codeagent-wrapper

[English | 中文]

A unified CLI wrapper enabling multi-model collaboration across AI coding backends (Codex, Claude, Gemini, Opencode).

Core Value: Let different AI models work together - Claude for reasoning, Codex for implementation, Gemini for UI. One command, multiple backends, seamless collaboration.

Quick Start

# 1. Clone and install
git clone https://github.com/anthropics/codeagent-wrapper-node.git
cd codeagent-wrapper-node && npm link

# 2. Ensure at least one backend is installed (e.g., codex)
npm install -g @openai/codex

# 3. Run your first task
codeagent-wrapper --backend codex "List files in current directory"

# 4. Try multi-model collaboration
codeagent-wrapper --agent oracle "Analyze this codebase"   # Uses Claude
codeagent-wrapper --agent develop "Implement the feature"  # Uses Codex

Why codeagent-wrapper?

Challenge	Solution
Different CLI syntax for each AI tool	Unified command interface
Can't easily switch between models	`--backend` flag or `--agent` preset
No parallel execution across models	DAG-based parallel task execution
Context lost between sessions	Session resume with `resume <session_id>`

Multi-model collaboration example:

# Claude analyzes, Codex implements, Claude reviews
codeagent-wrapper --backend claude "Analyze the auth module design"
codeagent-wrapper --backend codex "Implement OAuth based on the analysis"
codeagent-wrapper --backend claude "Review the implementation"

Installation

# Clone and link
git clone https://github.com/anthropics/codeagent-wrapper-node.git
cd codeagent-wrapper-node
npm link

# Or run directly without installing
node bin/codeagent-wrapper.mjs <task>

# Install Claude Code skill (optional)
codeagent-wrapper init

Requirements

Node.js >= 18.0.0
One or more AI CLI backends installed:

Backend	Install Command	Documentation
`codex`	`npm install -g @openai/codex`	OpenAI Codex CLI
`claude`	`npm install -g @anthropic-ai/claude-code`	Anthropic Claude Code
`gemini`	`npm install -g @google/gemini-cli`	Google Gemini CLI
`opencode`	`npm install -g opencode`	Opencode CLI

Usage

Basic Usage

# Run a task with default backend (opencode)
codeagent-wrapper "Fix the bug in auth.js"

# Specify working directory
codeagent-wrapper "Add tests" ./src

# Use specific backend
codeagent-wrapper --backend claude "Review this code"

# Use specific model
codeagent-wrapper --backend claude --model claude-3-opus "Complex task"

Agent Configuration

Pre-configured agents for common use cases:

# Use predefined agent configuration
codeagent-wrapper --agent oracle "Analyze this codebase"
codeagent-wrapper --agent develop "Implement new feature"

Agent	Backend	Model	Best For
`oracle`	Claude	claude-opus-4-5	Complex analysis, architecture design
`librarian`	Claude	claude-sonnet-4-5	Documentation, code explanation
`explore`	Opencode	grok-code	Codebase exploration
`develop`	Codex	(default)	Code implementation, refactoring
`frontend-ui-ux-engineer`	Gemini	(default)	UI/UX design, prototyping
`document-writer`	Gemini	(default)	Technical documentation

Session Resume

Each execution outputs a SESSION_ID. Use it to continue a conversation:

# First run - note the SESSION_ID in output
codeagent-wrapper --backend codex "Start implementing auth"
# Output: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14

# Resume the session later
codeagent-wrapper resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 "Continue from where we left off"

Stdin Input

# Read task from stdin (use `-` as task placeholder)
echo "Build the project" | codeagent-wrapper -

# With working directory (- means stdin, ./workdir is the working directory)
echo "Run tests" | codeagent-wrapper - ./workdir

# Multi-line task via heredoc
codeagent-wrapper - <<'EOF'
Refactor the authentication module:
1. Extract common logic
2. Add error handling
3. Write unit tests
EOF

Real-time Progress Display

See what's happening during task execution with real-time progress updates:

# Normal execution - shows live progress
codeagent-wrapper "Analyze the authentication module"
# Output:
# ⏳ Task started
# 🔍 Analyzing...
# ⚡ Executing
# ✓ Task completed (12.3s)

# Disable progress output for scripts
codeagent-wrapper --quiet "Build the project"

# Or use environment variable
export CODEAGENT_QUIET=1
codeagent-wrapper "Run tests"

# Use ASCII mode for environments without emoji support
export CODEAGENT_ASCII_MODE=1
codeagent-wrapper "Deploy to production"
# Output:
# [*] Task started
# [?] Analyzing...
# [!] Executing
# [√] Task completed (8.7s)

Progress Stages:

⏳ Task started - Execution begins
🔍 Analyzing... - AI thinking/analyzing phase
⚡ Executing - Running tools/commands
✓ Task completed - Execution finished with total time

Note: Progress output is sent to stderr, while task output goes to stdout, allowing you to redirect them separately:

codeagent-wrapper "Build" 2>/dev/null  # Hide progress, show output only
codeagent-wrapper "Build" 1>/dev/null  # Hide output, show progress only

Parallel Execution

Run multiple tasks concurrently with dependency management:

# Run tasks in parallel (from file)
codeagent-wrapper --parallel < tasks.txt

# Or pipe directly
codeagent-wrapper --parallel <<'EOF'
---TASK---
id: analyze
backend: claude
---CONTENT---
Analyze the codebase structure

---TASK---
id: implement
backend: codex
dependencies: analyze
---CONTENT---
Implement based on analysis
EOF

# With full output (for debugging)
codeagent-wrapper --parallel --full-output < tasks.txt

Parallel Task Format

---TASK---
id: <unique_id>           # Required: unique task identifier
workdir: /path/to/dir     # Optional: working directory (default: cwd)
backend: codex            # Optional: backend override
model: gpt-4              # Optional: model override
agent: oracle             # Optional: use agent config
dependencies: id1, id2    # Optional: comma-separated task IDs to wait for
skip_permissions: true    # Optional: skip permission checks (true/false)
session_id: abc123        # Optional: resume from existing session
---CONTENT---
<task content here>

Task Field Reference

Field	Required	Default	Description
`id`	Yes	-	Unique task identifier
`workdir`	No	cwd	Working directory for the task
`backend`	No	(global)	Backend: codex, claude, gemini, opencode
`model`	No	(global)	Model to use
`agent`	No	-	Agent configuration name
`dependencies`	No	-	Comma-separated IDs of tasks to wait for
`skip_permissions`	No	false	Skip permission checks (true/false)
`session_id`	No	-	Resume from existing session

Other Commands

# Show help
codeagent-wrapper --help

# Show version
codeagent-wrapper --version

# Clean up old log files (>7 days)
codeagent-wrapper --cleanup

# Install codeagent skill to ~/.claude/skills/
codeagent-wrapper init
codeagent-wrapper init --force  # Overwrite without confirmation

Options

Option	Description
`--backend <name>`	Backend to use: `codex`, `claude`, `gemini`, `opencode`
`--model <model>`	Model to use (backend-specific)
`--agent <name>`	Agent configuration name (see Agent Configuration)
`--prompt-file <path>`	Path to custom prompt file
`--reasoning-effort <level>`	Reasoning effort level (model-specific)
`--skip-permissions`	Skip permission checks (YOLO mode)
`--yolo`	Alias for `--skip-permissions`
`--parallel`	Run tasks in parallel mode
`--full-output`	Show full output in parallel mode
`--timeout <seconds>`	Timeout in seconds (default: 7200 = 2 hours)
`--cleanup`	Clean up old log files
`--force`	Force overwrite without confirmation (for `init`)
`--help`, `-h`	Show help
`--version`, `-v`	Show version

Environment Variables

Variable	Description	Default
`CODEX_TIMEOUT`	Timeout value. If >10000, treated as milliseconds; otherwise seconds	7200 (seconds)
`CODEAGENT_SKIP_PERMISSIONS`	Skip permissions if set to any non-empty value	(unset)
`CODEAGENT_MAX_PARALLEL_WORKERS`	Max parallel workers. 0 = unlimited	min(100, cpuCount*4)
`CODEAGENT_ASCII_MODE`	Use ASCII symbols instead of Unicode if set	(unset)
`CODEAGENT_LOGGER_CLOSE_TIMEOUT_MS`	Logger close timeout in milliseconds	5000

Custom Agent Configuration

Run codeagent-wrapper init to create default config at ~/.codeagent/models.json.

Or create manually:

{
  "defaultBackend": "opencode",
  "defaultModel": "opencode/grok-code",
  "agents": {
    "my-agent": {
      "backend": "claude",
      "model": "claude-3-opus",
      "promptFile": "~/.claude/prompts/my-agent.md",
      "reasoningEffort": "high"
    }
  }
}

Agent Config Fields

Field	Description
`backend`	Backend to use
`model`	Model name
`promptFile`	Path to prompt file (supports `~` expansion)
`reasoningEffort`	Reasoning effort level

Prompt File Format

A prompt file is a plain text or markdown file containing system instructions:

# ~/.claude/prompts/my-agent.md

You are a senior software engineer specializing in TypeScript.

## Guidelines
- Follow SOLID principles
- Write comprehensive tests
- Use meaningful variable names

Logging & Debugging

Log Location

All execution logs are stored in:

~/.codeagent/logs/

Viewing Logs

# List recent logs
ls -lt ~/.codeagent/logs/ | head -10

# View a specific log
cat ~/.codeagent/logs/codeagent-<timestamp>.log

# Follow log in real-time (during execution)
tail -f ~/.codeagent/logs/codeagent-*.log

Cleanup

# Remove logs older than 7 days
codeagent-wrapper --cleanup

Troubleshooting

Issue	Solution
"Command not found: codex"	Install the backend: `npm install -g @openai/codex`
"Unknown agent: xyz"	Check available agents in `~/.codeagent/models.json`
Task hangs	Check `CODEX_TIMEOUT` env var; default is 2 hours
Permission errors	Use `--skip-permissions` or set `CODEAGENT_SKIP_PERMISSIONS=1`

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
124	Timeout
127	Command not found (backend not installed)
130	Interrupted (SIGINT/SIGTERM)

Architecture

bin/
  codeagent-wrapper.mjs  # CLI entry point
src/
  main.mjs               # Main orchestration
  config.mjs             # Configuration parsing
  executor.mjs           # Task execution engine
  backend.mjs            # Backend implementations (Codex, Claude, Gemini, Opencode)
  parser.mjs             # JSON stream parsing with auto-detection
  logger.mjs             # Async logging with buffered writes
  utils.mjs              # Utility functions
  filter.mjs             # Output filtering
  agent-config.mjs       # Agent configuration management
  signal.mjs             # Signal handling
  process-check.mjs      # Process utilities
  init.mjs               # Skill installation
templates/
  skills/codeagent/      # Claude Code skill template

Development

# Run tests
npm test

# Run specific test file
node --test test/config.test.mjs

# Run CLI directly
node bin/codeagent-wrapper.mjs "test task"

Migration from Go Version

This is a complete port of the Go codeagent-wrapper to Node.js with:

Identical CLI interface
Same exit codes
Same environment variables
Same configuration file format
Same parallel task format

Key differences:

Uses ESM modules (.mjs)
No external dependencies (uses Node.js built-ins only)
Async/await instead of goroutines

License

MIT

Name	Name	Last commit message	Last commit date
Latest commit History 19 Commits 19 Commits
bin	bin
openspec	openspec
src	src
templates/skills/codeagent	templates/skills/codeagent
test	test
.gitignore	.gitignore
AGENTS.md	AGENTS.md
CHANGELOG.md	CHANGELOG.md
README.md	README.md
README.zh-CN.md	README.zh-CN.md
package.json	package.json

Search code, repositories, users, issues, pull requests...

Folders and files

Latest commit

History

Repository files navigation

codeagent-wrapper

Quick Start

Why codeagent-wrapper?

Installation

Requirements

Usage

Basic Usage

Agent Configuration

Session Resume

Stdin Input

Real-time Progress Display

Parallel Execution

Parallel Task Format

Task Field Reference

Other Commands

Options

Environment Variables

Custom Agent Configuration

Agent Config Fields

Prompt File Format

Logging & Debugging

Log Location

Viewing Logs

Cleanup

Troubleshooting

Exit Codes

Architecture

Development

Migration from Go Version

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages