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/
- WSL — same as Linux, ~/.local/share/boost/ inside the distro
- 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, GitHub Copilot, or OpenCode runs a shell command, Boost rewrites supported tools to boost <cmd> (shell hooks or the OpenCode plugin) 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
telemetry = false # no OTEL spans, no remote export, no Unleash network
upload = false # skip remote OTLP upload (ignored when telemetry = false)
[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. | true |
| [tracing] telemetry | Set false to disable all OpenTelemetry span collection, remote export (including OTEL_* env vars), and Unleash network. boost init --no-telemetry writes this. Local history.db is unchanged. | true |
| [tracing] upload | Set false to skip remote OTLP upload from boost sync (bundled endpoint and external mirror). Spans still persist locally unless telemetry = false; --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 |
Disable telemetry completely
boost init --no-telemetry writes [tracing] telemetry = false into every config Boost loads, including ~/.boost/config.toml. [tracing] upload = false only stops boost sync from uploading spans to JFrog (and any external_endpoint mirror). Spans can still be recorded locally and Unleash may still be contacted for feature flags. To turn off all product telemetry — no OpenTelemetry span collection, no remote export (including OTEL_* overrides), and no Unleash network — set [tracing] telemetry = false in your global ~/.boost/config.toml (project .boost/config.toml overrides when Boost loads that file first).
~/.boost/config.toml
[tracing]
telemetry = false
Put the same [tracing] telemetry = false block in a project .boost/config.toml if you only want it for one repo. Local command history in history.db is unchanged; Boost still filters output on your machine. Per-command stderr savings lines are separate — set [tracing] report = false in the same file.
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_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). WSL uses XDG_DATA_HOME, like Linux. LOCALAPPDATA is native 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 in config.toml |
| Disable remote telemetry upload only | [tracing] upload = false |
| Disable all telemetry (no spans, no upload, no Unleash) | boost init --no-telemetry, or [tracing] telemetry = false in ~/.boost/config.toml |
| 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 |
Related
$ BOOST_REPORT_USD_PER_MTOK=9 boost report -w # one run; config.toml unchanged
$ BOOST_DB_PATH=/tmp/ci.db boost go test ./...