$ reference
Configuration
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.tomlin the current directory — a per-invocation override..boost/config.tomlat the enclosing git repo root, so a command run from a subdirectory still finds the project's config.~/.boost/config.tomlin your home directory — the global fallback thatboost initwrites.
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, or Gemini CLI 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 Gemini and Copilot hook paths.
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
[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
[update]
auto_update = false # only read from ~/.boost/config.tomlA 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 regionHere, 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 |
| [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 |
| [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 |
| Opt out of background self-updates | [update] auto_update = false in ~/.boost/config.toml |
Related
$ 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