TOML Filters

Where filters load

Boost merges filters from several locations and applies every filter selected by the command or output. Files within a folder load in sorted (deterministic) order.

1. Built-in filters shipped with Boost (make, terraform, shellcheck, …)
2. ~/.boost/filters/*.toml (global folder, one filter per file)
3. .boost/filters/*.toml in the project (folder, one filter per file) — discovered from the current directory, then the enclosing git repo root, then $GITHUB_WORKSPACE

Project discovery loads only .boost/filters/*.toml — it does not read, create, or require a repo-level .boost/config.toml. Filters committed at the repo root apply from subdirectories. If the same name appears in more than one project dir, cwd wins. Enable/disable still uses ~/.boost/config.toml.

Sources are merged, not overridden. A project filter does not replace a built-in with the same name — both load (keyed by name + source), and every filter whose match_command or match_output_select hits is applied in load order (builtin → global → project). To replace a built-in, boost filters disable its name and ship your own.

Create a project filter

Ship team filters in .boost/filters/ at the repo root. Anyone who clones the repo — and runs Boost from a subdirectory or CI — gets the same compression automatically.

1. mkdir -p .boost/filters
2. Add one .toml file per filter. The name comes from [filters.<name>]. Use match_command plus a distinctive match_output_select so the filter selects on the agent pipe path.
3. Commit the file with the repo.
4. From a subdirectory, run boost filters show — the filter should appear with SOURCE=project.

schema_version = 1

[filters.acme-cli]
description = "Keep errors and warnings from the internal acme-cli"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:\S*/)?acme-cli\b'
match_output_select = [
  '(?m)^acme-cli v',
]
strip_ansi = true
keep_lines_matching = [
  '^acme-cli v',
  '^Error:',
  '^Warning:',
  '^✗',
]
on_empty = "acme-cli: ok"

Confirm it loaded

# From any subdirectory of the repo:
boost filters show | grep acme-cli
# → enabled   project     acme-cli   toml:project:acme-cli

After boost init, agent shell commands are piped through Boost automatically. No repo-level .boost/config.toml is required for project filters; enable/disable still uses ~/.boost/config.toml. For a fuller end-to-end example with before/after output, see the deploy script section below.

Folder layout (one filter per file)

Custom filters live in a folder of one-filter files: each file holds a single [filters.<name>] block plus its [[tests.<name>]] examples. This keeps filters independently editable — an agent (or you) can tune one filter without touching the others.

~/.boost/filters/                 # global (this machine)
  my-personal.toml

<repo>/.boost/filters/            # project (commit with the team)
  acme-cli.toml
  deploy.toml

Global and project folder filters are picked up by the next boost process with no rebuild (unlike built-in filters, which are embedded at compile time).

Selectors & common fields

Every filter needs at least one selector. The fields below show up in almost every example; the full glossary is at the bottom of this page.

Regex flavor

All patterns use Go's regexp package (RE2 syntax) — not PCRE. No backreferences or lookbehind. Multiline ^/$ need the (?m) flag when matching against the full output. See regexp/syntax.

Example: custom deploy script

Your team runs ./scripts/deploy.sh after installing the Boost hook. The hook sends only output to Boost, so match_output_select is needed in addition to match_command. Use a distinctive output signature to avoid filtering unrelated commands.

schema_version = 1

[filters.deploy]
description = "Keep failures from deploy.sh"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:bash\s+)?(?:\S*/)?deploy\.sh\b'
# The hook pipes output to boost, so select by a distinctive output signature.
# (?m) makes ^ and $ match each line, not only the full output boundaries.
match_output_select = [
  '(?m)^Starting deployment$\n^Environment: ',
]
strip_ansi = true
keep_lines_matching = [
  '^Starting deployment$',
  '^Environment: ',
  '^\[(WARN|ERROR)\]',
  '^ERROR DETAILS:$',
  'failed readiness probe',
  '^File:$',
  '^deploy/check_health\.go:\d+$',
  '^Reason:$',
  '^connection refused',
  '^Rollback started\.\.\.$',
  '^Deployment FAILED$',
]

[[tests.deploy]]
name = "keeps failures, drops info chatter"
input = """
Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""
expected = """
Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""

Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Inline tests

Each [[tests.<name>]] block is a regression fixture: name, input (raw output), and expected (filtered output). Optional expect_match_output asserts whether match_output_select would select the filter for that input.

How to run them

There is no boost filters test subcommand yet. Spot-check custom filters by piping sample output through boost. Built-in fixtures ship in the Boost repo and run under go test:

# Spot-check a custom filter: pipe sample output through boost
printf '%s\n' 'Starting deployment' 'Environment: staging' '[INFO] noise' | boost

# Built-in [[tests.*]] fixtures run in the Boost repo / CI:
go test ./internal/tomlfilter/ -run TestInlineTestDefs

Example: strip make chatter

Built-in filters use the same schema. This mirrors the shipped make filter: drop entering/leaving directory lines and blank rows.

schema_version = 1

[filters.make]
match_command = "^make\\b"
match_output_select = [
  "^make\\[\\d+\\]:",
  "^gcc ",
]
strip_lines_matching = [
  "^make\\[\\d+\\]:",
  "^\\s*$",
  "^Nothing to be done",
]
on_empty = "make: ok"

make[1]: Entering directory '/home/user/app'
gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

make[1]: Leaving directory '/home/user/app'

gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

Example: short-circuit on clean lint

Use match_output to return a one-line summary when the tool succeeded quietly.

schema_version = 1

[filters.eslint-quiet]
match_command = "^eslint\\b"
match_output_select = [
  "problems",
]
match_output = [
  { pattern = "0 problems", message = "eslint: ok" },
]

Disabling a filter

Prefer the CLI:

boost filters show                 # inventory with enabled/disabled status
boost filters show --enabled       # enabled filters only
boost filters disable git-status   # bare name or toml:builtin:git-status
boost filters enable git-status

Or edit ~/.boost/config.toml directly — list filter names under [filters] disabled. Those names are skipped at load time (builtins and user/project filters alike). After retrieve_disable_threshold retrieve events for the same capability (default 3), boost retrieve auto-appends the rolled-back filter name(s). Set the threshold to 0 to turn auto-disable off. Use boost filters enable (or clear the list) to re-enable.

[filters]
disabled = ["git-status", "make"]
retrieve_disable_threshold = 3

Filter fields

Put schema_version = 1 at the top of each filter file (recommended). A filter needs at least one selector: match_command for command-aware capture or match_output_select for piped hook output. Define both when the filter must work in both paths. Stages run in order: strip ANSI → replace → match_output short-circuit → strip/keep lines → dedupe → collapse → head/tail → on_empty. Avoid success-like on_empty messages unless empty filtered output proves success. Commands without a matching filter pass through unchanged. See the full reference in docs/TOML_FILTERS.md on GitHub.