Configuration

Config file format, agent overrides, capture settings, storage, and merge rules.

TokenJam reads its config from ~/.config/tj/config.toml (created by tj onboard). All settings can be overridden via the CLI, the REST API, or the web UI. The file is the source of truth and is regenerated when you save.

Example

# ~/.config/tj/config.toml (generated by tj onboard)

[defaults.budget]
daily_usd = 10.00

[agents.my-email-agent]
description = "Personal email management agent"

  [agents.my-email-agent.budget]
  daily_usd   = 5.00
  session_usd = 1.00

  [[agents.my-email-agent.sensitive_actions]]
  name     = "send_email"
  severity = "critical"

  [agents.my-email-agent.drift]
  enabled           = true
  baseline_sessions = 10
  token_threshold   = 2.0

[capture]
prompts      = false
completions  = false
tool_outputs = false

[storage]
path           = "~/.config/tj/telemetry.duckdb"
retention_days = 90

Merge rules

Budget limits merge per-field: each agent inherits [defaults.budget] unless overridden. Setting daily_usd on one agent doesn’t reset session_usd to nothing.

Capture settings

By default, prompt and completion text are not stored. Flip [capture] flags to record them locally. Useful for debugging, but the data only ever exists on your machine.

FlagWhat it records
promptsThe user/system prompt sent to the model.
completionsThe model’s response text.
tool_outputsThe raw return value of each tool call.

When capture.* is false, only metadata (tokens, cost, latency, span structure) is stored.

Storage

DuckDB is the only datastore. The file lives at [storage].path and is opened read-write by tj serve and read-only by the MCP server and CLI. retention_days controls automatic pruning of old spans.

Discovery order

tj looks for config in this order:

  1. --config <path> CLI flag
  2. TJ_CONFIG environment variable
  3. ./tj.config.toml (current directory)
  4. ~/.config/tj/config.toml (default, written by tj onboard)

The first match wins.

Verification

Run tj doctor to check that your config is well-formed and matches what the daemon is using:

tj doctor

doctor reports missing fields, invalid types, conflicting overrides, and whether the daemon picked up your most recent edits.