Você já entrega ao seu agente de IA seu código, seu terminal e suas sessões de depuração mais difíceis. Agora entregue a ele seus livros contábeis — com cada lançamento que ele redigir passando por uma pré-visualização que você aprova e um validador que confere a matemática. A ferramenta de linha de comando bea instala com dois comandos, trabalha com arquivos de razão em texto simples na sua própria máquina e não precisa de conta para escrituração local.
Instale em dois comandos
Existem duas formas publicadas de obter o mesmo comando. Escolha a que se adequa à sua máquina, depois confirme que ele responde com sua versão:
$ uv tool install beancount-io
$ brew install bex-co/tap/bea
$ bea --version
bea 0.1.0A distribuição Python é beancount-io e o executável que ela instala é bea, atualmente na versão 0.1.0. O caminho uv funciona em qualquer lugar com Python 3.12 ou mais recente; o caminho Homebrew cobre macOS e Linux. O passo a passo completo está na página de instalação, com os mesmos passos no guia de início rápido da CLI.
A primeira tarefa do seu agente leva minutos
Você não precisa de um novo agente, um plug-in ou uma migração de plataforma. Cole isto no agente de IA com acesso ao shell que você já usa, em um novo diretório de demonstração vazio:
Você tem acesso ao shell e a CLI
beainstalada. Primeiro executebea --helpe leia o que ela oferece. Depois, em um NOVO diretório de demonstração vazio (não toque em nenhum razão existente): 1) crie um razão em USD abrindo Assets:Checking em 1000 em 2026-08-01; 2) adicione uma compra de 12,50 USD com a descrição "Café" em Expenses:Dining em 2026-08-02; 3) executebea check; 4) reporte o saldo de Assets:Checking juntamente com a consulta BQL exata que você usou. Resultado esperado: 987,50 USD.
Os mesmas etapas como comandos simples:
$ bea --no-input init demo-books --currency USD --date 2026-08-01 --opening-balance "Assets:Checking 1000"
$ cd demo-books
$ bea add transaction --date 2026-08-02 --narration "Coffee" --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
$ bea check
$ bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"Resultado esperado: Assets:Checking mantém 987,50 USD — 1000 menos 12,50, validado por check e reportado com a consulta que o calculou. Quando seu agente de volta esse número, ele completou seu primeiro ciclo fechado: rascunho, validação, relatório. O guia de agentes constrói sobre o mesmo ciclo com duas receitas mais completas — importar um CSV de banco com revisão prévia, e responder uma pergunta de saldo a partir da saída de consulta.
O que você precisa, e para quem é isso
Um terminal, uma conexão de internet e Homebrew ou uv com Python 3.12 ou mais recente. Importação local, consulta, relatório e comandos de verificação não precisam de conta no Beancount.io, e seus arquivos de razão ficam em um diretório que você escolhe como texto plano que você pode comparar, fazer backup e controlar por versões.
Isso se encaixa para fundadores técnicos que mantêm seus livros contábeis em uma startup, desenvolvedores independentes que já vivem em um terminal e construtores de agentes que procuram um razão contra o qual um IA possa redigir alterações sem gravações silenciosas. Se seus livros já estão em um produto em nuvem, a resposta honesta é diferente — veja a seção de comparação abaixo.
O caminho hospedado é opcional e separado
Nada acima requer uma conta ou envia seu razão para qualquer lugar. Dois extras fazem isso, e ambos são deliberadamente separados da instalação da CLI:
bea askresponde perguntas sobre um razão local através do serviço de IA. Precisa do extra ask —uv tool install 'beancount-io[ask]'— mais suas credenciais do Beancount.io. A instalação padrão omite as dependências de IA até você solicitá-las.- O servidor MCP e os razões hospedados também iniciam sessão com sua conta Beancount.io para autorizar o acesso. Habilidades de agente para Beancount são essenciais no repositório do produto e são carregadas no seu agente separadamente — instalar a CLI não as instala ou configura.
Comece localmente; conecte a hospedagem apenas se quiser.
Prova: um agente, três linhas, livros verificados
Uma afirmação de lançamento é tão boa quanto sua reprodução. Então, junto com a CLI, vem um desafio sintético de três linhas com uma resposta derivada de aritmética antes que qualquer relatóriorodasse: livros abrem em 2026-09-01 com 1000 USD em conta corrente, um pagamento da conta indica uma fatura de 2.000,00 USD de pagamento do cliente, uma conta de hospedagem de −29,00 USD e uma visita a café de −12,50 USD, e as respostas esperadas são 2958,50 USD em conta corrente (1000 + 2000 − 29 − 12,50) e 1958,50 USD de lucro de setembro (2000 − 29 − 12,50).
Um verificador da CLI executando tudo em um novo diretório temporário: pré-visualização reporta 3 prontos e não escreve nada, a primeira aplicação escreve 3 lançamentos, um re-import idêntico escreve 0, com bytes preservados, uma gravação desbalanceada (−5 em conta corrente contra +4 em alimentação) sai com código 1 e bytes preservados, e check retorna válido. Os inputs exatos podem ser baixados como main.bean, statement.csv e rules.toml.
Então um agente real executou o mesmo desafio: cliente muse 1.1.1 (Muse Code) com modelo muse-spark-1.3-contributor, em modo headless, 22 chamadas de ferramenta, saída 0, sem intervenção humana — e, crucialmente, nenhum rules.toml fornecido, então o agente derivou sua própria categorização. Ele pré-visualizou 3 prontos, aplicou 3 lançamentos, executou uma verificação limpa e reportou 2958,50 USD em conta corrente e 1958,50 USD de lucro de setembro, ambos re-verificados depois contra os valores esperados independentes. O registro completo — o prompt real, cada chamada de ferramenta e a única falha real que o próprio agente diagnosticado (um bloqueio de cache em sandbox, corrigido apontando XDG_CACHE_HOME para dentro do diretório de trabalho) — está publicado como execução registrada, com o transcriptorial bruto ao lado.
A sessão de terminal abaixo é uma reprodução determinística daquele caminho de trabalho, reconstruída a partir dos downloads canônicos e demonstrando com demo-replay.sh — ele reencena os comandos, portanto inclui os as regras de categorização por determinismo, em vez de re-derivá-los. A saída capturada em demo-replay.txt carrega a mesma informação que vê-la:
$ bea --version
bea 0.1.0
$ bea import (preview)
csv → Assets:Checking: 3 ready, 0 exact duplicates, 0 possible duplicates
$ bea import --apply
Wrote 3 entries to $WORK/books/main.bean.
$ bea check
$WORK/books/main.bean: no errors
$ bea balance Assets:Checking
Checking 2,958.50 USD
$ bea report income-statement -t 2026-09
Net Profit: 1,958.50 USD
checking: 2958.50 USD (expected)
profit: 1958.50 USD (expected)
REPLAY OK: preview 3/0, applied 3, check clean, 2958.50 / 1958.50 USD.Dois limites honestos vêm com essa evidência. É verificação de saída de CLI de uma execução de um cliente em dados sintéticos — não um benchmark de um modelo, e não garante nada sobre outros clientes ou uso de produção sem supervisão. E um check que passa prova que o razão está equilibrado, mas nunca que o agente escolheu a conta certa para o café: a avaliação de categoria é do agente, a validação estrutural é do bea. Um teste de três linhas verifica o ciclo, não as decisões contábeis.
Escolhendo entre ferramentas
Se você está escolhendo um razão para fluxos de trabalho de agentes em vez de optar por este, leia a comparação de cinco ferramentas: Beancount.io, Xero, QuickBooks Online, Puzzle e hledger avaliadas pelos mesmos sete critérios de fluxo de trabalho de agentes — instalação, autenticação, escopo de leitura/escrita, dados locais versus nuvem, pré-visualização e validação, saída estruturada e comportamento de re-import, com fontes oficiais datadas verificadas em 2026-09-10. O Beancount.io é a única ferramenta ali com execução completa observada por trás; a página diz isso, nomeia seu publicador e rotula o que não testou.
Para onde seguir
- Página de instalação — os dois comandos, a primeira tarefa e downloads de desafios em um só lugar.
- Início rápido da CLI — instalação mais o exemplo trabalhado de 987,50 USD.
- Guia de agentes — duas receitas: importação de CSV com revisão prévia, e verificações de saldo a partir da saída de consulta.
- Execução registrada — o relato completo prova com metodologia, falhas e limitações.
- Comparação de cinco ferramentas — qual ferramenta se encaixa melhor para cada fluxo de trabalho de agente.
Simplifique sua gestão financeira
A forma mais rápida de julgar tudo isso é a avaliação acima: instale bea, cole a tarefa na (dh) de sua, e verifique os 987,50 USD você mesmo. O Beancount.io fornece contabilidade de texto simples que mantém cada saldo reprodutível e cada uma das etapas exportável — sem caixas-pretas, sem retenção de fornecedor. Em dê ao seu agente seu primeiro razão e veja o que ele devolve.
