# Features


# Features

This page collects the capabilities that are not tied to one command. For the
commands themselves, see [CLI commands](/docs/reference/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](/docs/concepts/bash-proxy) for the
full flow and [built-in filters](/docs/reference/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`](/docs/reference/cli-commands): 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`](/docs/reference/cli-commands).

## 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](/docs/concepts/mcp-server) and the guide on
[reducing MCP token usage](/docs/guides/reduce-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](/docs/concepts/bsh-language) for the syntax and
[built-in filters](/docs/reference/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).