$ reference

TOML フィルター

Boost は主要ツール向け Go パーサーと、それ以外向けの 宣言的 TOML フィルター で圧縮します。~/.boost/filters/ または .boost/filters/ に 1 フィルター 1 ファイルを置けば、再コンパイル不要です。

フィルターの読み込み元

Boost は複数の場所からフィルターをマージし、コマンドまたは出力で選択されたすべてのフィルターを適用します。フォルダ内のファイルは決定的な順序で読み込まれます。

Boost に同梱の組み込みフィルター（make、terraform、shellcheck など）
~/.boost/filters/*.toml（グローバルフォルダ、1 ファイル 1 フィルター）
.boost/filters/*.toml（プロジェクト）— cwd → git ルート → $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.

ソースは上書きではなくマージされます。同名のプロジェクトフィルターは組み込みを置き換えません — 両方読み込まれ（name + source）、match_command または match_output_select にヒットしたすべてが読み込み順（builtin → global → project）で適用されます。置き換えるには boost filters disable して独自フィルターを置きます。

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.

mkdir -p .boost/filters
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.
Commit the file with the repo.
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.

フォルダレイアウト（1 ファイル 1 フィルター）

カスタムフィルターは 1 フィルター 1 ファイルです。各ファイルに [filters.<name>] ブロックと [[tests.<name>]] 例があります。

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

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

~/.boost/filters/ のフィルターは次の boost プロセスで リビルドなし で読み込まれます。

セレクターとよく使うフィールド

フィルターには少なくとも 1 つのセレクターが必要です。以下はほぼすべての例に出るフィールドです。完全な一覧はページ末尾にあります。

フィールド	目的
match_command	Select by command line (capture path)
match_output_select	Select by piped output signature (hook path); use `(?m)` for line anchors
strip_ansi	Remove terminal color codes first
strip_lines_matching	Drop lines matching any pattern
keep_lines_matching	Keep only matching lines
on_empty	Message when filtering removes everything

正規表現の種類

パターンはすべて Go の regexp（RE2 構文）で、PCRE ではありません。後方参照や lookbehind はありません。出力全体に対する複数行の ^/$ には (?m) が必要です。regexp/syntax を参照。

例: カスタム deploy スクリプト

チームが ./scripts/deploy.sh を Boost 経由で実行します。フックは出力だけを送るため、match_command に加えて match_output_select が必要です。

.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
"""

Before (raw)

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

After Boost filter

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 # the installed Boost hook pipes output automatically

インラインテスト

各 [[tests.<name>]] ブロックは回帰フィクスチャです: name、input、expected。任意の expect_match_output で match_output_select の選択を検証できます。

実行方法

まだ boost filters test はありません。カスタムフィルターはサンプル出力を boost にパイプして確認します。組み込みフィクスチャは 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

例: `make` の冗長出力を削除

組み込みフィルターも同じスキーマです。同梱の make フィルターを反映: ディレクトリ入退場行と空行を削除。

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"

Before

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

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

例: クリーンな lint で短絡

match_output で、ツールが静かに成功したとき 1 行サマリーを返します。

schema_version = 1

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

フィルターを無効化

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

または ~/.boost/config.toml を直接編集し、[filters] disabled に名前を列挙します。retrieve_disable_threshold 回の retrieve（デフォルト 3）後、boost retrieve がロールバック名を自動追加します。0 で自動無効化をオフにできます。

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

フィルターフィールド

フィールド	型	目的
schema_version	int	File-level schema marker (recommended `1`; reserved for future validation)
description	string	Human-readable note (not used at filter runtime)
version	string	Capability version for retrieve / telemetry (e.g. `"1"`)
match_command	string	Command-path selector: regex against the full command line
match_output_select	string[]	Pipe-path selector: regexes against the complete piped output; use `(?m)` for line anchors
strip_ansi	bool	Remove terminal color codes first (before other stages)
replace	array	Line-level regex replacements: `{ pattern, replacement }`
match_output	array	If output matches `pattern`, return `message` instead (optional `unless`)
strip_lines_matching	string[]	Drop lines matching any pattern
keep_lines_matching	string[]	Keep only matching lines
dedupe_lines_matching	string[]	Keep the first exact copy of each matching line; drop later identical copies
collapse_lines_matching	array	Replace matching lines with one summary: `{ pattern, template }` — `{count}` = number of matches
head_lines / tail_lines	int	Keep first or last N lines
on_empty	string	Message when filtering removes everything

各ファイル先頭に schema_version = 1 を推奨。ステージ順: strip ANSI → replace → match_output → strip/keep → dedupe → collapse → head/tail → on_empty。完全なリファレンスは docs/TOML_FILTERS.md。

トークン節約

Boost が圧縮を測定する方法とコンテキストに残るもの。

設定

config.toml の設定、デフォルト、環境変数。