# Check it works: your first session

> Confirm Tokenade is wired into your agent: run tokenade healthcheck, start a session, then see the savings in tokenade dashboard.

Source: https://tokenade.net/en/docs/first-session · Updated: 2026-10-16

To check that Tokenade works, run `tokenade healthcheck`, then use your agent normally for a few minutes and look at `tokenade hooks tail` and `tokenade dashboard`. If hooks fire and the savings ledger grows, Tokenade is doing its job. You do not need to change how you prompt.

## 1. Run the health check

```bash
tokenade healthcheck
```

`healthcheck` (aliases `health` and `doctor`) verifies the install and prints one row per check. `OK` rows pass, `--` rows are information, and a failing row is marked `!!` and names its fix. Trimmed example:

```text
─── tokenade healthcheck ───

  OK  gain ledger writable at ~/.tokenade/gain.jsonl
  OK  all agent-config hook paths resolve
  OK  every hook runs the same tokenade binary
  OK  installed hook commands match the expected tokenade shape
  OK  Codex hooks trusted — compaction active (6 hook(s))
  OK  agent detected: claude-code
```

Exit code `0` means all checks pass (some may show info-only `--` rows); `1` means at least one check failed. For scripts and CI, use `tokenade healthcheck --json`: each check carries a stable `id` (for example `binary`, `gain_ledger`, `agent_detect`, `hook_installed`, `mcp_entry`, `wrapped_mcps`, `semantic_model`, `stale_mcp_procs`).

The rows you most want to see:

- `gain ledger writable`: Tokenade can record your savings locally.
- One row per wired agent, for example `opencode plugin active — tool-result compaction firing` or `Codex hooks trusted`.

### Claude Code: accept the folder trust prompt

Claude Code runs no hooks at all, Tokenade's included, in an interactive session in a folder whose trust prompt you have not accepted. Since 1.2.1, `healthcheck` says so:

```text
  --  Claude Code has not trusted /path/to/project — in an interactive session here, it runs none of its hooks (tokenade's included)
       accept the trust prompt when Claude Code opens this folder; `claude -p` runs are not affected
```

Open the folder in Claude Code and accept the prompt. See [Claude Code](https://tokenade.net/en/docs/claude-code).

## 2. See which agent Tokenade detects

```bash
tokenade detect
```

```text
claude-code
coverage: hooks (PostToolUse) — command output is compacted and the saving is measured
mcp config hint: .mcp.json (third-party servers only)
```

The `coverage:` line describes the channel this type of agent uses, not whether it is installed on your machine. `healthcheck` answers that second question.

## 3. Use your agent

Start a session as usual and give the agent a task that produces output: run the test suite, a build, `git log`, read a large file, search the web. Nothing changes on your side. Long outputs reach the model folded, with a short banner that tells the agent how to get the full bytes back if it needs them (see [Output compaction and the stash](https://tokenade.net/en/docs/compaction)).

## 4. Watch the hooks fire

```bash
tokenade hooks status    # installed Claude Code hooks
tokenade hooks tail      # last 20 hook-fire records from ~/.tokenade/debug.log
tokenade hooks tail 50   # last 50
```

`hooks status` lists each installed hook with its event, then recent activity: how many times the hooks fired and when they last did.

If the activity list stays empty after you used the agent, the hooks are not running: see [Troubleshooting](https://tokenade.net/en/docs/troubleshooting).

## 5. Check your savings

```bash
tokenade dashboard
```

`dashboard` (aliases `dash` and `stats`) reads the local savings ledger (`~/.tokenade/gain.jsonl`) and opens a local report in your browser: pick a period, then drill down by function, agent, project and model. For a quick summary in the terminal:

```bash
tokenade gain                # operations, tokens before and after, breakdown by operation
tokenade gain --history      # one row per ledger entry, after the summary
tokenade gain --by-source    # split by source: cli / hook / mcp / proxy
```

Everything `gain` and `dashboard` show is computed on your machine. How the figures are counted, and what is excluded, is explained in [How savings are measured](https://tokenade.net/en/docs/savings-measurement).

## Still nothing?

1. Re-run `tokenade install`: it is idempotent and repairs missing hooks.
2. Make sure you did not run install with `sudo` (it writes to `/root` and refuses by default).
3. Check that `TOKENADE_HOOK_DISABLED` is not set in your agent's environment.
4. Check the agent-specific steps: [Claude Code](https://tokenade.net/en/docs/claude-code) folder trust, [Codex](https://tokenade.net/en/docs/codex) hook approval.

## Related

- [Install Tokenade](https://tokenade.net/en/docs/install)
- [Supported agents and compatibility](https://tokenade.net/en/docs/compatibility)
- [gain, dashboard and receipt](https://tokenade.net/en/docs/gain-dashboard-receipt)
- [Troubleshooting](https://tokenade.net/en/docs/troubleshooting)
