$ reference

Configuration

Boost works out of the box — every setting is optional. When you want to change something, it lives in a single config.toml: per repo at .boost/config.toml, or globally for your user at ~/.boost/config.toml (same path on macOS, Linux, and Windows).

Where Boost looks for config

Boost reads the first config.toml it finds, checking these locations in order:

.boost/config.toml in the current directory — a per-invocation override.
.boost/config.toml at the enclosing git repo root, so a command run from a subdirectory still finds the project's config.
~/.boost/config.toml in your home directory — the global fallback that boost init writes.

A legacy boost.config.toml in any of those directories is still read for backward compatibility, but .boost/config.toml takes precedence.

From a monorepo subdirectory, Boost still reads <repo-root>/.boost/config.toml — not a .boost/ folder in cwd unless you put one there (checked first, so it overrides repo and global config).

Config dir vs. data dir

Config (config.toml) lives under .boost/. Boost's runtime data — the history.db SQLite database, update-check cache, and tee logs — lives in the OS data directory instead:

macOS — ~/Library/Application Support/boost/
Linux — $XDG_DATA_HOME/boost/ or ~/.local/share/boost/
Windows — %LOCALAPPDATA%\boost\

Point the database elsewhere with BOOST_DB_PATH or [tracking] database_path.

Skip hook rewrite for specific commands

When Cursor, Claude Code, Codex CLI, or GitHub Copilot runs a shell command, Boost's hook rewrites supported tools to boost <cmd> so output is compressed before it reaches the agent. To keep certain commands unwrapped, add them to [hooks] exclude_commands. Each entry is matched against the first word of the command, reduced to its binary name — so docker also matches /usr/bin/docker compose up.

.boost/config.toml

[hooks]
exclude_commands = ["playwright", "vim", "docker"]

With the example above, playwright test stays playwright test instead of becoming boost playwright test. The same list applies to boost rewrite and the Copilot hook path.

Hook rewrite only

exclude_commands prevents automatic wrapping in agent hooks. It does not disable capture or filtering when someone runs boost playwright test directly.

All settings

Every key is optional; omit a section to keep its defaults. Top-level keys (accept_terms and friends) are written by boost init when you accept the terms.

~/.boost/config.toml — global defaults

accept_terms = "yes"

[hooks]
exclude_commands = ["vim", "nano"]

[tracing]
report = false                 # silence per-command stderr savings lines
upload = false                 # skip remote OTLP upload (local spans still recorded)

[report]
usd_per_million_tokens = 5.0
co2e_kg_per_million_tokens = 0.21

[filters]
disabled = []                  # filter names skipped by the engine; retrieve auto-appends
retrieve_disable_threshold = 3 # retrieves per capability_id before auto-disable; 0 = never

[mcp]
toon_format = false            # opt in to MCP JSON→TOON (also needs Unleash boost-mcp-toon-format)

[update]
auto_update = false            # only read from ~/.boost/config.toml

A project's .boost/config.toml only needs to set what differs from the global defaults above — everything else keeps inheriting from ~/.boost/config.toml or its built-in default:

.boost/config.toml — project override

[tracking]
database_path = "/data/ci/history.db"   # this repo's CI containers only

[report]
co2e_kg_per_million_tokens = 0.09       # this team's low-carbon region

Here, accept_terms, [hooks], and [tracing] report are left unset, so this repo still uses whatever the global ~/.boost/config.toml — or the built-in default — says for those keys.

Key	Purpose	Default
accept_terms	Records that you accepted Boost's terms; set by `boost init`.	unset
[hooks] exclude_commands	Command names skipped by hook rewrite (matched on the first word's binary name).	[ ]
[tracing] report	Set `false` to hide the per-command stderr savings line. `BOOST_REPORT` overrides this.	true
[tracing] upload	Set `false` to skip remote OTLP upload from `boost sync` (bundled endpoint and external mirror). Spans still persist locally; `--file` JSONL still writes.	true
[tracking] database_path	Override the SQLite history DB location. `BOOST_DB_PATH` wins over this.	OS data dir / history.db
[report] usd_per_million_tokens	US dollars per 1M saved tokens for `boost report` dollar figures (non-negative).	5.0
[report] co2e_kg_per_million_tokens	kg CO2e avoided per 1M saved tokens for emissions estimates (non-negative).	0.21
[filters] disabled	TOML filter names skipped by the engine (builtins and user filters). `boost retrieve` auto-appends rolled-back filter names after the retrieve threshold.	[]
[filters] retrieve_disable_threshold	How many retrieve events for the same `capability_id` trigger auto-disable. Set `0` to never auto-disable. Read from global config.	3
[mcp] toon_format	Opt in to JSON→TOON for MCP tool responses on PostToolUse (Cursor/Claude). Also requires Unleash `boost-mcp-toon-format`. Toggleable in `boost report -w` Settings.	false
[update] auto_update	Set `false` to opt out of background self-updates. Read from global config only.	true

Environment overrides

Environment variables take precedence over config.toml, which makes them handy for one-off runs.

Variable	Effect
BOOST_DB_PATH	Path to the SQLite history DB; overrides `[tracking] database_path`.
BOOST_REPORT	`0` silences the per-command stderr savings line.
BOOST_REPORT_USD_PER_MTOK	Override `[report] usd_per_million_tokens`.
BOOST_REPORT_CO2E_KG_PER_MTOK	Override `[report] co2e_kg_per_million_tokens`.
BOOST_TEE_DIR	Directory for raw output tee logs written on failure.
XDG_DATA_HOME / LOCALAPPDATA	Relocate the data dir (history.db, caches, tee logs) on Linux / Windows.

Summary

Goal	Mechanism
Edit settings for a project	.boost/config.toml
Edit settings for every project	~/.boost/config.toml
Agent should not wrap `playwright`, `vim`, etc.	[hooks] exclude_commands
Move the history database	BOOST_DB_PATH or [tracking] database_path
Hide per-command savings on stderr	[tracing] report = false or BOOST_REPORT=0
Disable remote telemetry upload	[tracing] upload = false
Opt out of background self-updates	[update] auto_update = false in ~/.boost/config.toml
Enable MCP JSON→TOON (off by default)	Unleash boost-mcp-toon-format + [mcp] toon_format = true

TOML Filters

Add custom output compression rules for tools without a built-in filter.

Token Savings

See how much output Boost compresses before it reaches the agent.

$ BOOST_REPORT_USD_PER_MTOK=9 boost report -w       # one run; config.toml unchanged
$ BOOST_DB_PATH=/tmp/ci.db boost go test ./...
$ BOOST_REPORT=0 boost npm test

New version of Boost released— Smarter savings and cleaner output