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

Features

• Terminal-native — no web UI; everything runs inside your terminal
• Visual node editor — rounded nodes, dependency edges, and per-type coloring, powered by Textual
• 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

Requirements

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

Installation

**If you have uv, no installation is needed.** `uvx agenttakt` fetches and runs AgentTakt on demand, and the `.mcp.json` example below starts the MCP server the same way.

If you don't have uv, install AgentTakt once:

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

Installing is also handy for everyday use even with uv — you start the TUI by hand, so plain `agenttakt` beats typing `uvx agenttakt` each time:

uv tool install agenttakt

Quick Start

AgentTakt runs as two processes: the MCP server, which Claude Code starts for you, and the TUI, which you start yourself in a separate terminal. The TUI is what displays the plan, so start it before asking the Executor for approval.

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

1. Start the TUI (in its own terminal)

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 calls `request_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. Set `AGENTTAKT_NO_UPDATE_CHECK=1` to 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]

> Setting `timeout` (milliseconds) explicitly is required. The `request_approval` tool 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 to `show_plan`, which returns as soon as the TUI receives the plan.

3. Request approval from the Executor

When the Executor calls the MCP tool `request_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 }

See docs/schema.md for the plan JSON format and what to write in each node.

Display-only plans (`show_plan`)

`show_plan(plan, summary)` shows a plan in the TUI without 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 call `request_approval` naturally 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's `CLAUDE.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 later `request_approval` waits in the queue behind it.

Debug mode (try it without MCP)

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

Key Bindings

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

Documentation

• Plan JSON schema — data model, node fields, what to write in `type` / `data`, and validation rules
• Changelog — release notes for each version

License

MIT