codex-adapter — Claude Code skill: Codex task runner
The codex-adapter Claude Code skill hands one bounded, mechanical change to OpenAI Codex CLI. It activates on an explicit request to delegate a rename, config edit, or scripted replacement.
MIT ★ 26 updated 2026-11-16
npx skills add wrg32786/aigent-os --skill codex-adapter -a claude-codeWhat codex-adapter does
The skill sends Codex CLI one narrowly defined task, such as renaming files or applying a repetitive edit. The result should be easy to check in a diff. Codex CLI must be installed, and the task and working directory must be clear before invocation.
The wrapper script daemons/codex-adapter.sh runs codex exec in the chosen directory. It saves a run log, Git status, and a review diff; outside a Git repository, the changed files need direct inspection. The adapter never commits or pushes. Architecture choices, secrets, and production configuration are out of scope.
What it helps with
- delegate a batch file rename to Codex CLI
- edit a config file or add a
.gitignoreentry - repeat a clearly defined change across several files
- run lint fixes and inspect the resulting diff
Example prompts for the agent
- Hand Codex CLI the rename from
old-nametonew-nameinsrc. - Use Codex to add
*.tmpto.gitignore. - Delegate a scripted replacement across
srcto Codex and show me the diff for review.
How to install codex-adapter
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill codex-adapter -a claude-code2Manually: put the files in place
~/.claude/skills/codex-adapter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/codex-adapter/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill codex-adapter -a codex2Manually: put the files in place
.agents/skills/codex-adapter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill codex-adapter -a cursor2Manually: put the files in place
.cursor/skills/codex-adapter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/codex-adapter2Manually: put the files in place
.github/skills/codex-adapter/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill codex-adapter -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/codex-adapterManually: put the files in place
.devin/skills/codex-adapter/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill codex-adapter -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about codex-adapter
How do I install codex-adapter in Claude Code?
Run npx skills add wrg32786/aigent-os --skill codex-adapter -a claude-code. The skill file is placed at ~/.claude/skills/codex-adapter/SKILL.md.
What does codex-adapter do?
It passes one mechanical, checkable task to Codex CLI and saves a diff and Git status for review. It does not commit or push changes.
What does codex-adapter need to run?
Codex CLI must be installed and available as codex or through AIGENT_CODEX_BIN. The task and target directory must also be clear.
Source text
SKILL.md · MIT
--- name: codex-adapter description: "Route one mechanical task to OpenAI Codex CLI with review before merge. Use when explicitly asked to hand Codex a rename, config edit, or scripted replacement." allowed-tools: Read, Bash user-invocable: true triggers: - route this to codex - use codex for this - hand this to codex - run this through codex - codex exec - non-claude executor --- # Codex Adapter This is aigent-OS's first (and currently only) non-Claude executor: a thin wrapper around `daemons/codex-adapter.sh` that runs a single bounded, mechanical task through the [Codex CLI](https://developers.openai.com/codex)'s non-interactive `codex exec` mode. ## Scope -- what "bounded and mechanical" means Good fits: a scripted rename, a config/gitignore entry, a repetitive multi-file edit with a clear before/after, a lint-fix pass. The task prompt you hand it should be checkable by a human (or you) glancing at the resulting diff -- if you can't describe in one sentence what "done" looks like, it's not bounded enough for this adapter; do it yourself instead. Not a fit: architecture decisions, anything requiring judgment about tradeoffs, anything touching credentials/secrets/production config, anything the user hasn't explicitly asked to route to Codex. ## Before you invoke it 1. Confirm the Codex CLI is actually available: `command -v codex` (or whatever `AIGENT_CODEX_BIN` is set to). If it isn't installed, tell the user instead of guessing at a path. 2. State the bounded task in one sentence, and the target directory. If either is unclear, ask -- don't invoke on a guess. ## Invocation ```bash bash daemons/codex-adapter.sh "<bounded task prompt>" --dir <path> [--sandbox <mode>] ``` - `AIGENT_CODEX_BIN` (env, default `codex`) -- path or name of the Codex CLI binary. Never hardcode a machine-specific path in the invocation; set the env var if the binary isn't on `PATH`. - `--dir <path>` -- working directory the task runs in. Default: current directory. - `--sandbox <mode>` -- passed through to `codex exec --sandbox`. Default `workspace-write` (Codex may read/write inside `--dir`, nothing wider). Example: ```bash AIGENT_CODEX_BIN=codex bash daemons/codex-adapter.sh \ "Add a .gitignore entry for *.tmp files" --dir . ``` ## After it runs -- the review gate The adapter **never commits or pushes**. It writes: - `.aigent/codex-runs/<timestamp>/output.log` -- the raw Codex CLI transcript - `.aigent/codex-runs/<timestamp>/review.diff` -- a working-tree diff (tracked changes + a synthetic diff for any new untracked files) if `--dir` is a git repository - `.aigent/codex-runs/<timestamp>/status.txt` -- `git status --porcelain` for the same tree Read `review.diff` before doing anything else. Treat a Codex-produced change exactly like a sub-agent's diff: verify it does what was asked, then decide whether to stage/commit it yourself. If `--dir` isn't a git repository, the adapter says so explicitly and you review the files directly instead. ## What this is not Not a general multi-LLM router -- it's one task class routed to one executor. Extending this to route by task type, or to wire additional CLIs (Gemini CLI, opencode, etc.) behind the same interface, is future work, not something to imply is already live.
© wrg32786 · MIT · wrg32786/aigent-os