New releasev0.17.5Nov 18, 2026

New version of Boost released— Clearer usage forecasts

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:

  1. .boost/config.toml in the current directory — a per-invocation override.
  2. .boost/config.toml at the enclosing git repo root, so a command run from a subdirectory still finds the project's config.
  3. ~/.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/
  • 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.

KeyPurposeDefault
accept_termsRecords that you accepted Boost's terms; set by boost init.unset
[hooks] exclude_commandsCommand names skipped by hook rewrite (matched on the first word's binary name).[ ]
[tracing] reportSet false to hide the per-command stderr savings line.true
[tracing] telemetrySet 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] uploadSet 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_pathOverride the SQLite history DB location. BOOST_DB_PATH wins over this.OS data dir / history.db
[report] usd_per_million_tokensUS dollars per 1M saved tokens for boost report dollar figures (non-negative).5.0
[report] co2e_kg_per_million_tokenskg CO2e avoided per 1M saved tokens for emissions estimates (non-negative).0.21
[filters] disabledTOML 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_thresholdHow many retrieve events for the same capability_id trigger auto-disable. Set 0 to never auto-disable. Read from global config.3
[mcp] toon_formatOpt 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_updateSet 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.

VariableEffect
BOOST_DB_PATHPath to the SQLite history DB; overrides [tracking] database_path.
BOOST_REPORT_USD_PER_MTOKOverride [report] usd_per_million_tokens.
BOOST_REPORT_CO2E_KG_PER_MTOKOverride [report] co2e_kg_per_million_tokens.
BOOST_TEE_DIRDirectory for raw output tee logs written on failure.
XDG_DATA_HOME / LOCALAPPDATARelocate the data dir (history.db, caches, tee logs). WSL uses XDG_DATA_HOME, like Linux. LOCALAPPDATA is native Windows.

Summary

GoalMechanism
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 databaseBOOST_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 ./...