AgentTakt

AgentTakt is an MCP (Model Context Protocol) server and TUI tool. When an AI agent (an "Executor" such as Claude Code) sends a task execution plan over MCP, AgentTakt renders it as a node graph in your terminal. You review it with mouse and keyboard — move, add, and delete nodes, draw dependency edges, edit parameters — then approve, and the edited plan JSON is returned to the Executor for execution.

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

- Terminal-native— no web UI; everything runs inside your terminal
- Visual node editor— rounded nodes, dependency edges, and per-type coloring, powered byTextual
- Mouse-first editing— drag nodes to move them, draw edges between ports (rubber band), click to select and delete
- Safe approval loop— cycle detection (DAG guarantee) and other validations at the entry point, returning errors the agent can self-correct

- Python 3.10+ (recommended:uv)
- A terminal emulator with mouse reporting (iTerm2, WezTerm, kitty, Ghostty, ...)

If you haveuv, no installation is needed.uvx agenttaktfetches and runs AgentTakt on demand, and the.mcp.jsonexample below starts the MCP server the same way.

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

┌─ 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 ────────────────╯

Running the TUI in the same session as Claude Code does not work. A stdio MCP server has its standard input and output reserved for protocol traffic, so the same process cannot also drive a full-screen terminal UI. That is why the two halves are separate processes talking over a Unix domain socket.

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

An idle screen appears, waiting for plans from the Executor. Leave this terminal open. If no TUI is running when the Executor callsrequest_approval, the call fails with:

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

On startup the TUI checks PyPI in the background and shows a notification when a newer version is available. SetAGENTTAKT_NO_UPDATE_CHECK=1to disable the check.

2. Register the MCP server with the Executor (Claude Code)

Add the following to your project's.mcp.json:

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

[!IMPORTANT]Settingtimeout(milliseconds) explicitly is required.Therequest_approvaltool blocks until the human finishes reviewing. MCP progress notifications do not extend client-side timeouts, so the default would cut the request off before approval. The example above sets 30 minutes (1800000). This does not apply toshow_plan, which returns as soon as the TUI receives the plan.

When the Executor calls the MCP toolrequest_approval(plan, summary), the plan appears in the TUI as a node graph. Once the human edits and approves (or rejects) it, the result is returned as:

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

Seedocs/schema.mdfor the plan JSON format and what to write in each node.

show_plan(plan, summary)shows a plan in the TUIwithout waiting for approval— it returns{"status": "displayed"}as soon as the editor receives it. Use it when you just want visibility into what the agent is planning, in any mode (not only plan mode). The plan opens with a[view-only]header; closing it sends nothing back to the Executor.

Agents callrequest_approvalnaturally when the host is in plan mode, but they will not volunteer plans outside it. To encourage that, add an instruction like this to your project'sCLAUDE.md(or equivalent agent instructions):

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

Note: a[view-only]plan occupies the editor until dismissed; a laterrequest_approvalwaits in the queue behind it.

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

Loads a plan from a file, opens the editor, and writes the approval result to--out.

Mouse: drag a node to move it; drag from a node's output port (●, right edge) and release on another node to create an edge.

Edges are drawn as braille Bezier-like curves by default. If they render poorly in your environment, switch to rounded orthogonal lines with--edges orthogonal.

- Plan JSON schema— data model, node fields, what to write intype/data, and validation rules
- Changelog— release notes for each version

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB