codeagent（codeagent 搜索）

Codeagent Wrapper Integration

Overview

Execute codeagent-wrapper commands with pluggable AI backends (Codex, Claude, Gemini, OpenCode), agent presets, auto-detected skill injection, and parallel task orchestration. Supports session resume, git worktree isolation, and structured JSON output.

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

Quick Reference

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

CLI Flags

Backends

Agent Presets

Agent presets bundle backend, model, prompt, and tool control into a reusable name. Use --agent <name> to select.

Sources (checked in order):

1. ~/.codeagent/models.json → agents.<name> object
2. ~/.codeagent/agents/<name>.md → markdown file becomes the prompt

Agent config fields (in models.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:

Skill Injection

Auto-Detection

When --skills is not specified, skills are auto-detected from the working directory:

Manual Override

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.

Usage Patterns

Single Task (HEREDOC recommended)

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

With Agent Preset

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

Simple Task (short prompts only)

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.

Resume Session

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

# Or with agent preset
codeagent-wrapper --agent develop resume <session_id> - <<'EOF'
<follow-up task>
EOF

Worktree Isolation

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

# Create new worktree automatically (branch: do/{task_id})
codeagent-wrapper --agent develop --worktree - . <<'EOF'
Implement feature in isolation...
EOF

# Reuse existing worktree (set by /do workflow)
DO_WORKTREE_DIR=/path/to/worktree codeagent-wrapper --agent develop - . <<'EOF'
Continue work in existing worktree...
EOF

Rules:

• DO_WORKTREE_DIR env var takes precedence over --worktree
• Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need worktree
• Only develop agent needs worktree when making changes

Parallel Execution

Task Config Format

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

Multi-Agent Orchestration Example

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

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

Output Modes

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

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

### task_id PASS 92%
Did: Brief description of work done
Files: file1.ts, file2.ts
Tests: 12 passed
Log: /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.

Structured JSON Output

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

Produces:

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

Environment Variables

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.

Exit Codes

Invocation Pattern

Single Task:

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

With Worktree:

Bash tool parameters:
- command: DO_WORKTREE_DIR=<path> codeagent-wrapper --agent develop --skills <skills> - . <<'EOF'
  <task content>
  EOF
- timeout: 7200000
- description: <brief description>

Critical Rules

NEVER kill codeagent processes. Long-running tasks (2-10 minutes) are normal. Instead:

1. Check task status via log file: tail -f /tmp/claude/<workdir>/tasks/<task_id>.output
2. Wait with timeout: TaskOutput(task_id="<id>", block=true, timeout=300000)
3. Check process without killing: ps aux | grep codeagent-wrapper | grep -v grep

Why: Killing wastes API costs and loses progress.

Tool Control (Claude Backend)

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

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