BantuByte CLI

Assistente de programação com IA, no teu terminal. Conversa em streaming, edição de ficheiros, execução de comandos, sub-agentes e integração Model Context Protocol (MCP) — tudo a partir da linha de comandos.

Atualmente com o modelo Kimi K2.6; a camada de modelos é extensível e novos modelos vão ficar selecionáveis em versões futuras.

BantuByte é um serviço. O acesso requer uma conta e um plano ativo em bantubyte.dev.

---

Início rápido

1. Instalar

pip install bantubyte

Requer Python 3.10 – 3.13. Funciona em macOS, Linux e Windows.

2. Autenticar

bantubyte login

Abre o browser, corre o fluxo OAuth2 (PKCE) com a tua conta Google e guarda os tokens em ~/.bantubyte/auth.json (permissão 0600 em sistemas POSIX). O CLI renova os tokens automaticamente antes de expirarem.

3. Começar a conversar

bantubyte                       # REPL interativo
bantubyte --resume              # escolher uma sessão anterior de uma lista
bantubyte --resume <session-id> # retomar uma sessão específica

O REPL aceita:

• Texto simples — enviado ao modelo como mensagem.
• /<comando> — um comando (ver abaixo).
• Entrada multilinha com Esc-Enter (um único Enter envia quando ainda não há nova linha).

---

Comandos

Comando	Descrição
/help	Lista todos os comandos.
/clear	Inicia uma sessão nova no mesmo REPL.
/exit, /quit	Sai do REPL de forma limpa.
/login, /logout	Re-autentica ou revoga as credenciais.
/config	Ver e editar ~/.bantubyte/config.json.
/model	Trocar de modelo.
/theme	Alternar entre tema escuro e claro.
/permissions	Editar as listas allow/deny de ferramentas do projeto.
/session	Ver, retomar ou apagar sessões anteriores.
/usage	Uso de tokens + quota mensal do teu plano.
/cost	Custo estimado da sessão atual.
/compact	Forçar uma compactação de contexto.
/mcp ...	Gerir servidores MCP — ver secção seguinte.

---

MCP — Model Context Protocol

O MCP permite ligar servidores de ferramentas externos ao CLI sem alterar o BantuByte. A comunidade publica servidores para sistemas de ficheiros, git, postgres, sqlite, GitHub, Puppeteer, Slack e muitos mais — ver o catálogo oficial.

Configurar servidores

Cria ~/.bantubyte/mcp.json com um mapa mcpServers. Cada entrada declara como arrancar um servidor e quanto tempo esperar por ele.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${HOME}/Projects"
      ],
      "timeout_ms": 15000,
      "tool_timeout_ms": 60000
    },

    "time": {
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}

Referência de campos:

Campo	Default	Notas
command	obrigatório	Executável (resolvido via PATH, incl. .cmd/.bat no Windows) ou caminho absoluto.
args	[]	Argumentos passados ao command.
env	{}	Variáveis de ambiente adicionais.
enabled	true	Define false para ignorar o servidor no arranque.
timeout_ms	10000	Timeout do handshake + tools/list (máx 120 s).
tool_timeout_ms	1800000 (30 min)	Timeout por chamada (tools/call). Intervalo: 1 s – 4 h.

A expansão ${VAR} é suportada em command, args e env com a sintaxe ${VAR} (erro se não definida) e ${VAR:-default}.

Overrides por projeto

Coloca um .bantubyte/mcp.json na pasta de um projeto. O CLI procura subindo a partir da pasta atual e funde-o sobre a config global. As entradas do projeto sobrepõem-se às globais com o mesmo nome.

Gerir servidores a partir do REPL

/mcp                          # alias de /mcp list
/mcp list                     # mostra cada servidor com estado, versão, nº de ferramentas
/mcp info <name>              # detalhe completo
/mcp logs <name>              # último stderr desse servidor
/mcp reload                   # relê o mcp.json e reinicia tudo
/mcp enable <name>            # ativa e recarrega
/mcp disable <name>           # desativa e recarrega
/mcp prompts [server]         # lista templates de prompt
/mcp prompt <server> <name> [key=value ...]

O subsistema MCP é resiliente: auto-reconexão com backoff em falhas transitórias, encerramento gracioso dos subprocessos, propagação de cancelamento (Ctrl-C), e sanitização Unicode das descrições de ferramentas para defesa contra ataques de injeção.

---

Configuração

As definições vivem em camadas, com precedência env > projeto > utilizador > defaults:

Camada	Ficheiro	Propósito
Defaults	código	Valores sensatos por omissão.
Utilizador	~/.bantubyte/config.json	Preferências (tema, modelo, etc.).
Projeto	<cwd>/.bantubyte/config.json	Listas allow/deny de ferramentas do projeto.
Env	variáveis BANTUBYTE_*	Override no arranque.

Variáveis de ambiente úteis:

• BANTUBYTE_MODEL — sobrepõe o modelo default.
• BANTUBYTE_VERBOSE=1 — ativa logging detalhado para ficheiro.
• BANTUBYTE_TOOL_PERMISSION_MODE — default, auto-allow ou always-ask.
• BANTUBYTE_CONFIG_DIR — sobrepõe ~/.bantubyte/.

---

Sessões

Cada conversa é uma sessão, persistida como JSONL em ~/.bantubyte/sessions/<id>.jsonl. Retoma com bantubyte --resume para escolher de uma lista, ou bantubyte --resume <id> para ir direto.

A corrupção de uma sessão (uma linha má, fim truncado) não impede o carregamento — o CLI regista cada entrada descartada e continua com as mensagens recuperadas. O /session e o seletor de resume marcam sessões danificadas com ⚠.

---

Armazenamento

~/.bantubyte/
├── config.json            # definições do utilizador
├── auth.json              # tokens OAuth (0600 em POSIX)
├── mcp.json               # declarações de servidores MCP
├── sessions/              # transcrições JSONL, uma por sessão
├── logs/                  # logs rotativos
└── history                # histórico de input do REPL

Cada diretório é criado com permissões restritivas (0700 em POSIX).

---

Resolução de problemas

Not authenticated. Run 'bantubyte login' first. — o token expirou ou nunca foi criado. Corre bantubyte login. Se o browser não abrir, copia o URL impresso no terminal.

Servidor MCP preso em "reconnecting" — corre /mcp logs <name> para ver o stderr. Causas comuns: argumento em falta, caminho de comando errado no Windows, ou download de dependência do servidor a exceder o timeout (sobe o timeout_ms).

Onde estão os logs? — ~/.bantubyte/logs/bantubyte.log, rotado diariamente. Define BANTUBYTE_VERBOSE=1 para granularidade DEBUG.

---

Compatibilidade

• Python: 3.10 – 3.13.
• SO: macOS, Linux, Windows.
• Transportes MCP (v1): stdio. HTTP / SSE / WebSocket planeados para v2.

---

Licença

Proprietário — Todos os direitos reservados. © BantuByte / Pilartes Lander.

Este pacote é distribuído para uso com o serviço BantuByte. Não é software livre nem open-source. A utilização está sujeita aos termos em bantubyte.dev.