Codeagent Wrapper Integration

Overview

Execute codeagent-wrapper commands with pluggable AI backends (Codex, Claude, Gemini). Supports file references via

@

When to Use

• Complex code analysis requiring deep understanding
• Large-scale refactoring across multiple files
• Automated code generation with backend selection

Usage

HEREDOC syntax (recommended):

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

With backend selection:

codeagent-wrapper --backend claude - <<'EOF'
<task content here>
EOF

Simple tasks:

codeagent-wrapper --backend codex "simple task" [working_dir]
codeagent-wrapper --backend gemini "simple task"

Backends

--backend codex

--backend claude

--backend gemini

Backend Selection Guide

Codex (default):

• Deep code understanding and complex logic implementation
• Large-scale refactoring with precise dependency tracking
• Algorithm optimization and performance tuning
• Example: "Analyze the call graph of @src/core and refactor the module dependency structure"

Claude:

• Quick feature implementation with clear requirements
• Technical documentation, API specs, README generation
• Professional prompt engineering (e.g., product requirements, design specs)
• Example: "Generate a comprehensive README for @package.json with installation, usage, and API docs"

Gemini:

• UI component scaffolding and layout prototyping
• Design system implementation with style consistency
• Interactive element generation with accessibility support
• Example: "Create a responsive dashboard layout with sidebar navigation and data visualization cards"

Backend Switching:

• Start with Codex for analysis, switch to Claude for documentation, then Gemini for UI implementation
• Use per-task backend selection in parallel mode to optimize for each task's strengths

Parameters

• task

  (required): Task description, supports

  @file

  references

• working_dir

  (optional): Working directory (default: current)

• --backend

  (required): Select AI backend (codex/claude/gemini)
  • Note: Claude backend only adds

    --dangerously-skip-permissions

    when explicitly enabled

Return Format

Agent response text here...

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

Resume Session

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

# Resume with specific backend
codeagent-wrapper --backend claude resume <session_id> - <<'EOF'
<follow-up task>
EOF

Parallel Execution

Default (summary mode - context-efficient):

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: task1
backend: codex
workdir: /path/to/dir
---CONTENT---
task content
---TASK---
id: task2
dependencies: task1
---CONTENT---
dependent task
EOF

Full output mode (for debugging):

codeagent-wrapper --parallel --full-output <<'EOF'
...
EOF

Output Modes:

• Summary (default): Structured report with changes, output, verification, and review summary.
• Full (

  --full-output

  ): Complete task messages. Use only when debugging specific failures.

With per-task backend:

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: task1
backend: codex
workdir: /path/to/dir
---CONTENT---
analyze code structure
---TASK---
id: task2
backend: claude
dependencies: task1
---CONTENT---
design architecture based on analysis
---TASK---
id: task3
backend: gemini
dependencies: task2
---CONTENT---
generate implementation code
EOF

Concurrency Control: Set

CODEAGENT_MAX_PARALLEL_WORKERS

Environment Variables

• CODEX_TIMEOUT

  : Override timeout in milliseconds (default: 7200000 = 2 hours)

• CODEAGENT_SKIP_PERMISSIONS

  : Control Claude CLI permission checks
  • For Claude backend: Set to

    true

    /

    1

    to add

    --dangerously-skip-permissions

    (default: disabled)
  • For Codex/Gemini backends: Currently has no effect

• CODEAGENT_MAX_PARALLEL_WORKERS

  : Limit concurrent tasks in parallel mode (default: unlimited, recommended: 8)

Invocation Pattern

Single Task:

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

Note: --backend is required (codex/claude/gemini)

Parallel Tasks:

Bash tool parameters:
- command: codeagent-wrapper --parallel --backend <backend> <<'EOF'
  ---TASK---
  id: task_id
  backend: <backend>  # Optional, overrides global
  workdir: /path
  dependencies: dep1, dep2
  ---CONTENT---
  task content
  EOF
- timeout: 7200000
- description: <brief description>

Note: Global --backend is required; per-task backend is optional

Critical Rules

NEVER kill codeagent processes. Long-running tasks are normal. Instead:

1. Check task status via log file:

   # View real-time output
   tail -f /tmp/claude/<workdir>/tasks/<task_id>.output
   
   # Check if task is still running
   cat /tmp/claude/<workdir>/tasks/<task_id>.output | tail -50
   

2. Wait with timeout:

   # Use TaskOutput tool with block=true and timeout
   TaskOutput(task_id="<id>", block=true, timeout=300000)
   

3. Check process without killing:

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

Why: codeagent tasks often take 2-10 minutes. Killing them wastes API costs and loses progress.

Security Best Practices

• Claude Backend: Permission checks enabled by default
  • To skip checks: set

    CODEAGENT_SKIP_PERMISSIONS=true

    or pass

    --skip-permissions

• Concurrency Limits: Set

  CODEAGENT_MAX_PARALLEL_WORKERS

  in production to prevent resource exhaustion
• Automation Context: This wrapper is designed for AI-driven automation where permission prompts would block execution

Recent Updates

• Multi-backend support for all modes (workdir, resume, parallel)
• Security controls with configurable permission checks
• Concurrency limits with worker pool and fail-fast cancellation