🤖

Codexリポジトリを分解して優しく解説してみた

に公開
AI
Rust
CLI
tui
Model Context Protocol
tech

「AIエージェントって、コードの中でどう動いてるの？」——そんな素朴な疑問に答えるために、今回は Codex リポジトリ（Rust 製）を“文系にもわかる”言葉で分解してみました。

先に要点だけ：

  • Codex は「人間の操作」を「AIの行動（コード編集やコマンド実行）」に変換する“通訳ロボ”。
  • 画面（TUI）と頭脳（Core）と手足（Exec/ApplyPatch/MCPツール）が“イベント”で連携する設計。
  • 危険な操作は「本当にやる？」と必ず確認（安全設計）。
  • MCPは“道具箱を外付けできる規格”。後からツールを増やせる拡張性が肝。

Codexってなに？（一言で）

  • ざっくり言うと、ターミナル上でAIとやりとりしながら「コマンド実行」「差分適用」「外部ツール連携（MCP）」を、なるべく安全に・半自動で進めてくれる「開発の相棒」です。

たとえば「このファイルを書き換えてビルドして」と依頼すると、Codexは：

  1. 計画（Plan）を要約
  2. 実行（Exec）や編集（ApplyPatch）を提案
  3. 実行前にあなたに確認（Approval）
  4. 実行ログや差分をUIにストリーム表示

という“段取り”で、透明性を保ちながら進めます。

大づかみの構造（全体像）

人間の操作 → TUI（画面） → Core（中核） → ツール群（Exec/ApplyPatch/MCP） → 結果をイベントとしてTUIへ

あなたのキーボード
   │ 文字/Enter
   ▼
TUI（チャット画面・ヘルプ・モーダルなど）
   │ Op: UserInput / Approval / ...
   ▼
Core（セッション管理・安全確認・計画・実行指示）
   │ ツール呼び出し（Exec/ApplyPatch/MCP）
   ▼
外部ツール / OS / 編集差分
   │ イベント: AgentMessageDelta / ExecCommandEnd / PatchApplyEnd
   ▼
TUIに反映（ログ／差分／メッセージ）
  • ここでのキーワードは「イベント」。Coreはすべての出来事を“イベント”としてTUIに流し、TUIはそれをそのまま描画します。だからUIは“受け取った事実”を表示するだけで、複雑なAIの思考を知らなくてもいい。

ディレクトリを“人の仕事風”に置き換える

  • tui/ = 受付と案内（見た目と操作の窓口）
  • core/ = 現場監督（やることの段取りと安全の確認）
  • exec/ や apply-patch/ = 作業員（コマンド実行・ファイル編集）
  • mcp-* = 協力会社（必要に応じて呼べる外部ツール）

実際のコードでは、以下のような役割分担が見られます（Codex本体の例）：

  • TUI: codex-rs/tui/ … ratatuiでチャットやポップアップ。キー入力をイベントに。
  • Core: codex-rs/core/ … セッション、ツール呼び出し、安全判定、イベント生成。
  • Exec/ApplyPatch: codex-rs/exec/, codex-rs/apply-patch/ … 具体的な手の動き。
  • MCP: codex-rs/mcp-* … 外部AI/ツールと会話するための接続口。

イベント駆動ってなにが嬉しい？

  • 変更に強い： 新しいツールを追加しても、TUIは“イベント”を描画するだけで済む。
  • 安全設計と相性◎： 「実行前に approval（承認）イベントを挟む」などが自然にできる。
  • ログが明快： 「いつ、誰が、何を」したかを逐次イベントで追跡できる。

MCPは“拡張コンセント”

  • MCP（Model Context Protocol）は「AIに道具をつなぐための共通規格」。
  • Codexでは、外部サービスや社内ツールも“MCPサーバー”として接続でき、AIが必要に応じて呼び出します。
  • メリット：
    • 後から安全に機能拡張
    • 各ツールは独立配布でき、更新や権限の管理がしやすい

安全設計（ここが肝）

  • 何でも勝手に実行しない： 危険度の高い操作は承認ダイアログを出し、人間がOKしたら実行。
  • サンドボックス / ポリシー： 書き込み先やネットワーク可否など、ポリシーで縛る設計が根付いています。
  • 差分（Unified Diff）提示： コード変更は“パッチ”として提示し、内容を人がレビューしてから適用。

実際の“動き方”を物語風に

  1. あなたがTUIで文章を入力 → Enter
  2. TUIは UserInput をCoreへ渡す
  3. Coreは「計画（Plan）」を作り、必要なツール（Exec/ApplyPatch/MCP）を選ぶ
  4. 危ない操作なら一旦ストップ → 「このコマンド本当に実行してOK？」
  5. OKなら実行 → 実行ログがTUIにストリーム表示
  6. 終わったら「完了」のイベントが流れてきて、一息

Codexの良いところ / 注意点

  • 良いところ：
    • 安全と拡張性のバランスが良い
    • UIとCoreの分離で“見通しが良い”
    • MCPで道具箱を後から増やせる
  • 注意点：
    • ツール連携やポリシーは“設計の要”。運用前に一度ポリシーを言語化しておくと◎
    • モデル（LLM）やAPIキーの設定は確実に。権限周りでハマりやすい

はじめて触る人向けの地図（用語ミニ辞典）

  • TUI: Terminal UI（ターミナル画面のUI）。
  • Core: 司令塔。イベントを出したり、ツールを呼び出したりする中核。
  • Exec: コマンド実行担当。ls や cargo build など。
  • ApplyPatch: 変更差分を当てる担当。“パッチを当てる”あの感じ。
  • MCP: 道具を挿すコネクタ規格。後から新しいツールを増やせる。
  • Approval: 実行前確認。「本当にそれやる？」と聞いてくる安全帯。

“Codexっぽさ”を小さく試すには

  • 画面（TUI）と頭脳（Core）を分ける
  • イベントでつなぐ（入力→Op、結果→Event）
  • 危険操作はApprovalを挟む
  • 変更は必ずDiffで提示する

この4点を守るだけで、“小さなCodex”は組み立てられます。まずは小さく作って、イベントログをよく観察するのがおすすめ。

おわりに

Codexは「人間が主役で、AIは相棒」という思想が通底しています。
「ちゃんと言って、ちゃんと確認して、ちゃんと記録する」。
この“仕事の段取り”を、コードの世界でも愚直にやっているのが面白いところです。

この記事は、手元のリポジトリ構成を読み解きつつ、Zenn MCPでそのまま記事化しました。細部はプロジェクトのバージョンや運用方針で異なることもありますが、“UI↔Core↔Toolsをイベントで繋ぐ” という核は変わらないはず。どこから読めばいいか迷ったら、まずは tui/ と core/ の“入口”と“出口”を往復してみてください。世界がつながって見えてきます。

補足: 記事内の用語・比喩は初心者向けに噛み砕いています。厳密な仕様やAPIの最新版は、各ディレクトリのREADMEやソースコードのコメントをご確認ください。

GitHubで編集を提案

Discussion