New releasev0.17.5Nov 18, 2026

New version of Boost released— Clearer usage forecasts

TOML Filters

Boost compresses command output with Go parsers for major tools and declarative TOML filters for everything else. Drop one-filter files under ~/.boost/filters/ or .boost/filters/ to teach Boost how to trim a custom script, linter, or internal CLI — no recompile required.

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.

.boost/filters/acme-cli.toml

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.

FieldPurpose
match_commandSelect by command line (capture path)
match_output_selectSelect by piped output signature (hook path); use (?m) for line anchors
strip_ansiRemove terminal color codes first
strip_lines_matchingDrop lines matching any pattern
keep_lines_matchingKeep only matching lines
on_emptyMessage when filtering removes everything

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.

.boost/filters/deploy.toml

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
"""
$ ./scripts/deploy.sh staging
−64%
Before
36 lines
Starting deployment
Environment: staging
[INFO] Loading kubeconfig from ~/.kube/config
[INFO] Using cluster gke_acme-prod_us-central1_staging
[INFO] Authenticating to Artifact Registry
[INFO] Pulling us-docker.pkg.dev/acme/payments:7.4.2
7.4.2: Pulling from acme/payments
a1b2c3d4e5f6: Already exists
b2c3d4e5f6a7: Pull complete
c3d4e5f6a7b8: Pull complete
Digest: sha256:9f8e7d6c5b4a3210fedcba9876543210
Status: Downloaded newer image for us-docker.pkg.dev/acme/payments:7.4.2
[INFO] Applying Helm chart payment-service-7.4.2
service/payment-service configured
deployment.apps/payment-service configured
configmap/payment-service-env configured
[INFO] Waiting for rollout
Waiting for deployment "payment-service" rollout to finish: 0 of 3 updated replicas are available...
Waiting for deployment "payment-service" rollout to finish: 1 of 3 updated replicas are available...
Waiting for deployment "payment-service" rollout to finish: 2 of 3 updated replicas are available...
[INFO] GET http://payment-service/healthz → 000
[INFO] retry 1/5
[INFO] GET http://payment-service/healthz → 000
[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
[INFO] Streaming logs from payment-service-7f8d9c-abc12
Rollback started...
[INFO] Helm rollback to revision 183
Deployment FAILED
Environment: staging
After
13 lines
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

Image pulls, Helm apply, and rollout waits are dropped. The agent still sees the warning, the readiness failure, and the rollback.

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
−60%
Before
5 lines
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'
After
2 lines
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

FieldTypePurpose
schema_versionintFile-level schema marker (recommended 1; reserved for future validation)
descriptionstringHuman-readable note (not used at filter runtime)
versionstringCapability version for retrieve / telemetry (e.g. "1")
match_commandstringCommand-path selector: regex against the full command line
match_output_selectstring[]Pipe-path selector: regexes against the complete piped output; use (?m) for line anchors
strip_ansiboolRemove terminal color codes first (before other stages)
replacearrayLine-level regex replacements: { pattern, replacement }
match_outputarrayIf output matches pattern, return message instead (optional unless)
strip_lines_matchingstring[]Drop lines matching any pattern
keep_lines_matchingstring[]Keep only matching lines
dedupe_lines_matchingstring[]Keep the first exact copy of each matching line; drop later identical copies
collapse_lines_matchingarrayReplace matching lines with one summary: { pattern, template } — {count} = number of matches
head_lines / tail_linesintKeep first or last N lines
on_emptystringMessage when filtering removes everything

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.