Configuração · Makuco

Precedência

Quatro fontes, da mais fraca para a mais forte:

padrões da CLI  <  ~/.makuco/config.yml  <  <projeto>/.makuco/config.yml  <  flags

Cada camada sobrepõe só as chaves que declara. Um config.yml de projeto que traz apenas theme: não apaga o provider: que o global escolheu.

`.makuco/config.yml`

provider: claude-code
models:
  claude-code: opus
autoApprove: false
theme: one-dark
sidebar: auto

Chave	Valores	Padrão	O que faz
`provider`	`claude-code` · `custom-sdk`	`claude-code`	Quem executa o turno.
`models`	mapa `provider → modelo`	`{}`	O modelo preferido por provider. Ausente ⇒ vale o default do agente.
`autoApprove`	`true` · `false`	`false`	Auto-aprovar as ações seguras.
`theme`	`one-dark` · `dark` · `light` · `dracula` · `nord`	`one-dark`	Paleta da interface.
`sidebar`	`auto` · `hide`	`auto`	`auto` mostra a lateral em terminal largo; `hide`, nunca.

Mudar pelo /settings, /model, /theme, /sidebar ou Ctrl-T grava no arquivo do projeto. Flags não gravam nada.

O arquivo tem dois donos

O makuco init também escreve nesse arquivo — version, agents e telemetry são dele. As duas metades convivem: a CLI interativa ignora as chaves do init em silêncio e só avisa sobre chave que não tem dono nenhum, que é o caso do erro de digitação (them: em vez de theme:).

Config torta nunca é fatal: a CLI abre com os padrões e avisa o que ignorou. Um models: com uma entrada errada perde só aquela entrada, não o mapa inteiro.

Flags de `makuco`

Flag	O que faz
`--cwd <caminho>`	Raiz do projeto. Padrão: diretório atual.
`--provider <id>`	Provider do agente nesta execução.
`--model <nome>`	Modelo nesta execução. Aceita alias (`opus`, `sonnet`, `haiku`). Não é gravado.
`--auto`	Roda cada passo sem confirmar, no motor headless.
`--auto-approve`	Aprova todas as permissões, acima da política.
`--yolo`	Começa em auto total. Alterne depois com `/yolo` ou `Shift+Tab`.
`--theme <nome>`	Tema nesta execução. Nome desconhecido cai no padrão.
`--version`	Versão instalada.

Nem --provider nem --model nem --theme têm padrão embutido na flag — é isso que faz a sua config valer quando você não passa a flag.

Providers

Id	O que é	Requisitos
`claude-code`	O padrão. Fala com o Claude Code pelo Agent Client Protocol.	Claude Code instalado e autenticado.
`custom-sdk`	Fala direto com a API da Anthropic, sem passar pelo protocolo.	`ANTHROPIC_API_KEY` no ambiente.

custom-sdk não carrega skills nativamente

Provider sem suporte a skills recebe o corpo do SKILL.md embutido no prompt, em vez da invocação nativa. Funciona, mas é mais caro em tokens e não tem acesso às ferramentas do Claude Code. O caminho suportado para o fluxo Makuco é o claude-code.

Trocar de provider no /settings vale a partir do passo seguinte, e traz junto o modelo gravado daquele provider.

Modelos

A lista que aparece no /model vem do agente, quando há uma sessão aberta — inclusive respeitando um availableModels restrito que você tenha no settings.json do Claude Code. Antes de qualquer sessão, a CLI mostra a semente do provider:

Provider	Ids
`claude-code`	`default` · `sonnet` · `opus` · `haiku`
`custom-sdk`	`claude-opus-5` · `claude-sonnet-5` · `claude-fable-5` · `claude-haiku-4-5-20251001`

default é o "sem preferência" — o que o Claude Code recomenda no momento.

Preferência que o agente não consegue resolver vira aviso, e o turno segue no modelo padrão dele. Nunca aborta.

Temas

one-dark (padrão), dark, light, dracula, nord.

/theme abre o modal com pré-visualização: mover o cursor repinta a tela sem gravar; só o Enter escreve no config.yml, e o Esc desfaz.

Variáveis de ambiente

Variável	Para que serve
`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`	Credencial do Claude. Sem elas e sem `~/.claude`, a CLI diz que você provavelmente não está autenticado, em vez de só dizer que o turno falhou.
`CLAUDE_CODE_EXECUTABLE`	Aponta para o executável do Claude Code, quando ele não está no `PATH`.
`MAKUCO_DISABLE_MOUSE`	Desliga o mouse por inteiro.
`MAKUCO_DISABLE_TERMINAL_TITLE`	Impede a CLI de escrever o título da aba do terminal.
`MAKUCO_HUB_URL`	Aponta outro Makuco Hub. Precisa usar `https:`, exceto em `localhost`.
`MAKUCO_HUB_ALLOW_INSECURE`	Libera um endereço `http:` fora de `localhost`. Só liga com `1`, `true`, `yes` ou `on`.

O título da aba

Com a CLI aberta, a aba do terminal lê 🐦 Makuco — <pasta>:<branch>. Ao sair, o título é limpo e o prompt do shell repinta o dele.

MAKUCO_DISABLE_TERMINAL_TITLE desliga.