Back to Details

codeagent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codeagent Wrapper Integration

Codeagent Wrapper 集成

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.
通过可插拔的AI后端（Codex、Claude、Gemini）执行codeagent-wrapper命令。支持通过
@
语法进行文件引用、可选择后端的并行任务执行，以及可配置的安全控制。

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):
bash
codeagent-wrapper --backend codex - [working_dir] <<'EOF'
<task content here>
EOF
With backend selection:
bash
codeagent-wrapper --backend claude - . <<'EOF'
<task content here>
EOF
Simple tasks:
bash
codeagent-wrapper --backend codex "simple task" [working_dir]
codeagent-wrapper --backend gemini "simple task" [working_dir]
HEREDOC语法（推荐）：
bash
codeagent-wrapper --backend codex - [working_dir] <<'EOF'
<任务内容>
EOF
指定后端：
bash
codeagent-wrapper --backend claude - . <<'EOF'
<任务内容>
EOF
简单任务：
bash
codeagent-wrapper --backend codex "简单任务" [working_dir]
codeagent-wrapper --backend gemini "简单任务" [working_dir]

Backends

后端

BackendCommandDescriptionBest For
codex
--backend codex
OpenAI Codex (default)Code analysis, complex development
claude
--backend claude
Anthropic ClaudeSimple tasks, documentation, prompts
gemini
--backend gemini
Google GeminiUI/UX prototyping
后端命令描述最佳适用场景
codex
--backend codex
OpenAI Codex（默认）代码分析、复杂开发
claude
--backend claude
Anthropic Claude简单任务、文档编写、提示词工程
gemini
--backend gemini
Google GeminiUI/UX原型设计

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
Codex（默认）：
  • 深度代码理解与复杂逻辑实现
  • 具备精确依赖追踪的大规模重构
  • 算法优化与性能调优
  • 示例："分析@src/core的调用图并重构模块依赖结构"
Claude：
  • 需求明确的快速功能实现
  • 技术文档、API规范、README生成
  • 专业提示词工程（如产品需求、设计规范）
  • 示例："为@package.json生成包含安装、使用和API文档的完整README"
Gemini：
  • UI组件脚手架与布局原型设计
  • 具备风格一致性的设计系统实现
  • 支持无障碍的交互元素生成
  • 示例："创建包含侧边栏导航和数据可视化卡片的响应式仪表板布局"
后端切换：
  • 先使用Codex进行分析，再切换到Claude编写文档，最后用Gemini实现UI
  • 在并行模式中为每个任务选择合适的后端，以优化任务执行效果

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
  • task
    （必填）：任务描述，支持
    @file
    引用
  • working_dir
    （可选）：工作目录（默认：当前目录）
  • --backend
    （必填）：选择AI后端（codex/claude/gemini）
    • 注意：仅当显式启用时，Claude后端才会添加
      --dangerously-skip-permissions

Return Format

返回格式

Agent response text here...

---
SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
Agent响应文本...

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

Resume Session

恢复会话

bash
undefined
bash
undefined

Resume with codex backend

使用codex后端恢复会话

codeagent-wrapper --backend codex resume <session_id> - <<'EOF' <follow-up task> EOF
codeagent-wrapper --backend codex resume <session_id> - <<'EOF' <后续任务> EOF

Resume with specific backend

使用指定后端恢复会话

codeagent-wrapper --backend claude resume <session_id> - <<'EOF' <follow-up task> EOF
undefined
codeagent-wrapper --backend claude resume <session_id> - <<'EOF' <后续任务> EOF
undefined

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:
bash
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).
默认（摘要模式 - 高效上下文）：
bash
codeagent-wrapper --parallel <<'EOF'
---TASK---
id: task1
backend: codex
workdir: /path/to/dir
---CONTENT---
任务内容
---TASK---
id: task2
dependencies: task1
---CONTENT---
依赖任务
EOF
完整输出模式（用于调试）：
bash
codeagent-wrapper --parallel --full-output <<'EOF'
...
EOF
输出模式：
  • 摘要（默认）：包含变更、输出、验证和审核摘要的结构化报告。
  • 完整（
    --full-output
    ）    ：完整的任务消息。仅在调试特定失败场景时使用。
指定任务后端：
bash
codeagent-wrapper --parallel <<'EOF'
---TASK---
id: task1
backend: codex
workdir: /path/to/dir
---CONTENT---
分析代码结构
---TASK---
id: task2
backend: claude
dependencies: task1
---CONTENT---
基于分析结果设计架构
---TASK---
id: task3
backend: gemini
dependencies: task2
---CONTENT---
生成实现代码
EOF
并发控制： 设置
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)
  • CODEX_TIMEOUT
    ：覆盖超时时间（毫秒，默认：7200000 = 2小时）
  • CODEAGENT_SKIP_PERMISSIONS
    ：控制Claude CLI权限检查
    • 对于Claude后端：设置为
      true
      /
      1
      以添加
      --dangerously-skip-permissions
      （默认：禁用）
    • 对于Codex/Gemini后端：当前无效果
  • CODEAGENT_MAX_PARALLEL_WORKERS
    ：限制并行模式下的并发任务数（默认：无限制，推荐：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
单任务：
Bash工具参数：
- command: codeagent-wrapper --backend <backend> - [working_dir] <<'EOF'
  <任务内容>
  EOF
- timeout: 7200000
- description: <简要描述>

注意：--backend为必填项（codex/claude/gemini）
并行任务：
Bash工具参数：
- command: codeagent-wrapper --parallel --backend <backend> <<'EOF'
  ---TASK---
  id: task_id
  backend: <backend>  # 可选，覆盖全局设置
  workdir: /path
  dependencies: dep1, dep2
  ---CONTENT---
  任务内容
  EOF
- timeout: 7200000
- description: <简要描述>

注意：全局--backend为必填项；任务级后端为可选

Critical Rules

重要规则

NEVER kill codeagent processes. Long-running tasks are normal. Instead:
  1. Check task status via log file:
    bash
    # 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:
    bash
    # Use TaskOutput tool with block=true and timeout
TaskOutput(task_id="<id>", block=true, timeout=300000)
  3. Check process without killing:
    bash
    ps aux | grep codeagent-wrapper | grep -v grep
Why: codeagent tasks often take 2-10 minutes. Killing them wastes API costs and loses progress.
切勿终止codeagent进程。长时间运行的任务属于正常情况。正确的做法是：
  1. 通过日志文件检查任务状态：
    bash
    # 查看实时输出
tail -f /tmp/claude/<workdir>/tasks/<task_id>.output

# 检查任务是否仍在运行
cat /tmp/claude/<workdir>/tasks/<task_id>.output | tail -50
  2. 带超时等待：
    bash
    # 使用TaskOutput工具并设置block=true和超时时间
TaskOutput(task_id="<id>", block=true, timeout=300000)
  3. 检查进程而不终止：
    bash
    ps aux | grep codeagent-wrapper | grep -v grep
原因：codeagent任务通常需要2-10分钟。终止进程会浪费API成本并丢失进度。

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
  • Claude后端：默认启用权限检查
    • 跳过检查：设置
      CODEAGENT_SKIP_PERMISSIONS=true
      或传递
      --skip-permissions
  • 并发限制：在生产环境中设置
    CODEAGENT_MAX_PARALLEL_WORKERS
    以防止资源耗尽
  • 自动化上下文：此Wrapper专为AI驱动的自动化场景设计，在这些场景中权限提示会阻塞执行

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
  • 所有模式（工作目录、恢复会话、并行）均支持多后端
  • 具备可配置权限检查的安全控制
  • 带有工作池和快速失败取消的并发限制