Codeagent Wrapper Integration

Overview

Execute codeagent-wrapper commands with pluggable AI backends (Codex, Claude, Gemini). Supports file references via @ syntax, parallel task execution with backend selection, and configurable security controls.

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 - [working_dir] <<'EOF'
<task content here>
EOF

With backend selection:

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

Simple tasks:

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

Backends

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 (optional): Select AI backend (codex/claude/gemini, default: codex)
  • Note: Claude backend defaults to --dangerously-skip-permissions for automation compatibility

Return Format

Agent response text here...

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

Resume Session

# Resume with default backend
codeagent-wrapper 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

With global backend:

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

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 to limit concurrent tasks (default: unlimited).

Environment Variables

• CODEX_TIMEOUT: Override timeout in milliseconds (default: 7200000 = 2 hours)
• CODEAGENT_SKIP_PERMISSIONS: Control permission checks
  • For Claude backend: Set to true/1 to disable --dangerously-skip-permissions (default: enabled)
  • For Codex/Gemini backends: Set to true/1 to enable permission skipping (default: disabled)
• 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>

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>

Security Best Practices

• Claude Backend: Defaults to --dangerously-skip-permissions for automation workflows
  • To enforce permission checks with Claude: Set CODEAGENT_SKIP_PERMISSIONS=true
• Codex/Gemini Backends: Permission checks enabled by default
• 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