Barroso Harness

Uma harness de agentes leves, em um binário

Feita em Go do zero: CLI imediata, provider qualquer no padrão OpenAI Chat Completions, instruções BARROSO.md, tools locais sem aprovação e gestão de contexto por orçamento medido.

Windows · macOS · LinuxYOLO sempreChat CompletionsBARROSO.md

Instalar

Baixe um binário da última release da página (5 plataformas + SHA256SUMS) ou construa do fonte:

git clone --depth 1 https://github.com/ruanbarroso/barroso-harness
cd barroso-harness
go build -o barroso-harness ./cmd/barroso-harness && ./barroso-harness -version

Atalhos de download binário (valem em qualquer plataforma — troque o nome do arquivo pelo da sua):

# linux amd64
curl -LO https://github.com/ruanbarroso/barroso-harness/releases/latest/download/barroso-harness-linux-amd64
chmod +x barroso-harness-linux-amd64
sudo install -m 0755 barroso-harness-linux-amd64 /usr/local/bin/barroso-harness
sudo ln -sf /usr/local/bin/barroso-harness /usr/local/bin/bh
bh -version

# linux arm64
curl -LO https://github.com/ruanbarroso/barroso-harness/releases/latest/download/barroso-harness-linux-arm64
chmod +x barroso-harness-linux-arm64
sudo install -m 0755 barroso-harness-linux-arm64 /usr/local/bin/barroso-harness
sudo ln -sf /usr/local/bin/barroso-harness /usr/local/bin/bh

# macos (apple silicon)
curl -LO https://github.com/ruanbarroso/barroso-harness/releases/latest/download/barroso-harness-darwin-arm64
chmod +x barroso-harness-darwin-arm64
sudo install -m 0755 barroso-harness-darwin-arm64 /usr/local/bin/barroso-harness
sudo ln -sf /usr/local/bin/barroso-harness /usr/local/bin/bh

# macos intel
curl -LO https://github.com/ruanbarroso/barroso-harness/releases/latest/download/barroso-harness-darwin-amd64
chmod +x barroso-harness-darwin-amd64
sudo install -m 0755 barroso-harness-darwin-amd64 /usr/local/bin/barroso-harness
sudo ln -sf /usr/local/bin/barroso-harness /usr/local/bin/bh

# windows (PowerShell como usuário)
$dir = Join-Path $env:LOCALAPPDATA 'BarrosoHarness\\bin'
New-Item -ItemType Directory -Force $dir | Out-Null
Invoke-WebRequest https://github.com/ruanbarroso/barroso-harness/releases/latest/download/barroso-harness-windows-amd64.exe -OutFile (Join-Path $dir 'barroso-harness.exe')
Copy-Item (Join-Path $dir 'barroso-harness.exe') (Join-Path $dir 'bh.exe') -Force
$userPath = [Environment]::GetEnvironmentVariable('Path','User')
if (($userPath -split ';') -notcontains $dir) { [Environment]::SetEnvironmentVariable('Path', (($userPath.TrimEnd(';') + ';' + $dir).Trim(';')), 'User') }
# feche e abra um novo terminal
bh.exe -version

Atalho bh: depois de instalar e colocar a pasta no PATH, abra um novo terminal e digite somente bh. Em PowerShell, use Get-Command bh para confirmar o PATH; em macOS/Linux, use command -v bh.

Validar o checksum

# Linux/macOS
curl -LO https://github.com/ruanbarroso/barroso-harness/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS 2>/dev/null || shasum -a 256 -c SHA256SUMS

# Windows PowerShell
$sum = (Get-FileHash .\\barroso-harness-windows-amd64.exe -Algorithm SHA256).Hash.ToLower()
$expected = (Select-String 'barroso-harness-windows-amd64.exe' .\\SHA256SUMS).Line.Split()[0]
if ($sum -eq $expected) { 'SHA256 OK' } else { throw 'SHA256 mismatch' }

Configurar (60 segundos)

Instale, abra um terminal novo e rode bh sem argumentos. A CLI abre o onboarding:

bh
# base URL [https://keys.barroso.tec.br/v1]:  ⏎ Enter mantém o default da casa
# api key:  (input oculto; a chave fica só neste computador)
# modelos em ordem alfabética — digite o número ou o ID
# salvo em ~/.barroso-harness/config.json

Provider, chave e modelo são gravados localmente em ~/.barroso-harness/config.json com permissões restritas; o reasoning effort começa desativado. A chave nunca vai para código, README, Git ou logs, e só é enviada ao provider que você escolher.

Para outro endpoint OpenAI Chat Completions, informe a base URL no onboarding ou troque depois com /provider. Campo opcional no config.json: context_window manual (override do valor do catálogo), max_tokens, bytes_per_token.

Usar

barroso-harness -p "liste os arquivos e diga o que você vê"   # turno único, config salva
bh                                                           # sessão interativa

Dentro da sessão:

/model            # lista o catálogo (alfabética, numerado) e troca o modelo
/model barroso-chat
/effort           # mostra o valor atual; níveis low|medium|high|xhigh|max
/effort high      # entra na próxima requisição
/effort -         # limpa; request volta SEM reasoning_effort
/provider         # troca base URL + chave; valida /models antes de salvar
/help  /exit

Sessão e contexto

No REPL o transcript fica em memória entre mensagens; trocas de /model ou /provider preservam o texto confirmado e revalidam a janela pelo catálogo. Tool calls nunca ficam órfãs: uma rodada entra no histórico só completa. bh -p não pergunta nada — se faltar provider/chave/model, encerra com instrução para rodar bh.

Como o contexto é mantido

A janela do modelo é um guardrail, não o motor da compactação. O runtime mede o request antes de mandar: se o prompt estimado + reserva de saída não caberem na context_window, a poda entra — resultados antigos e grandes de tool saem como bilhete curto, a cauda de 24 mensagens fica intocada e o piso da poda é monotônico dentro do turno. Se o provider recusar mesmo assim, entra a recuperação reativa (uma tentativa). O transcript íntegro nunca é editado: a poda reduz só o request.

O estimador de tokens se calibra ao vivo com o usage que o provider reporta (stream_options.include_usage): o par bytes-enviados/tokens-reais puxa bytes_per_token na direção medida — sem regra fixa de chars/token como verdade.

BARROSO.md

Toda sessão entra com as instruções dos BARROSO.md aplicáveis, em ordem de precedência: pasta do projeto → diretórios pais → global em ~/.barroso-harness/BARROSO.md. O mesmo texto nunca entra duas vezes; arquivo em branco não entra.

Tools yolo

Tool	Faz
`terminal_run`	comando no shell local (timeout configurável, exit code st+stderr)
`file_read`	leitura com números de linha e janelas `start/limit`
`file_write`	escreve/sobrescreve; cria diretórios pais
`file_append`	anexa ao fim
`file_copy`	copia (cp/copy do sistema)
`list_dir`	lista diretório recursivo até depth 3
`ctx_read / ctx_write / ctx_append`	contexto vivo da sessão: o arquivo de estado que o próprio modelo cur — lê, reescreve e anexa
`session_search / session_retrieve`	busca no log da sessão e recupera o texto inteiro de um evento (inclusive tool results arquivados em blob)
`web_search / web_fetch`	busca SearXNG (`search_url` na config) e leitura de página com strip de HTML
`skills_list / skill_read`	catálogo de skills de `skills/` do projeto e global
`task_spawn / task_status / task_result`	subagentes assíncronos (config `subtasks: true`); o filho tem todas as tools, exceto delegar
tools MCP	servidores stdio/HTTP da config `mcp_servers` entram no mesmo catálogo — tool externa nunca sombreia a built-in

Modo YOLO significa: essas ferramentas executam direto, com os privilégios do usuário no sistema. Não há allowlist nem diálogo de confirmação.

Sessões e contexto vivo

Cada sessão ganha um event log append-only em SQLite (~/.barroso-harness/sessions.db): mensagens, tool calls/results (resultados grandes vão para blobs com preview), guardrails e resets. O REPL retoma conversa com /resume e dá título com /save; -p grava no mesmo log e anuncia o id no stderr em terminal.

O contexto vivo é o extrato curado pelo próprio modelo — objetivo, decisões, fatos com referência, pendências — versionado em <sessão>.ctx-vivo.md. O log descreve o passado; o contexto vivo carrega o presente.

ACP

bh -acp vira um servidor ACP (JSON-RPC 2.0 por stdio): initialize, session/new, session/prompt com streaming de session/update e session/cancel. É o caminho para editores/clientes dirigirem a mesma harness.

Status do roadmap

Entregue: sessões persistentes + event log + retomada; contexto vivo (ctx_read/ctx_write/ctx_append); ACP por stdio (bh -acp); skills (skills_list/skill_read); MCP stdio/HTTP; web_search/web_fetch; subagentes assíncronos com fila e sem delegação. Próximo: editar histórico de linha com ↑/↓, command palette e catálogo MCP gerenciado pela CLI (/mcp).