agent-exec

agent-exec is a thin, agent-friendly wrapper around the Codex, Claude Code, and
Cursor CLIs. It runs the specified agent, forwards the prompt, and emits a JSON
summary of changes (including file contents) for downstream agents.

Requirements

- Node.js 18+
- One or more agent CLIs installed on your PATH (codex, claude, agent)

Install / Run

``bash
npx agent-exec "Add a healthcheck endpoint to the API" --agent codex
`

Pass extra args to the underlying CLI, including a model ID:

`bash
npx agent-exec "Refactor the auth flow" --agent claude --model claude-3.5-sonnet -- --max-tokens 2048
`

Skills

Install skills using the open agent skills ecosystem (via npx skills add):

`bash
npx skills add vercel-labs/agent-skills
`

You can also proxy the same command through agent-exec:

`bash
npx agent-exec skills add vercel-labs/agent-skills
`

How it works

- Requires an explicit agent selection (--agent or AGENT_EXEC_AGENT).
- Runs it in the chosen working directory.
- Emits a JSON summary of git status changes, including file contents.
- When output is JSON (or stdin is used), it defaults to headless agent flags:
- Codex: exec
- Claude: -p
- Cursor: --print

Options

`bash
agent-exec [options] -- [agent args...]
agent-exec skills

-a, --agent codex | claude | cursor (required)
-d, --dir working directory (default: cwd)
-m, --model model ID to pass to the agent CLI
-f, --format output format: json or text (default: json)
--input auto | arg | stdin | none (default: auto)
--max-bytes max bytes per file in JSON output (default: 1000000)
--content include file contents in JSON (default: true)
--no-content omit file contents in JSON
--list list detected agents and exit
-h, --help show help
`

Flags must come before the prompt. Use -- to pass flags directly to the agent CLI.

Output

By default the CLI emits a JSON summary suitable for Codex/Claude/Cursor agents:

`json
{
"ok": true,
"agent": "codex",
"command": "codex",
"args": [],
"cwd": "/path/to/repo",
"exitCode": 0,
"changes": [
{
"path": "src/index.ts",
"status": "M",
"content": "..."
}
]
}
`

Use --format text for human-friendly output.
Binary files are detected and reported with "binary": true without content.

Configuration

Environment variables for agent overrides:

`bash
AGENT_EXEC_AGENT=claude
AGENT_EXEC_FORMAT=json
AGENT_EXEC_INPUT=auto
AGENT_EXEC_MAX_BYTES=1000000
AGENT_EXEC_NO_CONTENT=1
AGENT_EXEC_MODEL_FLAG=--model
AGENT_EXEC_MODEL_FLAG_CODEX=--model
AGENT_EXEC_MODEL_FLAG_CLAUDE=--model
AGENT_EXEC_MODEL_FLAG_CURSOR=--model
AGENT_EXEC_CODEX_CMD=codex
AGENT_EXEC_CLAUDE_CMD=claude
AGENT_EXEC_CURSOR_CMD=agent
AGENT_EXEC_CODEX_ARGS="--foo {prompt}"
AGENT_EXEC_CLAUDE_ARGS="--bar {prompt}"
AGENT_EXEC_CURSOR_ARGS="--baz {prompt}"
`

Use {prompt} in args to substitute the prompt.

Legacy AGENT_RUN_* variables are also supported.

Cursor's CLI installs an agent binary by default. Set AGENT_EXEC_CURSOR_CMD=cursor
if your install uses a different command name.

Headless defaults apply for JSON/stdin output. Override per-agent defaults:

`bash
AGENT_EXEC_CODEX_ARGS="exec"
AGENT_EXEC_CLAUDE_ARGS="-p {prompt}"
AGENT_EXEC_CURSOR_ARGS="--print"
`

Set any AGENT_EXEC_*_ARGS to an empty string to disable the defaults.

Contributing

`bash
npm install
npm run build
npm run lint
``