Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/toktop/toktop

Local-first usage and live status for Claude Code & Codex sessions — skills, MCP servers, and tools.
https://github.com/toktop/toktop

claude-code codex developer-tools observability token-usage transcript-analysis usage-analytics

Last synced: 6 days ago
JSON representation

Local-first usage and live status for Claude Code & Codex sessions — skills, MCP servers, and tools.

Awesome Lists containing this project

README 

          


  




Toktop





  Local-first usage and live status for Claude Code, Codex & opencode sessions — skills, MCP servers, and tools.




`toktop` reads the local session data that **Claude Code**, **Codex**, and **opencode**

record on your machine (JSONL transcripts for the first two, a SQLite store for opencode),

normalizes them into one provider-neutral model, and exposes everything through a CLI, an

HTTP API, and a low-latency **live event stream** over Server-Sent Events.



It answers questions like: *which MCP servers and skills are installed but never actually

used? where did a tool retry-loop burn tokens? how many turns and tokens did a session

take? what is happening in my agent sessions right now?*



**Everything runs locally** — no network calls, no telemetry, transcripts never leave your

machine. Secret redaction is on by default.



```console

$ toktop summary

raw events: 84120

sessions: 1109

turns: 3195

invocations: 38964

tool calls: 26397

input tokens: 14.8M

output tokens: 41.3M

cache read tokens: 3.9B

```



> This README is a quick tour — a simple intro and getting started. The full reference (every

> command, flag, HTTP route, and config key) lives on the docs site at

> [toktop.unceas.dev](https://toktop.unceas.dev).



---



## Install



**macOS / Linux**



```bash

curl -fsSL https://toktop.unceas.dev/install.sh | sh

```



**Windows (PowerShell)**



```powershell

irm https://toktop.unceas.dev/install.ps1 | iex

```



This drops a prebuilt binary in `~/.local/bin` (or `%LOCALAPPDATA%\toktop\bin` on Windows) —

no compiler needed, and the web UI is embedded. Override the location with `TOKTOP_INSTALL_DIR`.

Re-run the same command to upgrade (it overwrites in place). Releases are signed with

[cosign](https://docs.sigstore.dev/) and the installer verifies them automatically.



Build from source



Requires **Go 1.26+**, CGO (a C compiler), and the mandatory `sqlite_fts5` build tag — toktop

probes for FTS5 on startup and refuses to run without it.



```bash

git clone https://github.com/toktop/toktop && cd toktop

CGO_ENABLED=1 go build -tags sqlite_fts5 -o toktop ./cmd/toktop

```



A source build has **no embedded web UI**; run `make ui` (needs Node + pnpm) to build the SPA

and embed it. `make build` stamps git-derived version metadata.



---



## Quick start



```bash

toktop init        # create ~/.toktop/{config,data}

toktop ingest      # import Claude Code / Codex / opencode sessions (idempotent)

toktop summary     # imported counts and token totals

toktop status      # what's happening in your sessions right now

```



`toktop ingest` auto-detects which providers are present on disk and is idempotent (IDs are

content-hashed), so re-run it any time — unchanged transcripts are skipped. Run `toktop doctor`

if something looks off.



```

Claude Code / Codex transcripts (JSONL) · opencode session store (SQLite)

        │  collect + parse (per provider)

        ▼

   provider-neutral trace index

   sessions → turns → invocations → tool calls   (+ MCP servers, skills)

        │  store

        ▼

   local SQLite (+ FTS5 full-text index)  ──►  CLI · HTTP API · live SSE stream

```



Your session data is the **source of truth**: toktop stores normalized rows plus a pointer

back to the transcript and re-reads on demand.



---



## Analyze your usage



Analytics read the local SQLite DB directly (no daemon needed), reflecting the database as of

the last `toktop ingest` or daemon reconcile.



| Command | Shows |

| --- | --- |

| `toktop summary` | Trace counts + token totals |

| `toktop sessions` | Sessions, most-recent first (`sessions inspect ` for one) |

| `toktop turns` | Turns (`turns inspect\|timeline\|components ` for one) |

| `toktop search ` | Full-text search over turn text and tool calls (FTS5) |

| `toktop mcps` | MCP server usage (`mcps unused` = declared but never called) |

| `toktop skills` | Skill usage (`skills unused` = installed but never used) |

| `toktop tools` | Tool-call usage per tool (`tools calls --name ` drills into individual calls) |

| `toktop models` | Model invocation usage (calls / turns / tokens, per provider+model) |

| `toktop projects` | Per-project session / turn / tool counts |

| `toktop suggestions` | Rule-engine findings over your history |

| `toktop sources` | Configured providers and their discovery roots |



Most commands share filter flags (`--sources`, `--project`, `--session`, `--status`,

`--since`/`--until`, `--subagents`) and output flags (`--format table|json|ndjson|csv|markdown|html`,

`--output`, `--columns`). Subagent transcripts are excluded by default; `--subagents` folds them in.



```bash

toktop turns --sources claude-code --since 24h --sort tokens_desc --limit 10

toktop search 'rate limit' kind:turn source:claude-code --limit 20

toktop tools calls --name Bash --status failed

```



---



## Live status & event stream



toktop is a **real-time event broker**, not just a transcript analyzer. A background daemon

watches your transcript roots (and, with hooks installed, receives status callbacks from the

agents themselves), fans events out over SSE, and answers a current live-status query — so

dashboards, status bars, and RGB indicators can react to what your agents are doing right now.



```bash

toktop status                                      # every active session's current state

toktop stream                                      # subscribe to the live event stream (SSE)

toktop stream claude-code:ID --status-only         # status changes only, no firehose

toktop stream --status success,failed,completed    # filter by tidy provider-neutral status

toktop stream --type hook.stop                      # filter by raw event type

```



`status` / `stream` auto-start a daemon on demand and it idle-stops when no consumer is

listening. Install observer hooks to make status near-instant, or run a daemon explicitly:



```bash

toktop hooks install --sources=claude-code,codex   # opencode installs a plugin instead

toktop daemon serve                                 # watch transcripts + serve HTTP/SSE + broker

```



The status vocabulary, the `--status`/`--type` filter grains, per-provider hook/plugin setup,

and `toktop emit` are covered on the docs site.



---



## Web UI



`toktop ui` opens a local web interface backed by the daemon. It mirrors the CLI's read

surface as browsable screens — a **dashboard**, **sessions**, full-text **search**, a live

**events** view, **analytics**, and **daemon** status/control — plus a **settings** page, the

only place the UI can write.



```bash

toktop ui                   # bind a random loopback port, open the browser

toktop ui --no-browser      # print the URL instead of opening a browser

```



Prebuilt binaries ship with the UI embedded. It runs as a loopback-only reverse-proxy that

injects the daemon token so the browser never sees it — no remote access, no telemetry.



---



## Handoff



Hit a quota limit or an interruption mid-workflow and want to continue in the *other* agent?

`toktop handoff` packages one session as an **Evidence-based Handoff Package** another agent

can pick up — symmetric between Claude Code and Codex.



```bash

toktop handoff create --session    # → ~/.toktop/handoff//

```



It leads with a lean `digest.md` (the user→assistant narrative, no tool-call bloat) and, for a

multi-agent workflow, recovers each completed sub-agent's real result so they are reused, not

re-run. The same package is served at `GET /v1/sessions/{id}/handoff`. To consume one, use the

[`toktop-resume`](skills/toktop-resume/) agent skill (`npx skills add toktop/toktop/skills/toktop-resume`).



---



## HTTP API & configuration



An HTTP API v1 exposes the same read surface plus the live stream. By default it binds a unix

socket (`~/.toktop/run/toktop.sock`, mode `0600`, same-user only); TCP is opt-in via config and

requires a bearer token off loopback.



```bash

toktop serve            # HTTP API only (no transcript watching)

toktop daemon serve     # API + transcript watching + live broker

```



`~/.toktop/config/config.json` is the single source of truth for every persistent setting

(edits hot-reload):



```bash

toktop config get                          # all effective values + their source

toktop config set addr tcp://127.0.0.1:8787

```



The full route table and every config key are on the docs site.



---



## Privacy & uninstall



- **Local-first** — no network calls, no telemetry; transcripts never leave your machine.

- **Redaction** is on by default over persisted/indexed text (turn text, tool input/output) — never the raw transcript bytes.

- **Same-user only** — the default unix socket is `0600`; TCP off loopback requires a token.



```bash

toktop uninstall              # stop daemon, remove injected hooks, delete ~/.toktop

toktop uninstall --keep-data  # keep config / data / DB

```



toktop only ever *reads* your transcripts (its hooks are its only writes), so removing it

leaves Claude Code, Codex, and their history untouched.



---



## License



Licensed under the [Apache License 2.0](LICENSE).