Keep tool output out of your agent's context

1. Wrap a command

Prefix any command with h5i capture run --. It runs the command, prints a filtered structured summary, and passes the exit code straight through:

$ h5i capture run -- pytest -q
pytest test failed · 1 failed, 120 passed (exit 1)
  F tests/test_auth.py::test_refresh  assert 0 == 100

Output below --min-bytes (default 2 KB) passes straight through unstored, so wrapping a quick command is a harmless no-op. Use --min-bytes 0 to always capture. The full raw output is stored content-addressed in .git/.h5i/objects/; a tiny pointer + the summary go to the refs/h5i/objects git ref.

2. Choose the format

The default is compact (one line per finding). Switch when you want more or less:

3. Recover and query

Every capture is stored, queryable by status / tool / branch / file, and rehydratable byte-for-byte:

$ h5i recall objects                     # list captures (newest first)
$ h5i recall objects --status failed     # only failures
$ h5i recall objects --tool pytest       # by tool (compose with --branch/--file)
$ h5i recall object 0bb827e4 --summary   # the reduced summary
$ h5i recall object 0bb827e4             # the full raw bytes, exactly

Tag a capture with the files it concerns using --file (repeatable); the branch and working-tree diff are recorded automatically, so an agent resuming a branch can pull up exactly the test/build output tied to it.

4. Share raw blobs with the team (optional)

h5i push carries the manifests (summaries + pointers) but not the huge raw bytes — so nothing large is shared implicitly. To share the bytes, run h5i objects push; the backend is chosen by --backend auto|lfs|git-ref (default auto):

$ h5i objects push              # upload local raw blobs (Git LFS by default on HTTP(S) remotes)
$ h5i objects pull              # fetch shared blobs you don't have locally
$ h5i objects push --backend git-ref   # force the refs/h5i/objects-data git ref instead

The LFS path is native (h5i speaks the LFS Batch API directly — no git lfs CLI, no pointer files), so huge output lives on your git host's LFS server and never bloats the git object database. With LFS, h5i recall object <id> lazily fetches a blob on demand. The git-ref store is the fallback for SSH/file:// remotes. Both verify the content address on every read.

5. Reclaim space (raw is local until shared)

Manifests are kept forever (they're tiny and travel with h5i push); only the local raw blobs expire, and only when you ask:

$ h5i objects gc                # remove orphan blobs (no manifest references them)
$ h5i objects gc --ttl 30d      # also evict referenced blobs older than 30 days
$ h5i objects pin 0bb827e4      # protect a blob from gc
$ h5i objects fsck              # verify manifests against the local store

GC never rewrites a summary — an evicted blob's summary still works; it just reads as absent.

6. Make agents use it automatically

Run h5i objects setup once to wire token-reduction guidance into the project's .claude/h5i.md and AGENTS.md (a fresh h5i init already includes it). In Claude Code, the h5i_capture_run MCP tool exposes the same behavior with no shell-quoting — the agent calls it instead of the Bash tool and gets the structured result back directly.

$ h5i objects setup
✔ wired token-reduction guidance into .claude/h5i.md, AGENTS.md

Custom rules (optional)

h5i ships dedicated parsers for pytest, cargo, go test, tsc, eslint, ruff, and mypy, plus dozens of declarative filter rules. A repo can add its own in .h5i/filters.toml — but because that file could mask failures, it's applied only after you trust its current content:

$ h5i objects filters          # list built-in command filters
$ h5i objects trust            # review + trust a project-local .h5i/filters.toml