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, OpenCode), agent presets, auto-detected skill injection, and parallel task orchestration. Default to background execution, and prefer

--parallel

whenever work can be split into independent tasks.

通过可插拔AI后端（Codex、Claude、Gemini、OpenCode）、Agent预设、自动检测技能注入和并行任务编排来运行

codeagent-wrapper

命令。默认以后台模式执行，当工作可拆分为独立任务时，优先使用

--parallel

参数。

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

需要深度理解的复杂代码分析
跨多文件的大规模重构
多Agent编排（探索→设计→实现→评审）
支持后端/Agent选择的自动化代码生成
带依赖管理的并行任务执行

Quick Reference

快速参考

codeagent-wrapper [flags] <task|-> [workdir]
codeagent-wrapper [flags] resume <session_id> <task|-> [workdir]
codeagent-wrapper --parallel [flags] < tasks_config

codeagent-wrapper [flags] <task|-> [workdir]
codeagent-wrapper [flags] resume <session_id> <task|-> [workdir]
codeagent-wrapper --parallel [flags] < tasks_config

CLI Flags

CLI 参数

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	—

参数	说明	默认值
`--backend <name>`	后端类型：codex、claude、gemini、opencode	codex
`--agent <name>`	Agent预设（来自models.json或agents/目录）	none
`--model <name>`	覆盖任意后端的模型	后端默认值
`--skills <names>`	要注入的技能名称（逗号分隔）	自动检测
`--reasoning-effort <level>`	推理级别：low、medium、high	后端默认值
`--prompt-file <path>`	自定义提示文件（仅限~/.claude或~/.codeagent/agents/目录下的文件）	none
`--output <path>`	将结构化JSON输出写入文件	none
`--worktree`	在独立的git工作树中执行（分支：do/{task_id}）	false
`--skip-permissions`	跳过Claude后端的权限提示	false
`--parallel`	启用从标准输入读取的并行任务执行	false
`--full-output`	在并行输出中包含完整消息（默认仅显示摘要）	false
`--config <path>`	配置文件路径	~/.codeagent/config.*
`--cleanup`	清理旧日志并退出	—
`-v` , `--version`	打印版本信息并退出	—

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

后端	参数	适用场景
Codex	`--backend codex` （默认）	深度代码分析、复杂逻辑、算法优化、大规模重构
Claude	`--backend claude`	文档编写、提示工程、需求明确的功能开发
Gemini	`--backend gemini`	UI/UX原型设计、设计系统实现
OpenCode	`--backend opencode`	轻量级任务、极简功能开发

Agent Presets

Agent预设

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

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

Agent预设将后端、模型、提示和工具控制打包为可复用的名称。使用

--agent <name>

来选择。

来源（按顺序查找）：

```
~/.codeagent/models.json
```
→
```
agents.<name>
```
对象
```
~/.codeagent/agents/<name>.md
```
→ Markdown文件将作为提示语

Agent配置字段（在models.json中）：

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"]
    }
  }
}

常用Agent预设：

Agent	用途	只读模式
`code-explorer`	追踪代码、映射架构、发现模式	是
`code-architect`	设计实现方案、文件规划、构建流程	是
`code-reviewer`	检查Bug、简洁性、编码规范	是
`develop`	实现代码、运行测试、修改代码	否

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`

当未指定

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

手动覆盖

bash

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.

bash

codeagent-wrapper --agent develop --skills golang-base-practices,frontend-design - . <<'EOF'
实现全栈功能...
EOF

技能从

~/.claude/skills/{name}/SKILL.md

加载，去除YAML前置内容后注入到任务提示中。

Usage Patterns

使用模式

Single Task (HEREDOC recommended)

单任务（推荐使用HEREDOC）

bash

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

Default execution mode is background. Run in foreground only when the next step requires the full response immediately.

When running in foreground,

codeagent-wrapper

emits liveness frames on stdout before the final answer:

text

[codeagent-progress] status=started ...
[codeagent-progress] status=streaming ...
[codeagent-progress] status=running ...
[codeagent-progress] status=completed ...

Treat these lines as progress only. Do not conclude "no data returned" and do not start doing the task yourself while progress frames are still arriving.

bash

codeagent-wrapper --backend codex - [workdir] <<'EOF'
<任务内容>
EOF

默认执行模式为后台模式。仅当下一步需要立即获取完整响应时，才使用前台模式。

在前台模式下，

codeagent-wrapper

会在输出最终答案前，在标准输出中发送存活状态帧：

text

[codeagent-progress] status=started ...
[codeagent-progress] status=streaming ...
[codeagent-progress] status=running ...
[codeagent-progress] status=completed ...

这些行仅作为进度提示。请勿认为“未返回数据”，也不要在进度帧仍在输出时自行开始处理任务。

With Agent Preset

使用Agent预设

bash

codeagent-wrapper --agent develop --skills golang-base-practices - . <<'EOF'
Implement the authentication middleware following existing patterns.
EOF

bash

codeagent-wrapper --agent develop --skills golang-base-practices - . <<'EOF'
遵循现有模式实现认证中间件。
EOF

Simple Task (short prompts only)

简单任务（仅适用于短提示）

bash

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.

bash

codeagent-wrapper --backend codex "简单任务描述" [workdir]

自动标准输入检测：当任务长度超过800字符或包含特殊字符（

\n

）时，将自动使用标准输入模式。使用

可强制启用标准输入模式。

Resume Session

恢复会话

bash

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

bash

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

Or with agent preset

或使用Agent预设

codeagent-wrapper --agent develop resume <session_id> - <<'EOF' <follow-up task> EOF

undefined

codeagent-wrapper --agent develop resume <session_id> - <<'EOF' <后续任务> EOF

undefined

Worktree Isolation

工作树隔离

Execute in an isolated git worktree to keep changes separate from the main branch:

bash

codeagent-wrapper --agent develop --worktree - . <<'EOF'
Implement feature in isolation...
EOF

Rules:

Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need worktree
Only
```
develop
```
agent needs worktree when making changes

在独立的git工作树中执行，使修改与主分支分离：

bash

codeagent-wrapper --agent develop --worktree - . <<'EOF'
在隔离环境中实现功能...
EOF

规则：

只读Agent（code-explorer、code-architect、code-reviewer）不需要工作树
只有
```
develop
```
Agent在修改代码时需要工作树

Parallel Execution

并行执行

Use

--parallel

by default for multi-step or multi-agent work. Fall back to single-task mode only when the work is truly linear or the next step depends on the full output of the current task.

对于多步骤或多Agent工作，默认使用

--parallel

。仅当工作确实是线性的，或者下一步依赖当前任务的完整输出时，才退回到单任务模式。

Task Config Format

任务配置格式

bash

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

bash

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: <唯一ID>
agent: <Agent名称>
workdir: <路径>
backend: <名称>
model: <模型名称>
reasoning_effort: <low|medium|high>
skills: <skill1>, <skill2>
dependencies: <id1>, <id2>
session_id: <ID>
skip_permissions: true|false
worktree: true|false
---CONTENT---
<任务内容>
EOF

任务头字段（除

id

外均为可选）：

字段	说明
`id`	唯一任务标识符（必填）
`agent`	Agent预设名称
`workdir`	工作目录
`backend`	覆盖全局后端设置
`model`	覆盖模型设置
`reasoning_effort`	推理级别
`skills`	技能名称（逗号分隔）
`dependencies`	必须先完成的任务ID（逗号分隔）
`session_id`	恢复之前的会话
`skip_permissions`	跳过权限提示（Claude后端）
`worktree`	在git工作树中执行

Multi-Agent Orchestration Example

多Agent编排示例

bash

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

bash

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: p1_architecture
agent: code-explorer
workdir: .
---CONTENT---
绘制认证子系统的架构图。返回：模块映射 + 带行号的关键文件。

---TASK---
id: p1_conventions
agent: code-explorer
workdir: .
---CONTENT---
识别测试模式、规范和配置。返回：测试命令 + 文件位置。

---TASK---
id: p2_design
agent: code-architect
workdir: .
dependencies: p1_architecture, p1_conventions
---CONTENT---
基于架构分析设计最小改动的实现方案。

---TASK---
id: p3_backend
agent: develop
workdir: .
skills: golang-base-practices
dependencies: p2_design
---CONTENT---
遵循设计方案实现后端修改。

---TASK---
id: p3_frontend
agent: develop
workdir: .
skills: vercel-react-best-practices,frontend-design
dependencies: p2_design
---CONTENT---
遵循设计方案实现前端修改。

---TASK---
id: p4_review
agent: code-reviewer
workdir: .
dependencies: p3_backend, p3_frontend
---CONTENT---
评审所有修改的正确性、边缘情况和KISS合规性。
将每个问题分类为BLOCKING或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

任务按拓扑排序（Kahn算法）
检测并报告循环依赖
父任务失败会导致依赖任务被跳过
同一层级的独立任务并发执行

Output Modes

输出模式

Summary (default): Structured report per task with extracted fields:

=== Execution Report ===
3 tasks | 2 passed | 1 failed

摘要（默认）：每个任务的结构化报告，包含提取的字段：

=== 执行报告 ===
3个任务 | 2个成功 | 1个失败

task_id PASS 92%

Did: Brief description of work done Files: file1.ts, file2.ts Tests: 12 passed Log: /tmp/codeagent-xxx.log

完成：已完成工作的简要描述文件：file1.ts, file2.ts 测试：12个通过日志：/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.

退出码：1 错误：断言失败详情：预期状态码200，实际得到401 日志：/tmp/codeagent-zzz.log


**完整输出**（`--full-output`）：包含完整的任务消息。仅用于调试特定失败场景。

Structured JSON Output

结构化JSON输出

bash

codeagent-wrapper --parallel --output results.json <<'EOF'
...
EOF

Produces:

json

{
  "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 }
}

bash

codeagent-wrapper --parallel --output results.json <<'EOF'
...
EOF

生成的内容：

json

{
  "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

单任务输出：

Agent响应文本...

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

Environment Variables

环境变量

Variable	Description	Default
`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
`CODEAGENT_TMPDIR`	Custom temp directory for executable scripts	system temp
`CODEAGENT_ASCII_MODE`	Use ASCII symbols (PASS/WARN/FAIL) instead of Unicode	false

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.

变量	说明	默认值
`CODEAGENT_SKIP_PERMISSIONS`	跳过Claude后端的权限提示（ `true` / `false` ）	true
`CODEX_BYPASS_SANDBOX`	控制Codex沙箱绕过（ `true` / `false` ）	true
`CODEAGENT_MAX_PARALLEL_WORKERS`	最大并发并行工作线程数（0=无限制，最大100）	0
`CODEAGENT_TMPDIR`	可执行脚本的自定义临时目录	系统临时目录
`CODEAGENT_ASCII_MODE`	使用ASCII符号（PASS/WARN/FAIL）替代Unicode	false

配置文件：支持

~/.codeagent/config.(yaml|yml|json|toml)

，包含与CLI参数相同的键（短横线命名）。环境变量使用

CODEAGENT_

前缀和下划线命名。

Exit Codes

退出码

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

代码	含义
`0`	成功
`1`	通用错误（缺少参数、任务失败）
`127`	未找到后端命令
`130`	被中断（Ctrl+C）

Invocation Pattern

调用模式

Single Task:

Bash tool parameters:
- command: codeagent-wrapper --agent <agent> --skills <skills> - [workdir] <<'EOF'
  <task content>
  EOF
- background: true
- 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
- background: true
- description: <brief description>

单任务:

Bash工具参数:
- command: codeagent-wrapper --agent <agent> --skills <skills> - [workdir] <<'EOF'
  <任务内容>
  EOF
- background: true
- description: <简要描述>

并行任务:

Bash工具参数:
- command: codeagent-wrapper --parallel <<'EOF'
  ---TASK---
  id: task_id
  agent: <agent>
  workdir: /path
  skills: <skill1>, <skill2>
  dependencies: dep1, dep2
  ---CONTENT---
  任务内容
  EOF
- background: true
- description: <简要描述>

Critical Rules

重要规则

NEVER kill codeagent processes. Long-running tasks are normal. Default to background execution and inspect progress instead of blocking on the command.

Check task status via log file:

bash

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

Prefer wrapper progress frames over ad-hoc log scraping: If stdout is still emitting
```
[codeagent-progress] ...
```
, the task is alive and has not stalled.

Check process without killing:

bash

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

Why: Killing wastes API costs and loses progress.

切勿终止codeagent进程。长时间运行的任务是正常的。默认使用后台执行模式，通过查看进度而非阻塞命令来监控任务状态。

通过日志文件检查任务状态:

bash

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

优先使用wrapper进度帧而非临时日志抓取: 如果标准输出仍在发送
```
[codeagent-progress] ...
```
，说明任务仍在运行，未停滞。

不终止进程的情况下检查状态:

bash

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

原因：终止进程会浪费API成本并丢失进度。

Tool Control (Claude Backend)

工具控制（Claude后端）

When using Claude backend with agent presets, control available tools:

json

{
  "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).

当使用Claude后端和Agent预设时，可控制可用工具：

json

{
  "agents": {
    "safe-develop": {
      "backend": "claude",
      "allowed_tools": ["Read", "Write", "Bash", "Grep", "Glob"],
      "disallowed_tools": ["WebFetch", "WebSearch"]
    }
  }
}

将作为

--allowedTools

和

--disallowedTools

参数传递给Claude CLI。仅支持显式枚举（不支持通配符）。