aibrain-compress

Pure Python token compression for AI agent CLI output. Zero telemetry, zero network calls, stdlib only.

The problem

LLM agents that run shell commands on your behalf — Claude Code, Cursor, Aider, Codex, and so on — have to read the raw output of git, pytest, eslint, cargo, docker, and friends. That output is written for humans, not for a fixed context window. A single git push with progress bars, a pytest run with passing tests, or a large eslint sweep can burn thousands of tokens on noise before the actual signal is reached.

aibrain-compress filters that output. It strips progress bars, deduplicates spam, condenses diffs, keeps only failing tests, and collapses stack traces — while preserving every error, warning, and material piece of state. Pure stdlib, no network calls, no telemetry.

Token savings

Savings are density-dependent: a test run with one failure compresses far more than a test run with fifty.

Install

pip install aibrain-compress

Requires Python 3.8+. No runtime dependencies.

Usage

Wrap mode — run a command, get compressed output

aibrain-compress git status
aibrain-compress git diff HEAD~1
aibrain-compress pytest
aibrain-compress cargo test

Pipe mode — compress output from a command you already ran

git status | aibrain-compress -- git status
pytest | aibrain-compress -- pytest

The -- separator tells aibrain-compress that the arguments after it describe the command whose output is on stdin.

Hook mode — make git auto-compress in your shell

aibrain-compress init       # install shell hook (bash or PowerShell)
aibrain-compress disable    # remove the hook

Once the hook is installed, plain git status, git diff, etc. print compressed output automatically. The hook captures exit codes correctly so scripts keep working. Your ~/.bashrc or PowerShell profile is backed up before modification.

Supported commands

Git (status, diff, log, commit, push, pull, add, fetch, stash, branch, show, worktree, merge, rebase, and more), pytest, vitest, jest, cargo test, go test, cargo build, tsc, eslint, biome, prettier, next build, docker ps/images/logs, pip list/install, npm/pnpm/yarn install, Python tracebacks, env/printenv, ps, ls, cat *.json. Unknown commands fall through to a generic noise-stripping + deduplication filter.

Public Python API

from aibrain_compress import compress

raw = """On branch main
nothing to commit, working tree clean
"""
compressed = compress(['git', 'status'], raw)
print(compressed)

compress(command, output) takes the argv list of the command and the raw combined stdout+stderr string. It returns a compressed string and never raises — on any internal error it falls back to the generic filter or the raw input.

Configuration

A config file at ~/.aibrain/compress.toml can toggle filters per category:

[compress]
enabled = true    # master switch — false disables everything

[compress.git]
enabled = true

[compress.env]
enabled = false   # keep raw env output

Environment variables take precedence over the config file:

• AIBRAIN_COMPRESS_DISABLE — master disable
• AIBRAIN_COMPRESS_DISABLE_GIT, _TEST, _BUILD, _DOCKER, _PIP, _ENV, _JSON, _TRACEBACK
• AIBRAIN_COMPRESS_DIFF_CONTEXT=N — context lines in git diff (default: 0)

An interactive settings menu is available via aibrain-compress config.

What this does NOT do

• It does not run any LLM, tokenizer, or ML model — the compression is entirely rule-based.
• It does not modify the exit code or semantics of the wrapped command.
• It does not send anything over the network.
• It is not a general-purpose log compression tool; it targets developer CLI output specifically.

License

MIT. See LICENSE.

Related

aibrain-compress is extracted from the AIBrain portable cognitive substrate for AI agents. The rest of AIBrain deals with persistent memory, skill learning, and agent orchestration — this package is the part that deals with the firehose of CLI output those agents have to read.