Configuration

tok0 is intended to be invisible after tok0 init. You should never need to edit a config file. When you do, this is the canonical reference.

Config file location

~/.config/tok0/config.toml

On Windows: %APPDATA%\tok0\config.toml. On macOS: same as Linux (XDG-style, not ~/Library/Application Support).

The file is created on first run if it doesn’t exist. Every field is optional.

Full schema with defaults

[general]
# Where the SQLite token meter lives.
database_path = "~/.config/tok0/meter.db"
# Where snapshots get written when a filter falls back.
snapshot_dir  = "~/.cache/tok0/snapshots"
# Hard ceiling for any single command's output, post-pipeline.
max_chars     = 8000

[runtime]
# Time budget for any single wrapped command before tok0 kills it.
command_timeout_secs = 60
# If a filter errors, write the raw stdout to snapshot_dir for debugging.
snapshot_on_failure  = true

[bridge]
# Skip prompting on first run; useful in CI where stdin isn't interactive.
non_interactive = false
# Pin which AI tools tok0 should detect. Empty = all.
tools = []  # ["claude-code", "cursor", "gemini-cli", ...]

[telemetry]
# Off by default. Even when on, this is anonymous instance metrics —
# no command output, no paths, no identifiers.
enabled = false
endpoint = "https://api.tok0.dev/telemetry"

[updater]
# Check GitHub Releases for new versions.
auto_check = true
# Channel: "stable" | "beta"
channel    = "stable"

[cloud]
# Only used when the binary is built with --features cloud.
api_url = "https://api.tok0.dev"

Environment variables

Env vars override the config file when set.

Variable	Effect
TOK0_CONFIG	Path to an alternate config file.
TOK0_DB_PATH	Override general.database_path.
TOK0_DISABLE	If set to 1, tok0 passes through every command unchanged. The bypass switch.
TOK0_QUIET	Suppress non-error stderr output.
TOK0_LOG	error (default), warn, info, debug, trace.
TOK0_TIMEOUT_SECS	Override runtime.command_timeout_secs.
TOK0_NO_TELEMETRY	If set, telemetry is forcibly off regardless of config.
NO_COLOR	Standard. Disables tok0’s own ANSI output.

Filter search paths

Custom rules are loaded from three locations in priority order:

1. .tok0/filters/*.toml — project-local, requires tok0 trust ..
2. ~/.config/tok0/filters/*.toml — user-global, no trust prompt.
3. Built-in (embedded in the binary).

See Writing TOML rules for the schema.

Trust gating

Project-local rules can ship arbitrary regexes that get applied to your shell output. tok0 treats them as untrusted by default:

cd ~/projects/my-repo
tok0 trust .                   # opt this project in
tok0 untrust .                 # revert
tok0 trust list                # show all trusted projects

Trust is stored in ~/.config/tok0/trust.toml keyed by absolute path. Moving or renaming the project invalidates the trust entry. This is intentional — same model as VS Code workspace trust.

Bridge state

Hooks are written into each AI tool’s own config dir, not into tok0’s. Where they go:

Tool	Hook surface
Claude Code	~/.claude/settings.json (PreToolUse hook)
Cursor	Settings → Rules (manual paste-in)
Gemini CLI	~/.gemini/GEMINI.md
Windsurf	~/.codeium/windsurf/memories/...
Cline	~/Documents/Cline/Rules/tok0.md
Amp	~/.config/amp/AGENTS.md
OpenCode	~/.config/opencode/AGENTS.md
Codex	~/.codex/AGENTS.md
Kimi Code	~/.kimi/tok0.md

tok0 status shows which surfaces are wired and the integrity hash of each one. tok0 verify re-checks every hook against tok0’s signed manifest — catches drift, manual edits, or tampering.

Resetting

tok0 init --remove   # remove every hook tok0 installed
rm -rf ~/.config/tok0 ~/.cache/tok0   # nuke local state

If you want to keep historic stats but reset hooks, just run tok0 init --remove — the meter database stays.