banish.shdocs
/
HomeGitHub
Concepts / The audit footer
View as Markdown

The audit footer

Compaction in banish is auditable and reversible. When a filter drops lines from a large output, the compact result ends with a footer that accounts for every one of them, names the filter responsible, and gives you a one-command way to get the original back. Available since v0.6.0.

--- banish: dropped 222 lines ---
  groups:
    - filter: grep.per-group  lines: 119
    - filter: grep.max-lines  lines: 103
  recover: banish raw a1b2c3d4 (costs ~7009 tokens, only if needed)

Each group is one filter stage and the exact number of lines it removed. The labels tell you what kind of content was dropped before you decide whether you need it:

LabelWhat was dropped
<filter>.dropLines matched by a !drop or !keep rule - warnings, passing tests, progress noise.
<filter>.pipeLines removed by the filter's !compact shell pipe.
<filter>.per-groupRepeats past the per-group cap, already marked inline with +N more.
<filter>.max-linesOverflow past the total line cap, also marked inline.

An agent reading the footer knows exactly how much was removed, by what, and what recovering it would cost - so it can trust the compact view by default and reach for the raw output only when a needed detail is missing.

Recover the raw output

banish raw a1b2c3d4

This prints the original stdout and stderr byte for byte, straight from a local cache - no re-running the command, no re-paying for its execution. The token estimate on the recover line is the price of reading it all back; treat it as a last resort, not a habit. MCP agents get the same pathway as a banish_raw tool.

The raw cache

Raw outputs live in ~/.banish/cache/raw/, private to your user (files 0600, directory 0700) and never inside a repository. Entries expire after 1 hour and the cache is capped at 50 MB, evicting oldest first. Both limits are configurable in ~/.banish/config.json:

{"cache": {"ttl_minutes": 60, "max_mb": 50}}

Command output can contain whatever the command printed, including secrets. If you would rather keep nothing on disk, disable the cache entirely:

{"cache": {"raw": false}}

Or empty it at any point:

banish raw --clear

Trace mode

Writing or tuning a filter? Set BANISH_TRACE=1 and every silently dropped run is annotated in place instead of removed:

[banish: dropped 20 lines via go-test.drop]

The output shows exactly where each filter stage cut content, which makes a new .bsh filter easy to verify before you rely on it.

Only when it pays for itself. Small outputs - under 40 raw lines, under 2.5 KB, or with trivial savings - are passed through or kept whole, with no footer and nothing to recover. A typical footer costs about 37 tokens and points at hundreds or thousands of recoverable ones.

The footer rides inside the output your agent already reads, so it is counted in the savings numbers - the methodology measures what the agent actually sees, footer included.

Next: see how the footer reaches your agent through the bash proxy, or write your own filter in the .bsh language.

Audit footer and raw recovery - compaction with nothing lost - banish