AgentTakt

AgentTakt é um servidor MCP (Model Context Protocol) e ferramenta TUI. Quando um agente de IA (um "Executor", como Claude Code) envia um plano de execução de tarefas via MCP, o AgentTakt o renderiza como um grafo de nós no seu terminal. Você o revisa com mouse e teclado — mova, adicione e exclua nós, desenhe arestas de dependência, edite parâmetros — e então aprove, e o JSON do plano editado é retornado ao Executor para execução.

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

Recursos

• Nativo de terminal — sem interface web; tudo roda dentro do seu terminal
• Editor visual de nós — nós arredondados, arestas de dependência e cores por tipo, alimentado por Textual
• Edição focada no mouse — arraste nós para movê-los, desenhe arestas entre portas (elástico), clique para selecionar e excluir
• Ciclo de aprovação seguro — detecção de ciclos (garantia de DAG) e outras validações no ponto de entrada, retornando erros que o agente pode autocorrigir

Requisitos

• Python 3.10+ (recomendado: uv)
• Um emulador de terminal com suporte a mouse (iTerm2, WezTerm, kitty, Ghostty, ...)

Instalação

Se você tem uv, nenhuma instalação é necessária. uvx agenttakt busca e executa o AgentTakt sob demanda, e o exemplo .mcp.json abaixo inicia o servidor MCP da mesma forma.

Se você não tem uv, instale o AgentTakt uma vez:

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

Instalar também é útil para uso diário mesmo com uv — você inicia a TUI manualmente, então agenttakt simples é melhor do que digitar uvx agenttakt toda vez:

uv tool install agenttakt

Plugins de Agente

Este repositório é um pacote Agent Plugins 1.0.0. Em um cliente compatível, carregue a raiz do repositório como diretório de plugin:

AgentTakt/
├── plugin.json     # Portable plugin manifest
├── mcp.json        # MCP server configuration
└── LICENSE

O plugin requer uvx no PATH e executa o pacote agenttakt publicado no PyPI. Seu cache uv é armazenado no diretório PLUGIN_DATA gerenciado pelo cliente. Inicie a TUI separadamente com uvx agenttakt antes de usar as ferramentas. Para request_approval, configure um timeout de ferramenta suficientemente longo no seu cliente (por exemplo, 30 minutos); o formato MCP portátil não tem campo timeout.

O .mcp.json de desenvolvimento é uma configuração separada nativa do cliente que executa o checkout local. server.json fornece metadados para o Registro MCP.

Início Rápido

O AgentTakt roda como dois processos: o servidor MCP, que o Claude Code inicia para você, e a TUI, que você mesmo inicia em um terminal separado. A TUI é o que exibe o plano, então inicie-a antes de pedir aprovação ao 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 ────────────────╯

Executar a TUI na mesma sessão do Claude Code não funciona. Um servidor MCP stdio tem sua entrada e saída padrão reservadas para tráfego de protocolo, então o mesmo processo não pode também dirigir uma interface de terminal em tela cheia. É por isso que as duas metades são processos separados conversando por um socket de domínio Unix.

1. Inicie a TUI (em seu próprio terminal)

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

Uma tela ociosa aparece, aguardando planos do Executor. Deixe este terminal aberto. Se nenhuma TUI estiver em execução quando o Executor chamar request_approval, a chamada falhará com:

O editor AgentTakt não está em execução. Peça ao usuário para executar "agenttakt" em um terminal separado e chame request_approval novamente.

Na inicialização, a TUI verifica o PyPI em segundo plano e mostra uma notificação quando uma versão mais recente está disponível. Defina AGENTTAKT_NO_UPDATE_CHECK=1 para desativar a verificação.

2. Registre o servidor MCP com o Executor (Claude Code)

Adicione o seguinte ao .mcp.json do seu projeto:

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

[!IMPORTANT] Definir timeout (milissegundos) explicitamente é obrigatório. A ferramenta request_approval bloqueia até que o humano termine a revisão. Notificações de progresso do MCP não estendem timeouts do lado do cliente, então o padrão cortaria a solicitação antes da aprovação. O exemplo acima define 30 minutos (1800000). Isso não se aplica a show_plan, que retorna assim que a TUI recebe o plano.

3. Solicite aprovação do Executor

Quando o Executor chama a ferramenta MCP request_approval(plan, summary), o plano aparece na TUI como um grafo de nós. Quando o humano edita e aprova (ou rejeita), o resultado é retornado como:

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

Consulte docs/schema.md para o formato JSON do plano e o que escrever em cada nó.

Planos somente exibição (show_plan)

show_plan(plan, summary) mostra um plano na TUI sem aguardar aprovação — retorna {"status": "displayed"} assim que o editor o recebe. Use-o quando quiser apenas visibilidade do que o agente está planejando, em qualquer modo (não apenas no modo plano). O plano abre com um cabeçalho [view-only]; fechá-lo não envia nada de volta ao Executor.

Agentes chamam request_approval naturalmente quando o host está no modo plano, mas não oferecerão planos fora dele. Para incentivar isso, adicione uma instrução como esta ao CLAUDE.md do seu projeto (ou instruções 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: um plano [view-only] ocupa o editor até ser dispensado; um request_approval posterior aguarda na fila atrás dele.

Modo de depuração (experimente sem MCP)

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

Carrega um plano de um arquivo, abre o editor e grava o resultado da aprovação em --out.

Atalhos de Teclado

Tecla	Ação
a	Aprovar o plano (diálogo de confirmação)
r	Rejeitar o plano (com um motivo)
n	Adicionar um nó
d / Delete	Excluir o nó/aresta selecionado
u / U	Desfazer / Refazer
Setas	Mover o nó selecionado em uma célula (ajuste fino)
Escape	Limpar seleção
p	Alternar o painel de parâmetros
?	Ajuda (controles e como escrever type / data)
q	Sair

Mouse: arraste um nó para movê-lo; arraste da porta de saída de um nó (●, borda direita) e solte em outro nó para criar uma aresta.

As arestas são desenhadas como curvas braille semelhantes a Bezier por padrão. Se renderizarem mal no seu ambiente, alterne para linhas ortogonais arredondadas com --edges orthogonal.

Documentação

• Esquema JSON do plano — modelo de dados, campos de nó, o que escrever em type / data e regras de validação
• Changelog — notas de versão para cada versão

Licença

MIT