### [tokscale](https://github.com/junhoyeo/tokscale)

> Handle: `tokscale`

tokscale monitors AI token usage and costs across 23+ coding assistants. It reads local session files from tools like Claude Code, OpenCode, Cursor, Codex CLI, Gemini CLI, Goose, Zed Agent, and others, then displays token breakdowns, cost estimates, and daily/hourly statistics.

## Starting

```bash
harbor build tokscale
```

tokscale is a CLI tool that runs on demand, not a persistent service:

```bash
# JSON output
harbor tokscale --json

# Table view
harbor tokscale --light

# Interactive TUI
harbor tokscale
```

### Filtering

```bash
# Filter by client
harbor tokscale --client claude

# Time range
harbor tokscale --today
harbor tokscale --week
harbor tokscale --month
harbor tokscale --since 2025-01-01 --until 2025-01-31

# Group by model or client
harbor tokscale --group-by model
harbor tokscale --group-by client,model
```

## Configuration

### Environment Variables

Following options can be set via [`harbor config`](./3.-Harbor-CLI-Reference.md#harbor-config):

```bash
HARBOR_TOKSCALE_VERSION        # npm package version (default: latest)
HARBOR_TOKSCALE_HOME_DIR       # Host home directory to scan (default: ~)
HARBOR_TOKSCALE_CONFIG_DIR     # tokscale config and cache dir (default: ~/.config/tokscale)
```

### Volumes

- `${HARBOR_TOKSCALE_HOME_DIR}:/root:ro` -- Host home directory (read-only). Covers all AI tool session directories at their expected paths.
- `${HARBOR_TOKSCALE_CONFIG_DIR}:/root/.config/tokscale` -- tokscale configuration and pricing cache (writable overlay).

## Harbor Integrations

When running alongside Harbor services, tokscale automatically picks up their session data via cross-service compose files:

| Service | Cross-file | What it mounts |
|---------|------------|----------------|
| OpenCode | `compose.x.tokscale.opencode.yml` | `${HARBOR_OPENCODE_DATA}` at `/root/.local/share/opencode` |
| Hermes | `compose.x.tokscale.hermes.yml` | `${HARBOR_HERMES_WORKSPACE}/data` at `/root/.hermes` |
| OpenClaw | `compose.x.tokscale.openclaw.yml` | `${HARBOR_OPENCLAW_CONFIG_DIR}` at `/root/.openclaw` |

These overlays are applied automatically when the services run together.

## Supported Tools

tokscale scans session data from:

| Tool | Data Location |
|------|---------------|
| Claude Code | `~/.claude/projects/`, `~/.claude/transcripts/` |
| OpenCode | `~/.local/share/opencode/` |
| Codex CLI | `~/.codex/sessions/` |
| Copilot CLI | `~/.copilot/otel/` |
| Gemini CLI | `~/.gemini/tmp/*/chats/` |
| Cursor IDE | `~/.config/tokscale/cursor-cache/` (API sync) |
| Amp | `~/.local/share/amp/threads/` |
| Goose | `~/.local/share/goose/sessions/` |
| Zed Agent | `~/.local/share/zed/threads/` |
| Roo Code | `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/` |
| Kilo / Kilo CLI | `~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/`, `~/.local/share/kilo/` |
| OpenClaw | `~/.openclaw/agents/` |
| Hermes | `~/.hermes/` |
| Pi | `~/.pi/agent/sessions/`, `~/.omp/agent/sessions/` |
| Kimi CLI | `~/.kimi/sessions/` |
| Qwen CLI | `~/.qwen/projects/` |
| Factory Droid | `~/.factory/sessions/` |
| Mux | `~/.mux/sessions/` |
| Crush | `~/.local/share/crush/` |
| Codebuff | `~/.config/manicode/` |

## Troubleshooting

If tokscale reports no sessions found, verify that the home directory mount is correct:

```bash
harbor config get tokscale.home.dir
ls ~/
```

To rebuild after updating the version:

```bash
harbor config set tokscale.version 2.0.0
harbor build tokscale
```

## Links

- [GitHub Repository](https://github.com/junhoyeo/tokscale)
- [npm Package](https://www.npmjs.com/package/tokscale)
