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`	lê o contexto vivo da sessão (arquivo de trabalho do agente)

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.

Roadmap

Slice 1: sessões persistentes + contexto vivo editável (ctx_write/ctx_append), inicialização dos agentes, ACP por stdio e skills. Slice 2: MCP stdio/HTTP, web_search/web_fetch e subagentes (com todas as tools, exceto a de invocar subagente).