Codeagent Wrapper Integration Skill

Codeagent Wrapper Integration

Overview

Execute codeagent-wrapper commands with pluggable AI backends (Codex, Claude, Gemini, OpenCode), agent presets, auto-detected skill injection, and parallel task orchestration. Supports session resume, git worktree isolation, and structured JSON output.

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

| Flag | Description | Default | |------|-------------|---------| | --backend <name> | Backend: codex, claude, gemini, opencode | codex | | --agent <name> | Agent preset (from models.json or agents/ dir) | none | | --model <name> | Model override for any backend | backend default | | --skills <names> | Comma-separated skill names to inject | auto-detected | | --reasoning-effort <level> | Reasoning level: low, medium, high | backend default | | --prompt-file <path> | Custom prompt file (restricted to ~/.claude or ~/.codeagent/agents/) | none | | --output <path> | Write structured JSON output to file | none | | --worktree | Execute in isolated git worktree (branch: do/{task_id}) | false | | --skip-permissions | Skip Claude backend permission prompts | false | | --parallel | Enable parallel task execution from stdin | false | | --full-output | Include full messages in parallel output (default: summary) | false | | --config <path> | Config file path | ~/.codeagent/config.* | | --cleanup | Clean up old logs and exit | — | | -v, --version | Print version and exit | — |

Backends

| Backend | Flag | Best For | |---------|------|----------| | Codex | --backend codex (default) | Deep code analysis, complex logic, algorithm optimization, large-scale refactoring | | Claude | --backend claude | Documentation, prompt engineering, clear-requirement features | | Gemini | --backend gemini | UI/UX prototyping, design system implementation | | OpenCode | --backend opencode | Lightweight tasks, minimal feature set |

Agent Presets

Agent presets bundle backend, model, prompt, and tool control into a reusable name. Use --agent <name> to select.

Sources (checked in order):

~/.codeagent/models.json → agents.<name> object
~/.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:

| Agent | Purpose | Read-Only | |-------|---------|-----------| | code-explorer | Trace code, map architecture, find patterns | Yes | | code-architect | Design approaches, file plans, build sequences | Yes | | code-reviewer | Review for bugs, simplicity, conventions | Yes | | develop | Implement code, run tests, make changes | No |

Skill Injection

Auto-Detection

When --skills is not specified, skills are auto-detected from the working directory:

| Detected Files | Injected 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, stripped of YAML frontmatter, and injected into the task prompt.

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, \, ", ', `, $), stdin mode is used automatically. Use - to force stdin mode explicitly.

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):

| Field | Description | |-------|-------------| | id | Unique task identifier (required) | | agent | Agent preset name | | workdir | Working directory | | backend | Override global backend | | model | Override model | | reasoning_effort | Reasoning level | | skills | Comma-separated skill names | | dependencies | Comma-separated task IDs that must complete first | | session_id | Resume a previous session | | skip_permissions | Skip permission prompts (Claude backend) | | worktree | Execute in git 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): Complete task messages included. Use only for debugging specific failures.

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

| Variable | Description | Default | |----------|-------------|---------| | CODEX_TIMEOUT | Timeout in milliseconds | 7200000 (2 hours) | | CODEAGENT_SKIP_PERMISSIONS | Skip Claude backend permission prompts (true/false) | true | | CODEX_BYPASS_SANDBOX | Control Codex sandbox bypass (true/false) | true | | CODEAGENT_MAX_PARALLEL_WORKERS | Max concurrent parallel workers (0=unlimited, max 100) | 0 | | DO_WORKTREE_DIR | Reuse existing worktree path (set by /do workflow) | none | | CODEAGENT_TMPDIR | Custom temp directory for executable scripts | system temp | | CODEAGENT_ASCII_MODE | Use ASCII symbols (PASS/WARN/FAIL) instead of Unicode | false | | CODEAGENT_LOGGER_CLOSE_TIMEOUT_MS | Logger shutdown timeout in ms | 5000 |

Config file: Supports ~/.codeagent/config.(yaml|yml|json|toml) with the same keys as CLI flags (kebab-case). Env vars use CODEAGENT_ prefix with underscores.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error (missing args, failed task) | | 124 | Timeout | | 127 | Backend command not found | | 130 | Interrupted (Ctrl+C) |

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:

Check task status via log file:

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

Wait with timeout:

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

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 and --disallowedTools to Claude CLI. Explicit enumeration only (no wildcards).

Agent Skills: Codeagent Wrapper Integration

Install this agent skill to your local

Skill Files