Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill codex-adapter -a claude-code
Open on GitHub

What 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 .gitignore entry
  • 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-name to new-name in src.
  • Use Codex to add *.tmp to .gitignore.
  • Delegate a scripted replacement across src to 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-code

2Manually: put the files in place

~/.claude/skills/codex-adapter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codex-adapter/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set58

The whole set →
context-capsule The context-capsule Claude Code skill saves the current project state in a capsule for later work. Run it to checkpoint before risky changes, mark a completed milestone, or hand work to another session. CX Codex +1 ★ 26repo stars compact-note The compact-note Claude Code skill condenses long notes and logs while keeping the reasoning behind decisions. It runs on requests to shorten a note, log, or memory. CX Codex +1 ★ 26repo stars comms-summarize The comms-summarize Claude Code skill summarizes unread messages from an inbox, channel, or thread. It flags items that need action and separates them from FYI and stale messages. CX Codex +1 ★ 26repo stars cognitive-update The cognitive-update Claude Code skill updates goals, beliefs, self-model fields, and procedures from explicit evidence. It activates for cognitive or runtime state changes. CX Codex +1 ★ 26repo stars close This Claude Code skill saves session outcomes to durable memory and prepares a resume point. Run /close to wrap up work and update notes in vault/. CX Codex +1 ★ 26repo stars capsule-compact The capsule-compact Claude Code skill condenses long chains of context capsules. Run it on request or when a chain has grown too long. CX Codex +1 ★ 26repo stars brief This Claude Code skill drafts a structured brief for handing work to a sub-agent. It runs when a task needs to be assigned, handed off, or explained to another agent. CX Codex +1 ★ 26repo stars body-check The body-check Claude Code skill reads existing signals about context, memory, and pending work. It reports the current state and suggests a next action. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open