codeagent

Codeagent Wrapper 統合

概要

プラグイン可能な AI バックエンド（Codex、Claude、Gemini、OpenCode）、エージェントプリセット、自動検出されるスキルの注入、並列タスクのオーケストレーションを使って、codeagent-wrapper コマンドを実行します。デフォルトではバックグラウンドで実行し、作業を独立したタスクに分割できる場合は、常に --parallel を優先してください。

使用する場面

• 深い理解を必要とする複雑なコード分析
• 複数のファイルにまたがる大規模なリファクタリング
• マルチエージェントのオーケストレーション（調査 → 設計 → 実装 → レビュー）
• バックエンド／エージェントを選択して行う自動コード生成
• 依存関係を管理しながら行う並列タスク実行

クイックリファレンス

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

CLI フラグ

フラグ	説明	デフォルト
--backend <name>	バックエンド：codex、claude、gemini、opencode	codex
--agent <name>	エージェントプリセット（models.json または agents/ ディレクトリから選択）	なし
--model <name>	任意のバックエンドのモデルを上書き	バックエンドのデフォルト
--skills <names>	注入するスキル名をカンマ区切りで指定	自動検出
--reasoning-effort <level>	推論レベル：low、medium、high	バックエンドのデフォルト
--prompt-file <path>	カスタムプロンプトファイル（~/.claude または ~/.codeagent/agents/ 内に限定）	なし
--output <path>	構造化された JSON 出力をファイルに書き込む	なし
--worktree	隔離された git worktree で実行（ブランチ：do/{task_id}）	false
--skip-permissions	Claude バックエンドの権限確認をスキップ	false
--parallel	標準入力からの並列タスク実行を有効化	false
--full-output	並列実行の出力にメッセージ全文を含める（デフォルト：要約）	false
--config <path>	設定ファイルのパス	~/.codeagent/config.*
--cleanup	古いログをクリーンアップして終了	—
-v、--version	バージョンを表示して終了	—

バックエンド

バックエンド	フラグ	最適な用途
Codex	--backend codex（デフォルト）	深いコード分析、複雑なロジック、アルゴリズムの最適化、大規模なリファクタリング
Claude	--backend claude	ドキュメント、プロンプトエンジニアリング、要件が明確な機能
Gemini	--backend gemini	UI/UX のプロトタイピング、デザインシステムの実装
OpenCode	--backend opencode	軽量なタスク、最小限の機能セット

エージェントプリセット

エージェントプリセットは、バックエンド、モデル、プロンプト、ツール制御を再利用可能な名前にまとめたものです。選択するには --agent <name> を使用します。

参照元（次の順に確認）：

1. ~/.codeagent/models.json → agents.<name> オブジェクト
2. ~/.codeagent/agents/<name>.md → プロンプトとして使用される Markdown ファイル

エージェント設定フィールド（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"]
    }
  }
}

一般的なエージェントプリセット：

エージェント	目的	読み取り専用
code-explorer	コードを追跡し、アーキテクチャを整理し、パターンを見つける	はい
code-architect	アプローチ、ファイル計画、構築手順を設計する	はい
code-reviewer	バグ、シンプルさ、規約に照らしてレビューする	はい
develop	コードを実装し、テストを実行し、変更を加える	いいえ

スキルの注入

自動検出

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

手動での上書き

codeagent-wrapper --agent develop --skills golang-base-practices,frontend-design - . <<'EOF'
Implement full-stack feature...
EOF

スキルは ~/.claude/skills/{name}/SKILL.md から読み込まれ、YAML フロントマターを取り除いたうえで、タスクプロンプトに注入されます。

使用パターン

単一タスク（HEREDOC 推奨）

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

デフォルトの実行モードはバックグラウンドです。次のステップですぐに完全な応答が必要な場合にのみ、フォアグラウンドで実行してください。

フォアグラウンドで実行すると、codeagent-wrapper は最終回答の前に標準出力へ稼働状況フレームを出力します。

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

これらの行は進捗状況としてのみ扱ってください。進捗フレームが出力されている間は、「データが返されなかった」と判断したり、自分でタスクを開始したりしないでください。

エージェントプリセットを指定する場合

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

シンプルなタスク（短いプロンプトのみ）

codeagent-wrapper --backend codex "simple task description" [workdir]

標準入力の自動判定：タスクの長さが 800 文字を超える場合、または特殊文字（\n、\、"、'、`、$）を含む場合は、標準入力モードが自動的に使用されます。標準入力モードを明示的に指定するには、- を使用してください。

セッションの再開

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

ワークツリーによる分離

変更をメインブランチと分けておくため、分離された git ワークツリーで実行します。

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

ルール：

• 読み取り専用エージェント（code-explorer、code-architect、code-reviewer）では、ワークツリーは不要です
• 変更を行う場合、develop エージェントのみワークツリーが必要です

並列実行

複数ステップまたは複数エージェントの作業では、デフォルトで --parallel を使用してください。作業が本当に直線的である場合、または次のステップで現在のタスクの完全な出力が必要な場合にのみ、単一タスクモードに切り替えてください。

タスク設定フォーマット

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

タスクヘッダーのフィールド（id 以外はすべて省略可能）：

フィールド	説明
id	一意のタスク識別子（必須）
agent	エージェントプリセット名
workdir	作業ディレクトリ
backend	グローバルバックエンドの上書き
model	モデルの上書き
reasoning_effort	推論レベル
skills	スキル名をカンマ区切りで指定
dependencies	先に完了する必要があるタスク ID をカンマ区切りで指定
session_id	前のセッションを再開
skip_permissions	権限確認をスキップ（Claude バックエンド）
worktree	git ワークツリーで実行

マルチエージェントオーケストレーションの例

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

依存関係の解決

• タスクはトポロジカルソートされます（カーンのアルゴリズム）
• 循環依存は検出され、報告されます
• 親タスクが失敗すると、依存するタスクはスキップされます
• 同じレベルの独立したタスクは並行して実行されます

出力モード

要約（デフォルト）：タスクごとに、抽出されたフィールドを含む構造化レポートを出力します。

=== 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）：タスクのメッセージ全体を含めます。特定の失敗をデバッグする場合にのみ使用してください。

構造化 JSON 出力

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

次の内容が出力されます。

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

戻り値の形式

単一タスクの出力：

Agent response text here...

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

環境変数

変数	説明	デフォルト
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	Unicode の代わりに ASCII 記号（PASS/WARN/FAIL）を使用	false

設定ファイル：CLI フラグと同じキー（ケバブケース）を使用する ~/.codeagent/config.(yaml|yml|json|toml) をサポートしています。環境変数には CODEAGENT_ プレフィックスとアンダースコアを使用します。

終了コード

コード	意味
0	成功
1	一般エラー（引数不足、タスク失敗）
127	バックエンドコマンドが見つからない
130	中断（Ctrl+C）

呼び出しパターン

単一タスク：

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

並列タスク：

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>

重要なルール

codeagent のプロセスを絶対に終了させないでください。 長時間実行されるタスクは通常の動作です。デフォルトではバックグラウンドで実行し、コマンドの完了を待つのではなく、進捗状況を確認してください。

1. ログファイルでタスクの状態を確認する：

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

2. 独自にログを調べるより、ラッパーの進捗フレームを優先する： 標準出力に [codeagent-progress] ... が出力されている場合、タスクは稼働中であり、停止していません。

3. プロセスを終了させずに確認する：

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

理由： 終了させると API コストが無駄になり、進捗も失われます。

ツール制御（Claude バックエンド）

エージェントプリセットで Claude バックエンドを使用する場合は、利用可能なツールを制御します。

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

Claude CLI に --allowedTools と --disallowedTools として渡されます。明示的に列挙する必要があります（ワイルドカードは使用できません）。