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
•Multi-agent orchestration workflows (codex for code, gemini for UI, codex-review for review)

Usage

HEREDOC syntax (recommended):

bash

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

Sanity check (verify CLI is current):

bash

codeagent-wrapper --version
codeagent-wrapper --help

With backend selection:

bash

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

Simple tasks:

bash

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

Backends

Backend	Command	Description	Best For
codex	`--backend codex`	OpenAI Codex (default)	Code implementation, code review, complex analysis, orchestration
claude	`--backend claude`	Anthropic Claude	Simple tasks, documentation, prompts
gemini	`--backend gemini`	Google Gemini	UI/UX development, frontend components
opencode	`--backend opencode`	OpenCode CLI (`opencode run`)	Agent-driven runs, inner-loop orchestration decisions

⚠️ opencode backend does NOT support stdin input; prompts are passed as CLI args. Prefer short prompts + @path file references.

Backend Selection Guide

Codex (default, recommended for code + review):

•Deep code understanding and complex logic analysis
•Code review and quality assessment
•Orchestration and coordination tasks
•Example: "Review the implementation in @src/api for security issues and suggest improvements"

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 (recommended for UI):

•UI component scaffolding and layout prototyping
•Design system implementation with style consistency
•Interactive element generation with accessibility support
•Frontend development (React, Vue, HTML/CSS)
•Example: "Create a responsive dashboard layout with sidebar navigation and data visualization cards"

Multi-Agent Orchestration Pattern

For orchestrated workflows, use this backend assignment:

Task Type	Backend	Reason
Code Implementation	`codex`	Primary code implementation agent
UI/Frontend	`gemini`	Specialized for visual components
Code Review	`codex`	Deep analysis, quality assessment

Backend Switching:

•Use codex for code implementation, gemini for UI, codex for review
•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 only adds --dangerously-skip-permissions when explicitly enabled
•--skip-permissions / --dangerously-skip-permissions: For Claude backend only; disables permission prompts (use sparingly)
•--tmux-session (optional): Enable tmux visualization mode for parallel execution
•--tmux-attach (optional): Attach to tmux session after completion
•--tmux-no-main-window (optional): Remove default main window in tmux sessions
•--window-for (optional): Single-task mode only; route output to an existing task window
•--state-file (optional): Path to AGENT_STATE.json for real-time status updates
•--review (optional): Mark tasks as review tasks for state updates
•--cleanup: Remove old wrapper logs

Return Format

code

Agent response text here...

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

Resume Session

bash

# 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

Default (summary mode - context-efficient):

bash

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

bash

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 (orchestration pattern):

bash

codeagent-wrapper --parallel --tmux-session orch-session --state-file AGENT_STATE.json <<'EOF'
---TASK---
id: task1
backend: codex
workdir: /path/to/dir
target_window: backend
---CONTENT---
Implement user authentication module
---TASK---
id: task2
backend: gemini
workdir: /path/to/dir
target_window: frontend
---CONTENT---
Create login form component with validation
---TASK---
id: task3
backend: codex
dependencies: task1, task2
target_window: review
---CONTENT---
Review implementation for security issues
EOF

Task metadata fields:

•id: Unique task identifier (required)
•backend: AI backend to use (codex/claude/gemini)
•workdir: Working directory for the task
•dependencies: Comma-separated task IDs that must complete first
•target_window: tmux window name for grouping related tasks

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_ASCII_MODE: Use ASCII symbols instead of Unicode (PASS/WARN/FAIL)
•
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_OPENCODE_AGENT: OpenCode agent name (used by --backend opencode)
•CODEAGENT_OPENCODE_MODEL: OpenCode model name (used by --backend opencode)
•CODEAGENT_MAX_PARALLEL_WORKERS: Limit concurrent tasks in parallel mode (default: unlimited, recommended: 8)

🔒 CODEX_BYPASS_SANDBOX=true (Codex backend): bypasses approvals/sandbox in Codex CLI. Use only in trusted environments.

Invocation Pattern

Single Task:

code

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

Parallel Tasks:

code

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

•tmux integration: --tmux-session flag for visual parallel execution
•State file support: --state-file flag for AGENT_STATE.json real-time 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

Integration with Multi-Agent Orchestration

This skill integrates with the multi-agent-orchestrator skill for full orchestration workflows:

code

multi-agent-orchestrator
       │
       │ dispatch_batch.py
       ▼
codeagent-wrapper --parallel --tmux-session <session> --state-file AGENT_STATE.json
       │
       ├── codex (code tasks)
       ├── gemini (UI tasks)
       └── codex (review tasks)

See multi-agent-orchestrator skill for complete orchestration workflow.