Custom Data Directory

Move TokenAnalytics's config and state to a different directory using --data-dir, TOKENANALYTICS_DATA_DIR, or TOKENANALYTICS_HOME.

By default, TokenAnalytics stores all its config and state in ~/.tokenanalytics/. You can move this to any directory you like — useful for keeping your system drive clear, isolating tool state on a secondary drive, or running multiple independent instances.

Precedence

Three mechanisms control the data directory location. First match wins:

--data-dir <path> (or -d <path>) — launcher flag, highest precedence.
TOKENANALYTICS_DATA_DIR=<path> — environment variable, used verbatim (no .tokenanalytics suffix appended).
TOKENANALYTICS_HOME=<path> — environment variable, appends .tokenanalytics as a subdirectory under the given path.
Default: ~/.tokenanalytics/.

The legacy TOKENTELEMETRY_DATA_DIR / TOKENTELEMETRY_HOME names are still accepted for backward compatibility.

Using the flag

./start.sh --data-dir /mnt/d/tt-data
# or shorthand:
./start.sh -d /mnt/d/tt-data

The directory is created on first write. Subsequent launches use the same path if you pass the same flag.

Windows tip: Avoid a trailing backslash when quoting a path in cmd.exe. --data-dir "D:\tt\" fails because \" escapes the closing quote. Use --data-dir D:\tt or --data-dir "D:/tt" instead.

Using environment variables

# Exact path (no suffix appended):
export TOKENANALYTICS_DATA_DIR=/mnt/d/tt-data
./start.sh

# Home override (appends .tokenanalytics):
export TOKENANALYTICS_HOME=/mnt/d
# → data dir: /mnt/d/.tokenanalytics
./start.sh

An explicit --data-dir flag wins over both env vars.

What lives in the data directory

Everything moves together when you change the data directory:

File / folder	Contents
`aliases.json`	Path aliases — rename or merge project folder paths
`hidden.json`	Projects excluded from the dashboard
`preferences.json`	App preferences (the update-check toggle)
`billing.json`	Per-agent billing-mode overrides
`power.json`	Local-model wattage and electricity settings
`summarizer.json`	Summarizer backend selection and model settings
`summaries.db`	Cached session summaries (SQLite)
`history.db`	Durable session history (SQLite, if enabled)
`VERSION`	Schema version integer for future migrations
`.update-check.json`	Timestamp and SHA of last update check result

None of these files contain session transcript data by default. history.db may contain transcripts if you enable transcript archival.

Moving an existing data directory

Stop TokenAnalytics, move the directory, then relaunch with the new path:

mv ~/.tokenanalytics /mnt/d/tt-data
./start.sh --data-dir /mnt/d/tt-data

All your aliases, preferences, summaries, and history move with it.

Running multiple instances

To run two independent TokenAnalytics instances (e.g. one per project or one per user on a shared machine), give each a different data directory and different ports:

# Instance A
./start.sh --data-dir ~/tt-work --port 3000 --api-port 8000

# Instance B
./start.sh --data-dir ~/tt-personal --port 3001 --api-port 8001

Both read the same agent log files, but maintain separate aliases, preferences, and summaries.