Features

This page collects the capabilities that are not tied to one command. For the commands themselves, see CLI commands.

Output compaction

Every command banish runs is matched against its filters. The first matching filter pipes the command's raw stdout through a shell one-liner that strips the predictable noise, and banish returns only the compact result. If no filter matches, or a filter errors, you get the raw output unchanged - compaction never costs you correctness. See the bash proxy for the full flow and built-in filters for what ships.

Token-savings tracking

banish estimates tokens on both the raw and compact output of every command and records the difference. The running totals persist across sessions and are shown by banish gain: total commands, input and output tokens, tokens saved with a percentage, an estimated cost saved, and a per-command breakdown. banish gain --price adjusts the cost estimate to your model's input rate.

The freq.json data file

Tracking data lives in ~/.banish/freq.json. Each command banish runs appends an entry with its token counts and rewrite count; banish gain reads this file to build its report. Clear it with banish gain reset (or banish gain --reset), which rewrites the file to an empty set.

Permission-aware hook auto-approval

When wired into an agent with banish init, the PreToolUse hook routes Bash commands through banish for compaction. It never auto-approves a command the host's own permission rules do not already allow:

• Commands the host already allows are auto-approved and wrapped to run through banish.
• Commands that would normally prompt you still prompt you.
• State-changing or unattestable commands, banish's own calls, stateful shell builtins (cd, export, source, alias, eval), multi-line scripts, and heredocs are deferred to the host untouched.

Every auto-approval is logged to ~/.banish/hook-audit.jsonl so you can review exactly what ran without a prompt. Inspect it with banish audit.

MCP tool exposure

banish serve runs banish as a Model Context Protocol server over stdio and exposes every extension verb as a typed tool, with the verb's !help line as the tool description and its !args as parameters. The proxy and the server share the same filters, so output is compact whether the agent shells out or calls a tool. See MCP server and the guide on reducing MCP token usage.

.bsh extensions and verbs

A .bsh file declares verbs, filters, and config in plain directives. Drop one in ~/.banish/ext and it is live at the next run with no recompile. A verb is a named command shortcut that can take arguments and expand into a real command; a filter matches a command and compacts its output. See the .bsh language for the syntax and built-in filters for the directive reference.

Definitions load in precedence order, first match wins: your extensions in ~/.banish/ext, then the project BANISH file, then the embedded defaults. This lets a user or project definition override a built-in.

BANISH file support

A project can ship a BANISH file in its root for repo-specific verbs, filters, and rewrites. banish walks up from the working directory to find it and loads it after your personal extensions but before the embedded defaults. Scaffold a starter file with banish init (no argument).