kafox

CLI oficial do Kafox no estilo opencode: login por device code (SSO), modelos, saldo em reais, temas e conversa pelo gateway.

Instalar

npm install -g kafox-cli

O comando instalado e kafox. Alternativa sem npm:

npm install -g https://kafox.dev/static/downloads/kafox-cli-0.9.5.tgz

Requisito: Node.js 22.5+.

Login

kafox login

O terminal vira uma tela de login (arte grande em cima, link no centro): abra a URL https://kafox.dev/cli?code=..., entre na sua conta e clique em Autorizar. A sessao fica em ~/.kafox/token.json (permissao 600). No primeiro kafox sem sessao ele pergunta se quer entrar e abre a mesma tela.

Comandos

| Comando | O que faz | | --- | --- | | kafox | abre a interface de tela cheia | | kafox --allow-all | abre ja aprovando tudo (mesmo que KAFOX_ALLOW_ALL=1) | | kafox login / logout / whoami | sessao da conta | | kafox models | lista modelos e precos por 1M de tokens | | kafox pricing | pacotes de recarga | | kafox balance | saldo atual | | kafox key | cria uma API key | | kafox ask "pergunta" [-m modelo] | pergunta ao gateway | | kafox agent "objetivo" [-y] [--max-steps 12] [--json] | roda o agente sem TUI (script/CI) | | kafox history [n] | lista as conversas salvas (titulo - data + como retomar) | | kafox resume [codigo] | retoma uma conversa; sem codigo abre o seletor na tela | | kafox continue / kafox -c | volta para a conversa mais recente | | kafox status | conta, saldo e gateway | | kafox theme | seletor de tema | | kafox background [arquivo\|url] | imagem de fundo da interface (off remove) | | kafox compact / clear | compacta / limpa o contexto do REPL |

Conversas salvas

Toda conversa fica em ~/.kafox/chats/<codigo>.json. Ao sair com Ctrl+C a CLI mostra o codigo:

  Retome esta conversa: kafox --resume 3f1c9a0b

kafox history lista da mais nova para a mais antiga, cada uma com o comando que retoma (e kafox history 20 mostra so as 20 ultimas):

hello world em python, tem como fazer um sis... - 28/10
kafox resume 3f1c9a0b

nessa cli que voce ve, tem como fazer alguma co... - 27/10
kafox resume 8ad2f19c

kafox resume (sem codigo) abre o seletor com os titulos das conversas — setas ou a roda do mouse navegam, clique ou Enter retomam a conversa escolhida. kafox resume 3f1c aceita o codigo inteiro ou so o comeco dele, e kafox continue (ou -c) vai direto para a ultima.

A conversa guarda o modelo, o tema e o modo rodar tudo: se voce retomar um chat que estava com a aprovacao automatica ligada, ele volta ligado (e o contrario tambem). kafox --allow-all continua valendo por cima de tudo.

Imagem de fundo

/background ~/Imagens/ponte.jpg (ou uma URL https) desenha a foto atras da conversa, com o texto por cima. Aceita PNG e JPG; a imagem e escurecida para nao atrapalhar a leitura e se ajusta sozinha ao tamanho do terminal. /background off remove, e a escolha fica em ~/.kafox/config.json.

Colar imagem (Ctrl+V)

Copie um print ou um recorte e aperte Ctrl+V na interface: a imagem entra como anexo do proximo turno, com preview dentro da caixa de texto, e vai junto com a mensagem para qualquer modelo com visao. Vale o mesmo limite do /image (3 por mensagem) — clique no ✕ do preview para tirar uma.

A leitura usa o que existe na maquina: PowerShell no Windows, pngpaste (ou osascript) no macOS, wl-paste no Wayland e xclip no X11. Se nenhum estiver instalado, a CLI avisa e o /image <arquivo> continua funcionando.

Alguns terminais consomem o Ctrl+V antes da CLI ver (o paste deles e Ctrl+Shift+V). Nesse caso use /paste, que le a area de transferencia do mesmo jeito. Sem imagem copiada, o Ctrl+V//paste cola o texto, como um paste comum.

Agentes e subagentes

O agente tem a ferramenta spawn_subagent: ele lança subagentes com objetivo próprio, cada um num contexto separado, e recebe só o relatório final. Vão até 3 tarefas por chamada e as independentes rodam em paralelo. Por padrão o subagente só lê (read_file, list_dir); escrever, editar ou executar exige declarar a ferramenta na tarefa — e continua passando pela aprovação normal (ou pelo /allow).

kafox agent "revise src/agent.js e aponte bugs" --max-steps 8
kafox agent "rode os testes do backend e resuma as falhas" -y --json

Para ver o que os subagentes da sessão fizeram (objetivo, ferramentas, tempo e se terminaram), use /agents — o mesmo comando funciona no REPL e na TUI.

Na interface: digite / para o menu (↑/↓ navega, Tab completa, Enter executa), /model abre o seletor de modelo e /theme o de tema (↑/↓, clique do mouse, Enter aplica, Esc cancela). A resposta chega em streaming, com bloco Thinking quando o modelo manda o raciocinio. PgUp/PgDn ou a roda do mouse rolam a conversa; Ctrl+Y copia a ultima resposta, Ctrl+V cola uma imagem copiada e F2 solta o mouse para selecionar texto.

Enquanto o modelo trabalha a caixa de texto mostra trabalhando... com os pontinhos correndo, e o nome do modelo aparece fora dela, na linha de baixo. Se a rede cair (fetch failed), a CLI tenta de novo sozinha ate 20 vezes dobrando a espera (3s, 6s, 12s, 24s... ate 60s) e mostra a contagem na linha do modelo; Esc cancela a espera na hora. O agente nao tem limite de passos: ele continua ate terminar.

Nao precisa esperar a resposta para escrever de novo: Enter enfileira a mensagem (a fila aparece acima do input e roda em ordem assim que a atual termina). Para parar a IA na hora, Esc duas vezes — o primeiro Esc so avisa, o segundo interrompe o passo em andamento e guarda na conversa o que ja tinha chegado.

Demais comandos: /help, /models, /balance, /pricing, /key, /login, /logout, /whoami, /mcp, /allow, /theme, /background, /image, /paste, /clear, /compact, /status, /exit.

O /theme traz 29 temas (default, dark, light, brutalist, neon, paper, dracula, nord, gruvbox, monokai, tokyo-night, catppuccin, solarized, midnight, ocean, forest, sunset, plum, synthwave, cyberpunk, amoled, matrix, terminal, solarized-light, rose, mint, sepia, ice e high-contrast).

Ferramentas do agente

Com o saldo em dia a TUI deixa o modelo ler e mexer no projeto. Cada chamada aparece como um card na conversa, com o diff do que foi editado.

| Ferramenta | O que faz | | --- | --- | | read_file | le um arquivo (com offset/limit) | | list_dir | lista uma pasta | | write_file | cria ou reescreve um arquivo | | edit_file | troca um trecho exato do arquivo | | run_command | roda um comando no diretorio de trabalho |

run_command sai como uma janela de terminal: o comando em $ ..., a saida dentro da janela (erro em vermelho) e o rodape com exit e o tempo; enquanto roda, aparece o spinner com o tempo decorrido. Ferramentas de MCP usam a mesma janela, com os argumentos e o resultado.

Quem escreve, edita ou executa pede aprovacao num modal com tres opcoes: Permitir uma vez, Permitir sempre (roda tudo nesta sessao, sem perguntar de novo — inclusive as proximas ferramentas do mesmo passo) e Negar. Navegue com ↑/↓ (ou clique) e confirme com Enter; a libera sempre, y uma vez, n/Esc nega. Todo caminho fica travado dentro do diretorio de trabalho.

Para ja abrir liberado, use kafox --allow-all (ou KAFOX_ALLOW_ALL=1), e dentro da sessao /allow liga e /allow off volta a perguntar. Com o modo ligado a barra lateral mostra rodando tudo.

Servidores MCP

Ferramentas de servidores MCP entram no mesmo loop, com o prefixo mcp__servidor__ferramenta. Configure em ~/.kafox/mcp.json (ou ./mcp.json do projeto, que vence):

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"]
    },
    "remoto": {
      "type": "remote",
      "url": "https://exemplo.com/mcp",
      "headers": { "authorization": "Bearer ..." }
    }
  }
}

O servidor local roda por stdio e o remoto fala HTTP/SSE. Use enabled: false para desligar um servidor. Na TUI a barra lateral mostra o status de cada um (e o motivo do erro quando falha) e /mcp lista tudo; /mcp reload reconecta.

Configuracao

• KAFOX_API_URL ou ~/.kafox/config.json (api_url) troca a API.
• ~/.kafox/config.json guarda model, theme, background e a API key criada automaticamente no primeiro ask.
• ~/.kafox/mcp.json guarda os servidores MCP.

A CLI so responde se a conta tiver saldo; sem credito ela avisa e nao chama o gateway. Nao existe limite de mensagens por chamada nem de passos do agente: a conversa continua ate o modelo terminar (ou ate voce apertar Esc). O unico freio e o saldo.

Escopo

O kafox autentica na conta, lista modelos, mostra saldo, conversa pelo gateway e roda tarefas no projeto: le e edita arquivos, executa comandos (sempre com aprovacao) e chama servidores MCP configurados.