{ "markdown": "\n\n

\n \"AgentTakt\n

\n\n

\n \"PyPI\n \"PyPI\n \"License:\n

\n\n![AgentTakt demo: drag nodes, draw a dependency edge, approve](https://raw.githubusercontent.com/ryoohshima/AgentTakt/main/docs/images/demo.gif)\n\nAgentTakt 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.\n\n```\nClaude Code (Executor)\n │ stdio (MCP) your other terminal\n ▼ │\n[agenttakt serve] ── Unix domain socket ──▶ [agenttakt (TUI)]\n MCP server review / edit / approve\n```\n\n## Features\n\n- **Terminal-native** — no web UI; everything runs inside your terminal\n- **Visual node editor** — rounded nodes, dependency edges, and per-type coloring, powered by [Textual](https://textual.textualize.io/)\n- **Mouse-first editing** — drag nodes to move them, draw edges between ports (rubber band), click to select and delete\n- **Safe approval loop** — cycle detection (DAG guarantee) and other validations at the entry point, returning errors the agent can self-correct\n\n## Requirements\n\n- Python 3.10+ (recommended: [uv](https://docs.astral.sh/uv/))\n- A terminal emulator with mouse reporting (iTerm2, WezTerm, kitty, Ghostty, ...)\n\n## Installation\n\n**If you have [uv](https://docs.astral.sh/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.\n\n**If you don't have uv, install AgentTakt once:**\n\n```sh\nbrew install ryoohshima/tap/agenttakt # Homebrew\npipx install agenttakt # pipx\n```\n\nInstalling is also handy for everyday use even with uv — you start the TUI by hand, so plain `agenttakt` beats typing `uvx agenttakt` each time:\n\n```sh\nuv tool install agenttakt\n```\n\n## Quick Start\n\nAgentTakt 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.\n\n```\n┌─ Terminal A: you ───────────────────┐ ┌─ Terminal B: Claude Code ───────────┐\n│ $ uvx agenttakt │ │ $ claude │\n│ │ │ │\n│ ╭─ grep ───╮ │ │ > Plan the refactor, then ask │\n│ │ pattern │───╮ │ │ me to approve it │\n│ ╰──────────╯ │ │ │ │\n│ ╭────▼─────╮ │ │ calls request_approval(plan) │\n│ │ edit │ │ │ waiting for approval... │\n│ ╰──────────╯ │ │ (blocked until you decide) │\n│ │ │ │\n│ [a] Approve [r] Reject │ │ │\n└─────────────────────────────────────┘ └─────────────────────────────────────┘\n ▲ │\n ╰──────────────── Unix domain socket ────────────────╯\n```\n\nRunning 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.\n\n### 1. Start the TUI (in its own terminal)\n\n```sh\nuvx agenttakt # if installed: agenttakt (short alias: agt)\n```\n\nAn 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:\n\n> AgentTakt editor is not running. Ask the user to run \"agenttakt\" in a separate terminal, then call request_approval again.\n\nOn 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.\n\n### 2. Register the MCP server with the Executor (Claude Code)\n\nAdd the following to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"agenttakt\": {\n \"command\": \"uvx\",\n \"args\": [\"agenttakt\", \"serve\"],\n \"timeout\": 1800000\n }\n }\n}\n```\n\n> [!IMPORTANT]\n> **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.\n\n### 3. Request approval from the Executor\n\nWhen 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:\n\n```json\n{ \"status\": \"approved\", \"plan\": { \"...edited plan...\" }, \"reason\": null }\n```\n\nSee [docs/schema.md](docs/schema.md) for the plan JSON format and what to write in each node.\n\n### Display-only plans (`show_plan`)\n\n`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.\n\nAgents 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):\n\n```markdown\n## AgentTakt\n\nWhenever you formulate a multi-step plan — in any mode, not just plan mode —\nsubmit it with the AgentTakt `show_plan` tool so the human can see it as a\nnode graph. Use `request_approval` instead when you need the human's approval\nbefore executing.\n```\n\nNote: a `[view-only]` plan occupies the editor until dismissed; a later `request_approval` waits in the queue behind it.\n\n### Debug mode (try it without MCP)\n\n```sh\nuvx agenttakt open examples/sample_plan.json --out edited.json\n```\n\nLoads a plan from a file, opens the editor, and writes the approval result to `--out`.\n\n## Key Bindings\n\n| Key | Action |\n|---|---|\n| `a` | Approve the plan (confirmation dialog) |\n| `r` | Reject the plan (with a reason) |\n| `n` | Add a node |\n| `d` / `Delete` | Delete the selected node/edge |\n| `u` / `U` | Undo / Redo |\n| Arrow keys | Move the selected node by one cell (fine-tuning) |\n| `Escape` | Clear selection |\n| `p` | Toggle the parameter panel |\n| `?` | Help (controls and how to write `type` / `data`) |\n| `q` | Quit |\n\nMouse: drag a node to move it; drag from a node's output port (●, right edge) and release on another node to create an edge.\n\nEdges are drawn as braille Bezier-like curves by default. If they render poorly in your environment, switch to rounded orthogonal lines with `--edges orthogonal`.\n\n## Documentation\n\n- [Plan JSON schema](docs/schema.md) — data model, node fields, what to write in `type` / `data`, and validation rules\n- [Changelog](https://github.com/ryoohshima/AgentTakt/releases) — release notes for each version\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 8390, "sha": "8144ded5c2dc2cd2e3712a1e268cea9a965c51fb0143ded1dae5f7cbd0920a6b", "repo_slug": "ryoohshima/agenttakt", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ryoohshima_agenttakt_12d2a123/readme" }