myclaude/codeagent-wrapper

codeagent-wrapper

English | 中文

A multi-backend AI code agent CLI wrapper written in Go. Provides a unified CLI entry point wrapping different AI tool backends (Codex / Claude / Gemini / OpenCode) with consistent flags, configuration, skill injection, and session resumption.

Entry point: cmd/codeagent-wrapper/main.go (binary: codeagent-wrapper).

Features

• Multi-backend support: codex / claude / gemini / opencode
• Unified CLI: codeagent-wrapper [flags] <task> / codeagent-wrapper resume <session_id> <task> [workdir]
• Auto stdin: Automatically pipes via stdin when task contains newlines, special characters, or exceeds length; also supports explicit -
• Config merging: Config files + CODEAGENT_* environment variables (viper)
• Agent presets: Read backend/model/prompt/reasoning/yolo/allowed_tools from ~/.codeagent/models.json
• Dynamic agents: Place a {name}.md prompt file in ~/.codeagent/agents/ to use as an agent
• Skill auto-injection: --skills for manual specification, or auto-detect from project tech stack (Go/Rust/Python/Node.js/Vue)
• Git worktree isolation: --worktree executes tasks in an isolated git worktree with auto-generated task_id and branch
• Parallel execution: --parallel reads multi-task config from stdin with dependency-aware topological concurrent execution and structured summary reports
• Backend config: backends section in models.json supports per-backend base_url / api_key injection
• Claude tool control: allowed_tools / disallowed_tools to restrict available tools for Claude backend
• Stderr noise filtering: Automatically filters noisy stderr output from Gemini and Codex backends
• Log cleanup: codeagent-wrapper cleanup cleans old logs (logs written to system temp directory)
• Cross-platform: macOS / Linux / Windows

Installation

Recommended (interactive installer)

npx github:cexll/myclaude

Select the codeagent-wrapper module to install.

Manual build

Requires: Go 1.21+.

# Build from source
make build

# Or install to $GOPATH/bin
make install

Verify installation:

codeagent-wrapper --version

Usage

Basic usage (default backend: codex):

codeagent-wrapper "analyze the entry logic of internal/app/cli.go"

Specify backend:

codeagent-wrapper --backend claude "explain the parallel config format in internal/executor/parallel_config.go"

Specify working directory (2nd positional argument):

codeagent-wrapper "search for potential data races in this repo" .

Explicit stdin (using -):

cat task.txt | codeagent-wrapper -

HEREDOC (recommended for multi-line tasks):

codeagent-wrapper --backend claude - <<'EOF'
Implement user authentication:
- JWT tokens
- bcrypt password hashing
- Session management
EOF

Resume session:

codeagent-wrapper resume <session_id> "continue the previous task"

Execute in isolated git worktree:

codeagent-wrapper --worktree "refactor the auth module"

Manual skill injection:

codeagent-wrapper --skills golang-base-practices "optimize database queries"

Parallel mode (task config from stdin):

codeagent-wrapper --parallel <<'EOF'
---TASK---
id: t1
workdir: .
backend: codex
---CONTENT---
List the main modules and their responsibilities.
---TASK---
id: t2
dependencies: t1
backend: claude
---CONTENT---
Based on t1's findings, identify refactoring risks and suggestions.
EOF

CLI Flags

Flag	Description
--backend <name>	Backend selection (codex/claude/gemini/opencode)
--model <name>	Model override
--agent <name>	Agent preset name (from models.json or ~/.codeagent/agents/)
--prompt-file <path>	Read prompt from file
--skills <names>	Comma-separated skill names for spec injection
--reasoning-effort <level>	Reasoning effort (backend-specific)
--skip-permissions	Skip permission prompts
--dangerously-skip-permissions	Alias for --skip-permissions
--worktree	Execute in a new git worktree (auto-generates task_id)
--parallel	Parallel task mode (config from stdin)
--full-output	Full output in parallel mode (default: summary only)
--config <path>	Config file path (default: $HOME/.codeagent/config.*)
--version, -v	Print version
--cleanup	Clean up old logs

Configuration

Config File

Default search path (when --config is empty):

• $HOME/.codeagent/config.(yaml|yml|json|toml|...)

Example (YAML):

backend: codex
model: gpt-4.1
skip-permissions: false

Can also be specified explicitly via --config /path/to/config.yaml.

Environment Variables (CODEAGENT_*)

Read via viper with automatic - to _ mapping:

Variable	Description
CODEAGENT_BACKEND	Backend name (codex/claude/gemini/opencode)
CODEAGENT_MODEL	Model name
CODEAGENT_AGENT	Agent preset name
CODEAGENT_PROMPT_FILE	Prompt file path
CODEAGENT_REASONING_EFFORT	Reasoning effort
CODEAGENT_SKIP_PERMISSIONS	Skip permission prompts (default true; set false to disable)
CODEAGENT_FULL_OUTPUT	Full output in parallel mode
CODEAGENT_MAX_PARALLEL_WORKERS	Parallel worker count (0=unlimited, max 100)
CODEAGENT_TMPDIR	Custom temp directory (for macOS permission issues)
CODEX_TIMEOUT	Timeout in ms (default 7200000 = 2 hours)
CODEX_BYPASS_SANDBOX	Codex sandbox bypass (default true; set false to disable)
DO_WORKTREE_DIR	Reuse existing worktree directory (set by /do workflow)

Agent Presets (~/.codeagent/models.json)

{
  "default_backend": "codex",
  "default_model": "gpt-4.1",
  "backends": {
    "codex": { "api_key": "..." },
    "claude": { "base_url": "http://localhost:23001", "api_key": "..." }
  },
  "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"]
    }
  }
}

Use --agent <name> to select a preset. Agents inherit base_url / api_key from the corresponding backends entry.

Dynamic Agents

Place a {name}.md file in ~/.codeagent/agents/ to use it via --agent {name}. The Markdown file is read as the prompt, using default_backend and default_model.

Skill Auto-Detection

When no skills are specified via --skills, codeagent-wrapper auto-detects the tech stack from files in 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

Skill specs are read from ~/.claude/skills/{name}/SKILL.md, subject to a 16000-character budget.

Supported Backends

This project does not embed model capabilities. It requires the corresponding CLI tools installed and available in PATH:

Backend	Command	Notes
codex	codex e ...	Adds --dangerously-bypass-approvals-and-sandbox by default; set CODEX_BYPASS_SANDBOX=false to disable
claude	claude -p ... --output-format stream-json	Skips permissions and disables setting-sources to prevent recursion; set CODEAGENT_SKIP_PERMISSIONS=false to enable prompts; auto-reads env and model from ~/.claude/settings.json
gemini	gemini -o stream-json -y ...	Auto-loads env vars from ~/.gemini/.env (GEMINI_API_KEY, GEMINI_MODEL, etc.)
opencode	opencode run --format json	—

Project Structure

cmd/codeagent-wrapper/main.go   # CLI entry point
internal/
  app/          # CLI command definitions, argument parsing, main orchestration
  backend/      # Backend abstraction and implementations (codex/claude/gemini/opencode)
  config/       # Config loading, agent resolution, viper bindings
  executor/     # Task execution engine: single/parallel/worktree/skill injection
  logger/       # Structured logging system
  parser/       # JSON stream parser
  utils/        # Common utility functions
  worktree/     # Git worktree management

Development

make build    # Build binary
make test     # Run tests
make lint     # golangci-lint + staticcheck
make clean    # Clean build artifacts
make install  # Install to $GOPATH/bin

CI uses GitHub Actions with Go 1.21 / 1.22 matrix testing.

Troubleshooting

• On macOS, if you see permission denied related to temp directories, set: CODEAGENT_TMPDIR=$HOME/.codeagent/tmp
• claude backend's base_url / api_key (from ~/.codeagent/models.json backends.claude) are injected as ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY env vars
• gemini backend's API key is loaded from ~/.gemini/.env, injected as GEMINI_API_KEY with GEMINI_API_KEY_AUTH_MECHANISM=bearer auto-set
• Exit codes: 127 = backend not found, 124 = timeout, 130 = interrupted
• Parallel mode outputs structured summary by default; use --full-output for complete output when debugging