Skip to content
TTDash

Install and run TTDash

TTDash is a local-first dashboard and CLI for toktrack usage data. The fastest path is to run the latest published package directly.

Requirements

Section titled “Requirements”
  • Node.js 20 or newer for npm and npx installations
  • a modern browser
  • npm or Bun when auto-import needs a package-runner fallback
  • Typst only when you want PDF export
  • Docker with Compose v2 only for container deployments

Run without a global install

Section titled “Run without a global install”

Use either package runner:

npm / npx
npx --yes @roastcodes/ttdash@latest
Bun
bunx @roastcodes/ttdash@latest

TTDash starts on http://127.0.0.1:3000. If that port is occupied, it tries the requested port and up to 100 following ports, then prints the selected URL.

Install globally

Section titled “Install globally”

Install the ttdash command when you use it regularly:

npm
npm install --global @roastcodes/ttdash
ttdash
Bun
bun add --global @roastcodes/ttdash
ttdash

Confirm the executable without starting the server:

Terminal window
ttdash --help

First launch

Section titled “First launch”
  1. Start TTDash.
  2. Let it open the generated local authentication URL, or copy the Local Auth URL from the terminal when browser opening is disabled.
  3. Select Auto import to run the TTDash-pinned toktrack version, or choose Upload and select compatible JSON.
  4. Use the filter bar to choose a period, provider, model, and daily/monthly/yearly aggregation.
  5. Open Settings to save default filters, section order, theme, language, and motion preferences.

The local server generates a fresh bootstrap token for each start, exchanges it for an HttpOnly browser cookie, and removes it from the address. You do not need to configure a password for ordinary loopback use.

Common starts

Section titled “Common starts”
Terminal window
# Choose the first port to try.
ttdash --port 3010


# Do not open a browser.
ttdash --no-open


# Import toktrack data once during startup.
ttdash --auto-load


# Run as a managed background instance.
ttdash --background


# Stop a managed background instance.
ttdash stop

Flags can be combined:

Terminal window
ttdash --background --port 3010 --auto-load

See Configuration and CLI for every supported option, environment variable, and storage location.

Keep enough source history

Section titled “Keep enough source history”

toktrack can only report usage that still exists in the underlying tools’ local history. For example, Claude Code removes older sessions after its configured retention period. If you need a longer history, set an appropriate cleanupPeriodDays in ~/.claude/settings.json before old sessions are removed:

{
  "cleanupPeriodDays": 365
}

Choose a retention value that matches your own storage and privacy requirements.

Next steps

Section titled “Next steps”