AgentTakt
Revisa y aprueba los planes de tareas de agentes de IA en un editor de nodos estilo ComfyUI, directamente en tu terminal (servidor MCP + TUI)
Documentación
AgentTakt es un servidor MCP (Model Context Protocol) y una herramienta TUI. Cuando un agente de IA (un "Executor" como Claude Code) envía un plan de ejecución de tareas a través de MCP, AgentTakt lo renderiza como un grafo de nodos en tu terminal. Lo revisas con el ratón y el teclado — mueve, añade y elimina nodos, dibuja aristas de dependencia, edita parámetros — luego apruebas, y el JSON del plan editado se devuelve al Executor para su ejecución.
Claude Code (Executor)
│ stdio (MCP) your other terminal
▼ │
[agenttakt serve] ── Unix domain socket ──▶ [agenttakt (TUI)]
MCP server review / edit / approve
Características
- Nativo de terminal — sin interfaz web; todo se ejecuta dentro de tu terminal
- Editor visual de nodos — nodos redondeados, aristas de dependencia y colores por tipo, impulsado por Textual
- Edición centrada en el ratón — arrastra nodos para moverlos, dibuja aristas entre puertos (banda elástica), haz clic para seleccionar y eliminar
- Bucle de aprobación seguro — detección de ciclos (garantía DAG) y otras validaciones en el punto de entrada, devolviendo errores que el agente puede autocorregir
Requisitos
- Python 3.10+ (recomendado: uv)
- Un emulador de terminal con soporte de ratón (iTerm2, WezTerm, kitty, Ghostty, ...)
Instalación
Si tienes uv, no se necesita instalación. uvx agenttakt obtiene y ejecuta AgentTakt bajo demanda, y el ejemplo .mcp.json a continuación inicia el servidor MCP de la misma manera.
Si no tienes uv, instala AgentTakt una vez:
brew install ryoohshima/tap/agenttakt # Homebrew
pipx install agenttakt # pipx
Instalar también es útil para el uso diario incluso con uv — inicias la TUI manualmente, así que agenttakt simple supera a escribir uvx agenttakt cada vez:
uv tool install agenttakt
Plugins de Agente
Este repositorio es un paquete Agent Plugins 1.0.0. En un cliente compatible, carga la raíz del repositorio como directorio de plugins:
AgentTakt/
├── plugin.json # Portable plugin manifest
├── mcp.json # MCP server configuration
└── LICENSE
El plugin requiere uvx en PATH y ejecuta el paquete publicado agenttakt desde PyPI. Su caché de uv se almacena bajo el directorio PLUGIN_DATA gestionado por el cliente. Inicia la TUI por separado con uvx agenttakt antes de usar las herramientas. Para request_approval, configura un tiempo de espera de herramienta suficientemente largo en tu cliente (por ejemplo, 30 minutos); el formato MCP portátil no tiene campo timeout.
El .mcp.json de desarrollo es una configuración separada nativa del cliente que ejecuta el checkout local. server.json proporciona metadatos para el Registro MCP.
Inicio Rápido
AgentTakt se ejecuta como dos procesos: el servidor MCP, que Claude Code inicia por ti, y la TUI, que tú mismo inicias en una terminal separada. La TUI es la que muestra el plan, así que iníciala antes de pedir aprobación al 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 ────────────────╯
Ejecutar la TUI en la misma sesión que Claude Code no funciona. Un servidor MCP stdio tiene su entrada y salida estándar reservadas para el tráfico del protocolo, por lo que el mismo proceso no puede también manejar una interfaz de terminal de pantalla completa. Es por eso que las dos mitades son procesos separados que se comunican a través de un socket de dominio Unix.
1. Inicia la TUI (en su propia terminal)
uvx agenttakt # if installed: agenttakt (short alias: agt)
Aparece una pantalla inactiva, esperando planes del Executor. Deja esta terminal abierta. Si no hay una TUI ejecutándose cuando el Executor llama a request_approval, la llamada falla con:
El editor de AgentTakt no está ejecutándose. Pide al usuario que ejecute "agenttakt" en una terminal separada, y luego llama a request_approval de nuevo.
Al iniciar, la TUI verifica PyPI en segundo plano y muestra una notificación cuando hay una versión más reciente disponible. Establece AGENTTAKT_NO_UPDATE_CHECK=1 para deshabilitar la verificación.
2. Registra el servidor MCP con el Executor (Claude Code)
Añade lo siguiente al .mcp.json de tu proyecto:
{
"mcpServers": {
"agenttakt": {
"command": "uvx",
"args": ["agenttakt", "serve"],
"timeout": 1800000
}
}
}
[!IMPORTANTE] Establecer
timeout(milisegundos) explícitamente es obligatorio. La herramientarequest_approvalse bloquea hasta que el humano termina de revisar. Las notificaciones de progreso de MCP no extienden los tiempos de espera del lado del cliente, por lo que el valor predeterminado cortaría la solicitud antes de la aprobación. El ejemplo anterior establece 30 minutos (1800000). Esto no se aplica ashow_plan, que regresa tan pronto como la TUI recibe el plan.
3. Solicita aprobación al Executor
Cuando el Executor llama a la herramienta MCP request_approval(plan, summary), el plan aparece en la TUI como un grafo de nodos. Una vez que el humano edita y aprueba (o rechaza) el plan, el resultado se devuelve como:
{ "status": "approved", "plan": { "...edited plan..." }, "reason": null }
Consulta docs/schema.md para el formato JSON del plan y qué escribir en cada nodo.
Planes solo de visualización (show_plan)
show_plan(plan, summary) muestra un plan en la TUI sin esperar aprobación — devuelve {"status": "displayed"} tan pronto como el editor lo recibe. Úsalo cuando solo quieras visibilidad de lo que el agente está planeando, en cualquier modo (no solo en modo plan). El plan se abre con un encabezado [view-only]; cerrarlo no envía nada de vuelta al Executor.
Los agentes llaman a request_approval naturalmente cuando el host está en modo plan, pero no ofrecerán planes voluntariamente fuera de él. Para fomentarlo, añade una instrucción como esta al CLAUDE.md de tu proyecto (o instrucciones de agente equivalentes):
## 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.
Nota: un plan [view-only] ocupa el editor hasta que se descarta; un request_approval posterior espera en la cola detrás de él.
Modo depuración (pruébalo sin MCP)
uvx agenttakt open examples/sample_plan.json --out edited.json
Carga un plan desde un archivo, abre el editor y escribe el resultado de la aprobación en --out.
Atajos de Teclado
| Tecla | Acción |
|---|---|
a | Aprobar el plan (diálogo de confirmación) |
r | Rechazar el plan (con un motivo) |
n | Añadir un nodo |
d / Delete | Eliminar el nodo/arista seleccionado |
u / U | Deshacer / Rehacer |
| Flechas | Mover el nodo seleccionado una celda (ajuste fino) |
Escape | Limpiar selección |
p | Alternar el panel de parámetros |
? | Ayuda (controles y cómo escribir type / data) |
q | Salir |
Ratón: arrastra un nodo para moverlo; arrastra desde el puerto de salida de un nodo (●, borde derecho) y suelta sobre otro nodo para crear una arista.
Las aristas se dibujan como curvas braille tipo Bezier por defecto. Si se renderizan mal en tu entorno, cambia a líneas ortogonales redondeadas con --edges orthogonal.
Documentación
- Esquema JSON del plan — modelo de datos, campos de nodo, qué escribir en
type/data, y reglas de validación - Registro de cambios — notas de versión para cada versión