Instalação · Makuco

Pré-requisitos

Node.js ≥ 20 + npm.
O pacote makuco-<versão>.tgz da CLI, fornecido pelo time responsável pela ferramenta.

Para usar a CLI interativa (makuco sem argumento), some a isto:

Claude Code instalado e autenticado — é ele quem executa os turnos.
Terminal com TTY.

Não instale com --no-optional nem --omit=optional

A interface da CLI carrega uma biblioteca nativa que exige o runtime Bun, e ele vem como dependência do pacote makuco — você não instala nada a mais. Excluindo as dependências opcionais, o Bun não é baixado e a CLI interativa sai com makuco: o runtime Bun não foi instalado. O makuco init continua funcionando.

Instalar a CLI

A CLI é distribuída como um pacote .tgz (ex.: makuco-3.1.0.tgz). Há duas formas de usá-lo.

Opção A — instalar globalmente (recomendado)

Instala o binário makuco no PATH a partir do arquivo baixado (ajuste o nome para a sua versão):

npm install -g ./makuco-3.1.0.tgz

Confira que o binário ficou no PATH:

makuco --version

Com a CLI global você chama makuco, makuco init e makuco update direto, de qualquer diretório — é o formato que o resto desta documentação assume. Para subir de versão, rode o mesmo npm install -g com o .tgz da versão nova.

Opção B — rodar o `.tgz` sem instalar

Rode o arquivo baixado com npx, sem instalar nada globalmente:

npx -y ./makuco-3.1.0.tgz init

Comandos

Comando	O que faz
`makuco`	Abre a CLI interativa no projeto. Desde a 3.2.0.
`makuco run <skill> [alvo]`	Roda um turno de uma skill sem interface. Desde a 3.2.0.
`makuco init`	Instala skills, agentes e MCPs no projeto. Interativo.
`makuco init --force`	Sobrescreve artefatos já existentes, sem perguntar.
`makuco update`	Atualiza os ativos do pacote preservando o que você alterou.
`makuco unit sync`	Atualiza o conteúdo da unidade a partir do Hub. Desde a 3.1.0.
`makuco skill\|agent\|prompt add <endereço>`	Instala um item avulso de qualquer unidade. Desde a 3.1.0.
`makuco --version`	Mostra a versão da CLI.

Referência completa de cada comando, flags e códigos de saída em Comandos. A CLI interativa tem seção própria em CLI Interativa.

Rodar a inicialização

Nas Opções B e C o init já vai junto no comando. Instalando globalmente (Opção A), rode-o à parte, na raiz do projeto:

makuco init

Prompts do `makuco init`

O comando é interativo e pergunta:

Ferramenta de IA (multiseleção, até 2):
- Claude Code → instala em .claude/
- VSCode + Copilot → instala em .github/
Pasta raiz — padrão . (diretório atual).
Usa Azure DevOps? — não por padrão. Respondendo sim, pergunta o projeto e, se o VSCode estiver selecionado, o PAT. Veja Azure DevOps.
Unidade — a lista vem do Makuco Hub. A escolha fica registrada no projeto e não é perguntada de novo. Desde a 3.1.0 — antes disso a lista vinha embutida no binário e o conteúdo era clonado por chave SSH.
Clonar repositórios para repos/? — não por padrão. Respondendo sim, pergunta o método de autenticação (SSH ou HTTPS) e a URL de cada repositório, e permite clonar mais de um.

init é uma reinstalação completa

O makuco init sobrescreve as skills instaladas e repergunta as configurações — ele não é só um reindex. Quando ele perguntar se deseja sobrescrever o MAKUCO.md existente, responda não: sobrescrever descarta as descrições de repositório já preenchidas. E não use --force para reindexar — --force sobrescreve o MAKUCO.md sem perguntar, apagando o índice e as políticas do time. Para atualizar ativos preservando o que você mudou, use o makuco update e o makuco unit sync.

Manter em dia

Os ativos do projeto vêm de duas origens, e cada uma tem o seu comando:

# Ativos entregues pelo pacote da CLI (skills base, agentes, hooks, MCPs, MAKUCO.md).
makuco update
 
# Conteúdo da unidade e itens avulsos, vindos do Makuco Hub. Desde a 3.1.0.
makuco unit sync

Um comando não substitui o outro

A partir da 3.1.0, o conteúdo da unidade não entra no makuco update. Rodar só o update deixa a unidade parada — o próprio comando avisa quantos itens vêm do Hub e manda rodar o makuco unit sync.

Flags, comportamento em CI e códigos de saída de cada um em Comandos → makuco update e Comandos → makuco unit sync.

Workspace multi-repo

O makuco init sempre cria a pasta repos/ na raiz do workspace, então a existência dela não diz nada:

repos/ com ao menos uma sub-pasta de repositório → workspace multi-repo. O contexto de código vive em repos/<nome>/.makuco/docs/codebase/.
repos/ só com o README.md → repositório único. O contexto vive em .makuco/docs/codebase/ na raiz.

O fluxo continua único, na raiz — multi-repo não significa um Makuco por repositório. Só o contexto de código é por repo; MAKUCO.md, docs/modules/, templates/, integrations/ e STATE.md seguem no workspace.

Cada repositório é listado no MAKUCO.md, na seção entre os marcadores makuco:repos:start e makuco:repos:end. Essa seção pertence ao Makuco: quem escreve nela é o makuco init (a lista) e a skill makuco-project-research (a descrição e o mapa de módulos de cada repo). Não edite à mão, e não mexa nos marcadores.

Depois de adicionar um repositório manualmente com git clone:

Rode makuco init novamente para reindexar o MAKUCO.md (respondendo não ao sobrescrever).
Rode a skill makuco-project-research para preencher a descrição de cada repositório.

Estrutura de pastas, a divisão do que é por repo e a anatomia do índice em Configurações → A pasta repos/.

Configurar o Makuco MCP

Para habilitar o Makuco MCP (que usa o SonarQube), veja o passo a passo em Configurações.

Verificação

Confira que o init criou:

.makuco/ (com README.md, templates/, docs/).
.claude/skills/, .claude/agents/, .claude/prompts/ (Claude Code).
.github/skills/, .github/agents/ (VSCode, se selecionado).
MAKUCO.md e repos/ na raiz.

Detalhamento completo do que é criado em Configurações.

Abrir a CLI interativa

Com o projeto inicializado:

cd meu-projeto
makuco

A tela inicial abre com três portas: desenvolver uma nova feature, continuar uma em andamento, ou conversar livremente. Veja CLI Interativa.