AgentTakt

AgentTaktは、MCP（Model Context Protocol）サーバー兼TUIツールです。AIエージェント（Claude Codeなどの「Executor」）がMCP経由でタスク実行計画を送信すると、AgentTaktはそれをターミナル内にノードグラフとして表示します。マウスとキーボードで確認し、ノードの移動、追加、削除、依存関係エッジの描画、パラメーターの編集を行った後、承認します。編集した計画のJSONは、実行のためにExecutorへ返されます。

Claude Code (Executor)
   │ stdio (MCP)                        your other terminal
   ▼                                           │
[agenttakt serve] ── Unix domain socket ──▶ [agenttakt (TUI)]
 MCP server                               review / edit / approve

特長

• ターミナルネイティブ — Web UIは不要で、すべてターミナル内で動作します
• ビジュアルノードエディター — 角丸ノード、依存関係エッジ、タイプごとの色分けを備え、Textualを使用しています
• マウス中心の編集 — ノードをドラッグして移動し、ポート間にエッジを描画し（ラバーバンド）、クリックして選択・削除できます
• 安全な承認ループ — エントリーポイントで循環検出（DAGを保証）などの検証を行い、エージェントが自ら修正できるエラーを返します

要件

• Python 3.10+（推奨：uv）
• マウスレポートに対応したターミナルエミュレーター（iTerm2、WezTerm、kitty、Ghosttyなど）

インストール

uvをお持ちの場合、インストールは不要です。 uvx agenttaktは必要に応じてAgentTaktを取得して実行します。以下の.mcp.jsonの例でも、同じ方法でMCPサーバーを起動します。

uvをお持ちでない場合は、AgentTaktを一度インストールしてください：

brew install ryoohshima/tap/agenttakt    # Homebrew
pipx install agenttakt                   # pipx

uvをお使いの場合でも、普段使いにはインストールしておくと便利です。TUIは手動で起動するため、毎回uvx agenttaktと入力するより、agenttaktだけで起動できます。

uv tool install agenttakt

エージェントプラグイン

このリポジトリはAgent Plugins 1.0.0 パッケージです。互換性のあるクライアントでは、リポジトリのルートをプラグインディレクトリとして読み込んでください。

AgentTakt/
├── plugin.json     # Portable plugin manifest
├── mcp.json        # MCP server configuration
└── LICENSE

このプラグインにはPATH上のuvxが必要で、PyPIから公開済みのagenttaktパッケージを実行します。 uvキャッシュは、クライアントが管理するPLUGIN_DATA ディレクトリに保存されます。ツールを使う前に、uvx agenttaktでTUIを別途起動してください。 request_approvalでは、クライアントに十分長いツールタイムアウトを設定してください （例：30分）。ポータブルなMCP形式にはtimeoutフィールドがありません。

開発用の.mcp.jsonは、ローカルのチェックアウトを実行する、クライアント固有の別設定です。 server.jsonはMCP Registry向けのメタデータを提供します。

クイックスタート

AgentTaktは2つのプロセスとして動作します。1つはClaude Codeが起動するMCPサーバー、もう1つは別のターミナルで自分で起動するTUIです。計画を表示するのはTUIなので、Executorに承認を求める前に起動してください。

┌─ Terminal A: you ───────────────────┐   ┌─ Terminal B: Claude Code ───────────┐
│ $ uvx agenttakt                     │   │ $ claude                            │
│                                     │   │                                     │
│   ╭─ grep ───╮                      │   │ > Plan the refactor, then ask       │
│   │ pattern  │───╮                  │   │   me to approve it                  │
│   ╰──────────╯   │                  │   │                                     │
│             ╭────▼─────╮            │   │   calls request_approval(plan)      │
│             │   edit   │            │   │   waiting for approval...           │
│             ╰──────────╯            │   │   (blocked until you decide)        │
│                                     │   │                                     │
│   [a] Approve   [r] Reject          │   │                                     │
└─────────────────────────────────────┘   └─────────────────────────────────────┘
             ▲                                                    │
             ╰──────────────── Unix domain socket ────────────────╯

Claude Codeと同じセッションでTUIを実行することはできません。stdio MCPサーバーでは、標準入力と標準出力がプロトコルトラフィック用に確保されているため、同じプロセスでフルスクリーンのターミナルUIを動かすこともできません。そのため、2つのプロセスに分け、Unixドメインソケット経由で通信します。

1. TUI を起動する（専用のターミナルで）

uvx agenttakt           # if installed: agenttakt (short alias: agt)

Executor からのプランを待機するアイドル画面が表示されます。このターミナルは開いたままにしてください。Executor が request_approval を呼び出したときに TUI が起動していないと、呼び出しは失敗し、次のメッセージが表示されます。

AgentTakt editor is not running. Ask the user to run "agenttakt" in a separate terminal, then call request_approval again.

起動時、TUI はバックグラウンドで PyPI を確認し、新しいバージョンが利用可能な場合に通知を表示します。確認を無効にするには、AGENTTAKT_NO_UPDATE_CHECK=1 を設定します。

2. Executor に MCP サーバーを登録する（Claude Code）

プロジェクトの .mcp.json に次の内容を追加します。

{
  "mcpServers": {
    "agenttakt": {
      "command": "uvx",
      "args": ["agenttakt", "serve"],
      "timeout": 1800000
    }
  }
}

重要

timeout（ミリ秒）の明示的な設定が必要です。 人間が確認を終えるまで、request_approval ツールは処理をブロックします。MCP の進捗通知ではクライアント側のタイムアウトは延長されないため、デフォルト設定では承認前にリクエストがタイムアウトします。上記の例では 30 分（1800000）に設定しています。プランを TUI が受信するとすぐに戻る show_plan には、この設定は適用されません。

3. Executor に承認をリクエストする

Executor が MCP ツール request_approval(plan, summary) を呼び出すと、プランがノードグラフとして TUI に表示されます。人間が編集して承認（または却下）すると、結果が次の形式で返されます。

{ "status": "approved", "plan": { "...edited plan..." }, "reason": null }

プランの JSON 形式と各ノードに記述する内容については、docs/schema.md を参照してください。

表示専用のプラン（show_plan）

show_plan(plan, summary) は、承認を待たずに TUI にプランを表示します。エディターがプランを受信するとすぐに {"status": "displayed"} を返します。プランモードに限らず、エージェントが何を計画しているかを確認したい場合に使用してください。プランには [view-only] ヘッダーが付き、閉じても Executor には何も返されません。

ホストがプランモードのとき、エージェントは自然に request_approval を呼び出しますが、プランモード以外では自発的にプランを提示しません。そうするよう促すには、プロジェクトの CLAUDE.md（または同等のエージェント向け指示）に次のような指示を追加してください。

## AgentTakt

Whenever you formulate a multi-step plan — in any mode, not just plan mode —
submit it with the AgentTakt `show_plan` tool so the human can see it as a
node graph. Use `request_approval` instead when you need the human's approval
before executing.

注：[view-only] のプランは閉じるまでエディターを占有します。その間に後続の request_approval が呼び出されると、キューで待機します。

デバッグモード（MCP を使わずに試す）

uvx agenttakt open examples/sample_plan.json --out edited.json

ファイルからプランを読み込み、エディターを開いて、承認結果を --out に書き込みます。

キーバインド

キー	操作
a	プランを承認する（確認ダイアログ）
r	プランを却下する（理由を入力）
n	ノードを追加する
d / Delete	選択したノード／エッジを削除する
u / U	元に戻す／やり直す
矢印キー	選択したノードを 1 セル移動する（微調整）
Escape	選択を解除する
p	パラメータパネルを切り替える
?	ヘルプ（操作方法と type ／ data の記述方法）
q	終了する

マウス：ノードをドラッグして移動します。ノードの出力ポート（●、右端）からドラッグし、別のノード上で離すとエッジを作成できます。

デフォルトでは、エッジは点字文字を使ったベジェ曲線のような形で描画されます。お使いの環境で正しく表示されない場合は、--edges orthogonal を指定して角丸の直交線に切り替えてください。

ドキュメント

• プランの JSON スキーマ — データモデル、ノードのフィールド、type ／ data に記述する内容、検証ルール
• 変更履歴 — 各バージョンのリリースノート

ライセンス

MIT