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)

./barroso-harness -init                # cria ~/.barroso-harness/{config.json,BARROSO.md}
export BARROSO_API_KEY=sua-chave        # a chave NUNCA vai para o arquivo

Depois edite ~/.barroso-harness/config.json:

{
  "base_url": "https://seu-endpoint.example/v1",
  "model": "seu-modelo"
}

Campo opcional context_window: se o endpoint publicar a janela do modelo, informe aqui em tokens — ativa o guardrail de contexto do runtime.

Usar

barroso-harness -p "liste o que tem na pasta e diga o que pensa"

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).