Metadata-Version: 2.4
Name: aibrain-compress
Version: 2.1.0
Summary: Pure Python token compression for AI agent CLI output. Zero telemetry, zero network calls, stdlib only.
Author-email: DeckerOps <decker.ops@gmail.com>
License: MIT
Project-URL: Homepage, https://myaibrain.org
Project-URL: Repository, https://github.com/sindecker/aibrain-compress
Project-URL: Issues, https://github.com/sindecker/aibrain-compress/issues
Keywords: llm,ai,agent,cli,compression,tokens,claude,gpt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

| Category                            | Commands                                  | Typical savings |
|-------------------------------------|-------------------------------------------|-----------------|
| Tests                               | pytest, vitest, jest, cargo test          | 90-99%          |
| ESLint (large runs)                 | eslint                                    | 60-80%          |
| TypeScript                          | tsc                                       | 40-55%          |
| Cargo build, prettier, next build   | cargo build, prettier, next build         | 70-87%          |
| Git push (with progress bars)       | git push                                  | 80-87%          |
| Git push (clean)                    | git push                                  | ~63%            |
| Git add / pull / fetch / stash      | summary-only filter                       | 80%+            |
| Git status                          | hint stripping                            | 50-60%          |
| Git diff                            | context reduction (configurable)          | 40-80%          |

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

## Install

```bash
pip install aibrain-compress
```

Requires Python 3.8+. No runtime dependencies.

## Usage

### Wrap mode — run a command, get compressed output

```bash
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

```bash
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

```bash
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

```python
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:

```toml
[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](LICENSE).

## Related

`aibrain-compress` is extracted from the [AIBrain](https://myaibrain.org) 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.
