# Built-in filters


# Built-in filters

banish ships with filters for the commands agents run all day. They are plain
`.bsh` files embedded into the binary at build time, one per ecosystem.

## What ships

| Ecosystem | Commands compacted |
| --- | --- |
| git | status, diff, log, branch |
| docker | ps, build, images, compose |
| kubectl | get, describe, logs |
| node | npm, yarn, pnpm install and run |
| rust | cargo build, test, check |
| go | go build, test, vet |
| java | maven and gradle builds |
| python | pytest, pip |
| cloud | aws, terraform |

Each filter targets the noisy, predictable output these tools print and returns
just the part the model needs. For worked examples with before-and-after token
counts, see the per-command guides: [git](/docs/guides/compact-git-output),
[cargo](/docs/guides/compact-cargo-output), [npm](/docs/guides/compact-npm-output),
[kubectl](/docs/guides/compact-kubectl-output), and
[go test](/docs/guides/compact-go-test-output).

## Directive reference

A `.bsh` file is a list of directives. These are the ones you will use most:

| Directive | Purpose |
| --- | --- |
| `!extension` | Names and versions an extension file. |
| `!verb` | Declares a command shortcut. |
| `!args` | Names the parameters a verb accepts. |
| `!expand` | The command a verb expands into. |
| `!help` | Description shown to the agent. |
| `!filter` | Declares an output filter. |
| `!match` | Substring that selects which commands the filter handles. |
| `!compact` | Shell one-liner that strips the noise from stdout. |
| `!config` | Opens a block of runtime options. |
| `!timeout` | Maximum time a command may run. |
| `!output` | Output format, for example `json`. |

## Add your own

Create a file in `~/.banish/ext`:

```bsh
!extension mytools v:1.0

!filter docker-build
!match docker build
!compact "grep -v '^Sending build' | grep -v '^---> ' | tail -20"
```

Save it and the filter is live. A new filter is about ten lines, which is why it
is the most common first contribution. If a filter fails, banish falls back to raw
output, so a work-in-progress filter never breaks anyone.