/codeagent

name: codeagent
description: Execute codeagent-wrapper for multi-backend AI code tasks. Supports Codex, Claude, Gemini, and OpenCode backends with agent presets, skill injection, file references (@syntax), worktree isolation, parallel execution, and structured output.

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. Default to background execution, and prefer `--parallel` whenever work can be split into independent tasks.

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

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

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 |

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

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

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

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

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:

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

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 c