codex-delegate

What this tool does

codex-delegate is a CLI that lets Codex agents spawn focused sub-agents for implementation, testing, review, or documentation tasks. It wraps @openai/codex-sdk, keeps the main context small, and provides concise summaries by default so you can delegate safely and return to the main thread quickly.

For more detail, see docs/codex-delegation.md. Release notes live in docs/release-notes.md.

Install from npm

Recommended: Node.js 22+.

1. Install the CLI globally from the public npm registry:

   npm install -g @h-arnold/codex-delegate

2. Run the CLI:

   codex-delegate --help

Install from GitHub Packages

If you prefer GitHub Packages, configure npm to use the GitHub registry for the scope and authenticate (ensure your personal access token includes read:packages, plus repo if the package is in a private repository):

npm config set @h-arnold:registry https://npm.pkg.github.com/
npm config set //npm.pkg.github.com/:_authToken=PERSONAL_ACCESS_TOKEN

Then install the CLI globally:

npm install -g @h-arnold/codex-delegate

Quick start

codex-delegate --role implementation --task "Add input validation to the assessor controller" --instructions "Use existing DTO patterns; update tests."

Initialise and add agent files

1. Initialise the .codex folder and default config:

   codex-delegate init

2. Add role templates (agent files) in .codex/<role>.md. For example:

   cat <<'EOF' > .codex/implementation.md
   You are an implementation-focused agent. Follow the repo style guide and update tests.
   EOF

3. Verify the roles are discovered:

   codex-delegate --list-roles

For a full list of configuration options and recommended settings, see docs/configuration.md.

Recommended AGENTS.md guidance

If you maintain a project-level AGENTS.md, add a short section so contributors know what this tool is, how to run it, and what to expect when it is working. This snippet includes guidance for Codex agents on how to use codex-delegate effectively:

## Codex delegation (codex-delegate)

````markdown
## Spawning sub-agents

Use `codex-delegate` to spawn a focused sub-agent for a specific task. Keep tasks small, pass constraints in `--instructions`, and set `--timeout-minutes` to 10 or more for long-running jobs.

Example:

```bash
codex-delegate --role implementation \
  --task "Add input validation to the assessor controller" \
  --instructions "Use existing DTO patterns; update tests." \
  --working-dir packages/my-app \
  --timeout-minutes 10
```

While a sub-agent is running, expect a heartbeat line (`agent is still working`) roughly every minute if no new stream events arrive.

**IMPORTANT**: Be patient. Some tasks will take several minutes and if the agent is thinking, you may not see any output for a while. If you see the heartbeat line, it is still working. If there is an error with the agent, `codex-delegate` will throw an error. If you stop it early, you may lose the work it has done so far. If you think it has stalled, check the logs for details `codex-delegate.log` (or set `--log-file` to write logs to a different path).

### Sub-agent roles

Sub-agent roles are defined in the `.codex` folder, along with the configuration file. To create a new role, add a markdown file with the role name (e.g. `implementation.md`) and a prompt template for that role. Empty files are ignored. Use `--list-roles` to see the discovered roles.
````

Creating new agents (roles)

Roles are defined by prompt templates in the .codex folder. To create a new agent:

1. Create a new file at .codex/<role>.md with the prompt template for that role.
2. Keep the template non-empty; empty files are ignored.
3. Run codex-delegate --list-roles to confirm it is discovered.
4. Invoke it with codex-delegate --role <role> --task "...".

AGENTS.md files inside .codex are ignored for role discovery.

Configuration (.codex)

The CLI uses a per-project .codex folder for both configuration and role templates.

• Config file: .codex/codex-delegate-config.json
• Role templates: .codex/<role>.md (ignored if empty)
• AGENTS.md is always ignored for role discovery

Run the init command to create the default config file, or let the CLI create it on first run:

codex-delegate init

Config defaults (stored when the file is first created) come from the CLI defaults:

• sandbox: danger-full-access
• approval: never
• network: true
• webSearch: live
• overrideWireApi: true
• verbose: false
• timeoutMinutes: 10

Role, task, and instructions are CLI-only and are never read from config files.

Config precedence is:

1. Built-in defaults
2. .codex/codex-delegate-config.json
3. CLI flags

Wire API note: codex-delegate overrides wire_api to responses by default. If you set overrideWireApi to false, ensure your Codex config.toml uses wire_api = "responses" or wire_api = "chat" to avoid startup errors. If responses_websocket is detected in config.toml, codex-delegate will isolate CODEX_HOME to a local .codex/codex-home folder to avoid the failure.

Development setup

• Husky is used for Git hooks. Hooks are installed automatically when contributors run npm install because of the prepare script: "prepare": "husky".
• To (re)initialise Husky locally: npm run husky:init (runs npx husky init).
• To add a hook: npx husky add .husky/<hook-name> "<command>" (e.g. npx husky add .husky/pre-commit "npx --no-install lint-staged").

Pre-commit runs lint-staged, which runs eslint --fix and prettier --write on staged files.

CI and containers

If you install only production dependencies in CI or Docker you may want to skip Husky there. Set HUSKY=0 or adapt the prepare script (see Husky docs).