コーディングエージェント (bash-first)

コーディングエージェント関連のすべての作業に bash (オプションでバックグラウンドモード)を使用します。シンプルで効果的です。

⚠️ PTY モード必須!

コーディングエージェント (Codex、Claude Code、Pi) は インタラクティブターミナルアプリケーション であり、正しく動作するには疑似ターミナル (PTY) が必要です。PTY なしでは、出力が壊れたり、色が失われたり、エージェントがハングする可能性があります。

コーディングエージェントを実行する際は常に pty:true を使用してください:

# ✅ 正しい - PTY 付き
bash pty:true command:"codex exec 'Your prompt'"

# ❌ 間違い - PTY なし、エージェントが破損する可能性
bash command:"codex exec 'Your prompt'"

Bash ツールパラメータ

パラメータ	型	説明
command	string	実行するシェルコマンド
pty	boolean	コーディングエージェント用! インタラクティブ CLI 用に疑似ターミナルを割り当てます
workdir	string	作業ディレクトリ (エージェントはこのフォルダのコンテキストのみを参照)
background	boolean	バックグラウンドで実行、監視用に sessionId を返します
timeout	number	タイムアウト時間 (秒単位、期限切れでプロセスを強制終了)
elevated	boolean	サンドボックスではなくホスト上で実行 (許可されている場合)

プロセスツールアクション (バックグラウンドセッション用)

アクション	説明
list	実行中/最近のセッションをすべてリストアップ
poll	セッションがまだ実行中かどうか確認
log	セッション出力を取得 (オプションでオフセット/制限付き)
write	stdin に未処理データを送信
submit	データ + 改行を送信 (入力してEnterを押すような動作)
send-keys	キートークンまたは 16 進数バイトを送信
paste	テキストを貼り付け (オプションでブラケットモード付き)
kill	セッションを終了

---

クイックスタート: ワンショットタスク

クイックプロンプト/チャットの場合、一時 git リポジトリを作成して実行します:

# クイックチャット (Codex は git リポジトリが必要!)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"

# または実際のプロジェクトで - PTY 付き!
bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"

git init が必要な理由? Codex は信頼できる git ディレクトリ外では実行されません。一時リポジトリを作成することでスクラッチワーク用のこの問題を解決します。

---

パターン: workdir + background + pty

より長いタスクの場合、PTY 付きのバックグラウンドモードを使用します:

# ターゲットディレクトリでエージェントを開始 (PTY 付き!)
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
# 追跡用に sessionId を返します

# 進捗を監視
process action:log sessionId:XXX

# 完了したか確認  
process action:poll sessionId:XXX

# 入力を送信 (エージェントが質問をした場合)
process action:write sessionId:XXX data:"y"

# Enter 付きで送信 (「yes」と入力して Enter を押すような動作)
process action:submit sessionId:XXX data:"yes"

# 必要に応じて強制終了
process action:kill sessionId:XXX

workdir が重要な理由: エージェントは焦点を絞ったディレクトリで起動し、関連のないファイル (soul.md のような 😅) を読むために彷徨き歩きません。

---

Codex CLI

モデル: gpt-5.2-codex がデフォルト (~/.codex/config.toml で設定)

フラグ

フラグ	効果
exec "prompt"	ワンショット実行、完了時に終了
--full-auto	サンドボックス化されていますが、ワークスペース内で自動承認
--yolo	サンドボックスなし、承認なし (最速、最も危険)

ビルド/作成

# クイックワンショット (自動承認) - PTY を忘れずに!
bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"

# より長い作業用のバックグラウンド
bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"

PR レビュー

⚠️ 重要: Clawdbot 独自のプロジェクトフォルダで PR をレビューしないでください! 一時フォルダにクローンするか、git worktree を使用してください。

# 安全なレビュー用に一時フォルダにクローン
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
# 後でクリーンアップ: trash $REVIEW_DIR

# または git worktree を使用 (main を保持)
git worktree add /tmp/pr-130-review pr-130-branch
bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"

バッチ PR レビュー (パラレル軍団!)

# まず PR リファレンスをすべて取得
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# 軍団をデプロイ - PR ごとに 1 つの Codex (すべて PTY 付き!)
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

# すべてを監視
process action:list

# 結果を GitHub に投稿
gh pr comment <PR#> --body "<review content>"

---

Claude Code

# 適切なターミナル出力用に PTY 付き
bash pty:true workdir:~/project command:"claude 'Your task'"

# バックグラウンド
bash pty:true workdir:~/project background:true command:"claude 'Your task'"

---

OpenCode

bash pty:true workdir:~/project command:"opencode run 'Your task'"

---

Pi コーディングエージェント

# インストール: npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:"pi 'Your task'"

# 非インタラクティブモード (PTY は依然として推奨)
bash pty:true command:"pi -p 'Summarize src/'"

# 異なるプロバイダー/モデル
bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"

注: Pi には現在 Anthropic プロンプトキャッシュが有効化されています (PR #584、2026 年 1 月マージ)!

---

git worktrees を使用したパラレルイシュー修正

複数のイシューをパラレルで修正する場合、git worktrees を使用します:

# 1. 各イシュー用に worktree を作成
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. 各フォルダで Codex を起動 (バックグラウンド + PTY!)
bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'"

# 3. 進捗を監視
process action:list
process action:log sessionId:XXX

# 4. 修正後に PR を作成
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 5. クリーンアップ
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

---

⚠️ ルール

1. 常に pty:true を使用 — コーディングエージェントはターミナルが必要!
2. ツール選択を尊重 — ユーザーが Codex を求めた場合は Codex を使用。自分で構築することは決して提案しない!
3. 忍耐強く — セッションが「遅い」という理由で強制終了しない
4. process:log で監視 — 干渉せずに進捗を確認
5. ビルド用に --full-auto — 変更を自動承認
6. レビュー用にバニラ — 特別なフラグは不要
7. パラレル OK — バッチ作業用に多くの Codex プロセスを同時実行
8. 決して ~/clawd/ で Codex を起動しない — 組織図についての奇妙な考えを得るために soul ドキュメントを読むでしょう!
9. 決して ~/Projects/clawdbot/ でブランチをチェックアウトしない — それはライブ Clawdbot インスタンスです!

---

ラーニング (2026 年 1 月)

• PTY は必須: コーディングエージェントはインタラクティブターミナルアプリです。pty:true なしでは、出力が破損するかエージェントがハングします。
• Git リポジトリが必須: Codex は git ディレクトリ外では実行されません。スクラッチワーク用に mktemp -d && git init を使用してください。
• exec はあなたの味方: codex exec "prompt" はクリーンに実行して終了 — ワンショット用に完璧です。
• submit vs write: 入力 + Enter を送信する場合は submit を、改行なしの未処理データを送信する場合は write を使用してください。
• Sass は機能します: Codex は遊び心のあるプロンプトに よく応答します。宇宙ロブスターの相棒になることについてのハイクを書くよう求めたところ、"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow" が得られました 🦞