Makuco

Buscar na documentação

Páginas e seções

Visão geral

O que muda quando o comando makuco deixa de ser um instalador e passa a ser uma CLI interativa que dirige o fluxo.

Até a 3.1.0, makuco sozinho só imprimia um banner: todo o trabalho acontecia dentro do Claude Code ou do Copilot, e era você quem decidia qual skill invocar e em qual PBI.

A partir da 3.2.0, makuco abre uma CLI interativa no terminal. Ela lê os artefatos do projeto, deriva qual é o próximo passo, invoca a skill certa sozinha e mostra o agente trabalhando — mensagens, chamadas de ferramenta, diffs, pedidos de permissão e perguntas — sem você sair do terminal.

cd meu-projeto
makuco

O makuco init não mudou

A instalação de skills, agentes e MCPs continua sendo makuco init, com os mesmos prompts. A CLI interativa é uma camada nova por cima do projeto já inicializado — ela não instala nada.

O que ela faz por você

AntesAgora
Você abria o agente e digitava /makuco-desenvolver escolhendo o PBI na mão.A CLI lê .makuco/docs/ e oferece o próximo passo; Enter roda.
Um chat por task, gerenciado por você.A sessão pertence à skill: PBIs seguidos da mesma skill reaproveitam o processo vivo.
Progresso conferido abrindo arquivos./workflow relê os artefatos e desenha a árvore inteira.
Permissão respondida no agente.Diálogo na própria CLI, com política de auto-aprovação.
Commit feito no terminal, à parte.Diálogo de commit na lateral, com o agente escrevendo a mensagem.

Pré-requisitos

RequisitoPor quê
Projeto já inicializado (.claude/ presente)A CLI recusa abrir fora de um projeto Makuco e manda rodar o makuco init.
Claude Code instaladoO agente que executa os turnos. A CLI procura o executável claude no PATH e em ~/.local/bin, ~/.claude/local e ~/.claude/bin.
Autenticação do ClaudeA sessão do próprio Claude Code (~/.claude), ou ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN no ambiente.
Node.js ≥ 20 e npmSó para instalar a CLI. O runtime que executa a interface vem no pacote.
Terminal com TTYSem TTY não há interface: a CLI cai no modo de texto ou no caminho headless.

O runtime da interface é o Bun, e ele vem no pacote

A engine de terminal (OpenTUI) carrega uma biblioteca nativa que só o Bun sabe abrir. O pacote makuco traz o Bun como dependência e o executável makuco troca de runtime sozinho — você não instala nada a mais.

Se a instalação foi feita com --no-optional ou --omit=optional, o Bun não é baixado e a CLI sai com makuco: o runtime Bun não foi instalado. Refaça a instalação sem essas flags.

Não achou o Claude Code? A CLI diz exatamente isso, e a saída é instalar o Claude Code ou apontar CLAUDE_CODE_EXECUTABLE para o executável.

O loop

A CLI não é um chat com um agente solto. Ela roda um laço:

  1. Lê os artefatos — .makuco/docs/.../pbis/ e os arquivos de sessão (sessao.md, sessao-dev.md) de cada feature e PBI.
  2. Deriva os passos candidatos — makuco-analisar quando falta análise ou PBIs; makuco-desenvolver para cada PBI não implementado de feature já analisada.
  3. Oferece o primeiro — a caixa mostra a oferta e Enter aceita. /steps lista os outros, /skip deixa o oferecido de lado.
  4. Invoca a skill — abre a sessão com o agente e passa o alvo como sugestão, não como ordem: o agente confere contra o disco e conduz os passos internos da skill do começo ao fim.
  5. Relê e volta ao 1 — quando um alvo fecha, a CLI para e pergunta antes de seguir para o próximo. O modo yolo é o que dispensa essa licença.

Quem conduz os passos internos é o agente

A CLI escolhe qual skill rodar e em qual alvo. Os passos de dentro da skill — descoberta, gate, spec, tasks, código — são conduzidos pelo agente, que ajusta o roteiro contra o que encontra no disco. A CLI não tenta controlá-los.

O que abre na tela

TelaComo chegar
HOME — o menu de entrada, com três portasÉ o que abre no arranque. /home volta.
Conversa — o agente trabalhando, com a caixa de promptQualquer opção do menu leva para cá. /flow volta.
Lateral — contexto, uso da licença, árvore de arquivos e o botão de commitAparece sozinha acima de 120 colunas. Ctrl-T ou /sidebar.
/workflow — a árvore completa de features e PBIs, relida do discoComando. Esc volta.
/skills — todas as skills do ambiente, navegáveisComando. Esc volta.
/usage — o consumo da assinatura e quando ele resetaComando. Esc volta.
/settings — provider, modelo, auto-aprovação, tema e lateralComando. Esc volta.

Detalhe de cada uma em Telas.

Por onde seguir