Codeagent Wrapper Integration

Overview

Execute

codeagent-wrapper

When to Use

• Complex code analysis requiring deep understanding
• Large-scale refactoring across multiple files
• Multi-agent orchestration (explore → design → implement → review)
• Automated code generation with backend/agent selection
• Parallel task execution with dependency management

Quick Reference

codeagent-wrapper [flags] <task|-> [workdir]
codeagent-wrapper [flags] resume <session_id> <task|-> [workdir]
codeagent-wrapper --parallel [flags] < tasks_config

CLI Flags

--backend <name>

--agent <name>

--model <name>

--skills <names>

--reasoning-effort <level>

--prompt-file <path>

--output <path>

--worktree

--skip-permissions

--parallel

--full-output

--config <path>

--cleanup

-v

--version

Backends

--backend codex

--backend claude

--backend gemini

--backend opencode

Agent Presets

Agent presets bundle backend, model, prompt, and tool control into a reusable name. Use

--agent <name>

Sources (checked in order):

1. ~/.codeagent/models.json

   →

   agents.<name>

   object

2. ~/.codeagent/agents/<name>.md

   → markdown file becomes the prompt

Agent config fields (in models.json):

{
  "agents": {
    "develop": {
      "backend": "codex",
      "model": "gpt-4.1",
      "prompt_file": "~/.codeagent/prompts/develop.md",
      "reasoning": "high",
      "yolo": true,
      "allowed_tools": ["Read", "Write", "Bash"],
      "disallowed_tools": ["WebFetch"]
    }
  }
}

Common agent presets:

code-explorer

code-architect

code-reviewer

develop

Skill Injection

Auto-Detection

When

--skills

go.mod

go.sum

golang-base-practices

Cargo.toml

rust-best-practices

pyproject.toml

setup.py

requirements.txt

python-best-practices

package.json

vercel-react-best-practices

frontend-design

vue.config.js

vite.config.ts

nuxt.config.ts

vue-web-app

Manual Override

codeagent-wrapper --agent develop --skills golang-base-practices,frontend-design - . <<'EOF'
Implement full-stack feature...
EOF

Skills are loaded from

~/.claude/skills/{name}/SKILL.md

Usage Patterns

Single Task (HEREDOC recommended)

codeagent-wrapper --backend codex - [workdir] <<'EOF'
<task content here>
EOF

With Agent Preset

codeagent-wrapper --agent develop --skills golang-base-practices - . <<'EOF'
Implement the authentication middleware following existing patterns.
EOF

Simple Task (short prompts only)

codeagent-wrapper --backend codex "simple task description" [workdir]

Auto-stdin detection: When task length exceeds 800 characters or contains special characters (

\n

\

"

'

`

$

-

Resume Session

codeagent-wrapper --backend codex resume <session_id> - <<'EOF'
<follow-up task>
EOF

# Or with agent preset
codeagent-wrapper --agent develop resume <session_id> - <<'EOF'
<follow-up task>
EOF

Worktree Isolation

Execute in an isolated git worktree to keep changes separate from the main branch:

# Create new worktree automatically (branch: do/{task_id})
codeagent-wrapper --agent develop --worktree - . <<'EOF'
Implement feature in isolation...
EOF

# Reuse existing worktree (set by /do workflow)
DO_WORKTREE_DIR=/path/to/worktree codeagent-wrapper --agent develop - . <<'EOF'
Continue work in existing worktree...
EOF

Rules:

• DO_WORKTREE_DIR

  env var takes precedence over

  --worktree

• Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need worktree
• Only

  develop

  agent needs worktree when making changes

Parallel Execution

Task Config Format

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: <unique_id>
agent: <agent_name>
workdir: <path>
backend: <name>
model: <model_name>
reasoning_effort: <low|medium|high>
skills: <skill1>, <skill2>
dependencies: <id1>, <id2>
session_id: <id>
skip_permissions: true|false
worktree: true|false
---CONTENT---
<task content>
EOF

Task header fields (all optional except

id

id

agent

workdir

backend

model

reasoning_effort

skills

dependencies

session_id

skip_permissions

worktree

Multi-Agent Orchestration Example

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: p1_architecture
agent: code-explorer
workdir: .
---CONTENT---
Map architecture for the authentication subsystem. Return: module map + key files with line numbers.

---TASK---
id: p1_conventions
agent: code-explorer
workdir: .
---CONTENT---
Identify testing patterns, conventions, config. Return: test commands + file locations.

---TASK---
id: p2_design
agent: code-architect
workdir: .
dependencies: p1_architecture, p1_conventions
---CONTENT---
Design minimal-change implementation plan based on architecture analysis.

---TASK---
id: p3_backend
agent: develop
workdir: .
skills: golang-base-practices
dependencies: p2_design
---CONTENT---
Implement backend changes following the design plan.

---TASK---
id: p3_frontend
agent: develop
workdir: .
skills: vercel-react-best-practices,frontend-design
dependencies: p2_design
---CONTENT---
Implement frontend changes following the design plan.

---TASK---
id: p4_review
agent: code-reviewer
workdir: .
dependencies: p3_backend, p3_frontend
---CONTENT---
Review all changes for correctness, edge cases, and KISS compliance.
Classify each issue as BLOCKING or MINOR.
EOF

Dependency Resolution

• Tasks are topologically sorted (Kahn's algorithm)
• Circular dependencies are detected and reported
• Failed parent tasks cause dependent tasks to be skipped
• Independent tasks at the same level run concurrently

Output Modes

Summary (default): Structured report per task with extracted fields:

=== Execution Report ===
3 tasks | 2 passed | 1 failed

### task_id PASS 92%
Did: Brief description of work done
Files: file1.ts, file2.ts
Tests: 12 passed
Log: /tmp/codeagent-xxx.log

### task_id FAIL
Exit code: 1
Error: Assertion failed
Detail: Expected status 200 but got 401
Log: /tmp/codeagent-zzz.log

Full output (

--full-output

Structured JSON Output

codeagent-wrapper --parallel --output results.json <<'EOF'
...
EOF

Produces:

{
  "results": [
    {
      "task_id": "task_1",
      "exit_code": 0,
      "message": "...",
      "session_id": "...",
      "coverage": "92%",
      "files_changed": ["file.ts"],
      "tests_passed": 12,
      "log_path": "/tmp/..."
    }
  ],
  "summary": { "total": 3, "success": 2, "failed": 1 }
}

Return Format

Single task output:

Agent response text here...

---
SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14

Environment Variables

CODEX_TIMEOUT

CODEAGENT_SKIP_PERMISSIONS

true

false

CODEX_BYPASS_SANDBOX

true

false

CODEAGENT_MAX_PARALLEL_WORKERS

DO_WORKTREE_DIR

CODEAGENT_TMPDIR

CODEAGENT_ASCII_MODE

CODEAGENT_LOGGER_CLOSE_TIMEOUT_MS

Config file: Supports

~/.codeagent/config.(yaml|yml|json|toml)

CODEAGENT_

Exit Codes

0

1

124

127

130

Invocation Pattern

Single Task:

Bash tool parameters:
- command: codeagent-wrapper --agent <agent> --skills <skills> - [workdir] <<'EOF'
  <task content>
  EOF
- timeout: 7200000
- description: <brief description>

Parallel Tasks:

Bash tool parameters:
- command: codeagent-wrapper --parallel <<'EOF'
  ---TASK---
  id: task_id
  agent: <agent>
  workdir: /path
  skills: <skill1>, <skill2>
  dependencies: dep1, dep2
  ---CONTENT---
  task content
  EOF
- timeout: 7200000
- description: <brief description>

With Worktree:

Bash tool parameters:
- command: DO_WORKTREE_DIR=<path> codeagent-wrapper --agent develop --skills <skills> - . <<'EOF'
  <task content>
  EOF
- timeout: 7200000
- description: <brief description>

Critical Rules

NEVER kill codeagent processes. Long-running tasks (2-10 minutes) are normal. Instead:

1. Check task status via log file:

   tail -f /tmp/claude/<workdir>/tasks/<task_id>.output
   

2. Wait with timeout:

   TaskOutput(task_id="<id>", block=true, timeout=300000)
   

3. Check process without killing:

   ps aux | grep codeagent-wrapper | grep -v grep
   

Why: Killing wastes API costs and loses progress.

Tool Control (Claude Backend)

When using Claude backend with agent presets, control available tools:

{
  "agents": {
    "safe-develop": {
      "backend": "claude",
      "allowed_tools": ["Read", "Write", "Bash", "Grep", "Glob"],
      "disallowed_tools": ["WebFetch", "WebSearch"]
    }
  }
}

Passed as

--allowedTools

--disallowedTools