AgentTakt
Review, edit, and approve AI agent task plans in a ComfyUI-style visual node editor in your terminal
Open source Open in the app JSON README (API)
About
Review, edit, and approve AI agent task plans in a ComfyUI-style visual node editor in your terminal
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- ryoohshima
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Last push
- 2026-08-29T01:02:28Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:20
- Updated
- 2026-08-29 04:01:20
- Origin id
io.github.ryoohshima/agenttakt
README
<!-- mcp-name: io.github.ryoohshima/agenttakt -->
<p align="center">
<img src="https://raw.githubusercontent.com/ryoohshima/AgentTakt/main/docs/images/github-social-preview.png" alt="AgentTakt — Review, edit, and approve AI agent task plans in a ComfyUI-style visual node editor, right in your terminal." />
</p>
<p align="center">
<a href="https://pypi.org/project/agenttakt/"><img src="https://img.shields.io/pypi/v/agenttakt" alt="PyPI - Version" /></a>
<a href="https://pypi.org/project/agenttakt/"><img src="https://img.shields.io/pypi/pyversions/agenttakt" alt="PyPI - Python Version" /></a>
<a href="https://github.com/ryoohshima/AgentTakt/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" /></a>
</p>
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](https://textual.textualize.io/)
- **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](https://docs.astral.sh/uv/))
- A terminal emulator with mouse reporting (iTerm2, WezTerm, kitty, Ghostty, ...)
## Installation
**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.
**If you don't have uv, install AgentTakt once:**
```sh
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:
```sh
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)
```sh
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`:
```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:
```json
{ "status": "approved", "plan": { "...edited plan..." }, "reason": null }
```
See [docs/schema.md](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):
```markdown
## 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)
```sh
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
| Key | Action |
|---|---|
| `a` | Approve the plan (confirmation dialog) |
| `r` | Reject the plan (with a reason) |
| `n` | Add a node |
| `d` / `Delete` | Delete the selected node/edge |
| `u` / `U` | Undo / Redo |
| Arrow keys | Move the selected node by one cell (fine-tuning) |
| `Escape` | Clear selection |
| `p` | Toggle the parameter panel |
| `?` | Help (controls and how to write `type` / `data`) |
| `q` | Quit |
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](docs/schema.md) — data model, node fields, what to write in `type` / `data`, and validation rules
- [Changelog](https://github.com/ryoohshima/AgentTakt/releases) — release notes for each version
## License
[MIT](LICENSE)