bantubyte 1.2.7

AI-powered coding assistant CLI — powered by Kimi K2.6 via the BantuByte platform (more models coming)

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.