{"id":51345279,"url":"https://github.com/toktop/toktop","last_synced_at":"2026-07-02T11:01:54.667Z","repository":{"id":363538123,"uuid":"1263749503","full_name":"toktop/toktop","owner":"toktop","description":"Local-first usage and live status for Claude Code \u0026 Codex sessions — skills, MCP servers, and tools.","archived":false,"fork":false,"pushed_at":"2026-06-17T03:10:41.000Z","size":898,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T05:10:48.546Z","etag":null,"topics":["claude-code","codex","developer-tools","observability","token-usage","transcript-analysis","usage-analytics"],"latest_commit_sha":null,"homepage":"https://toktop.unceas.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toktop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T08:28:05.000Z","updated_at":"2026-06-17T03:10:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/toktop/toktop","commit_stats":null,"previous_names":["toktop/toktop"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/toktop/toktop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toktop%2Ftoktop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toktop%2Ftoktop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toktop%2Ftoktop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toktop%2Ftoktop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toktop","download_url":"https://codeload.github.com/toktop/toktop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toktop%2Ftoktop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35043938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","developer-tools","observability","token-usage","transcript-analysis","usage-analytics"],"created_at":"2026-07-02T11:01:53.992Z","updated_at":"2026-07-02T11:01:54.660Z","avatar_url":"https://github.com/toktop.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.png\" alt=\"\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eToktop\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Local-first usage and live status for Claude Code, Codex \u0026amp; opencode sessions — skills, MCP servers, and tools.\n\u003c/p\u003e\n\n`toktop` reads the local session data that **Claude Code**, **Codex**, and **opencode**\nrecord on your machine (JSONL transcripts for the first two, a SQLite store for opencode),\nnormalizes them into one provider-neutral model, and exposes everything through a CLI, an\nHTTP API, and a low-latency **live event stream** over Server-Sent Events.\n\nIt answers questions like: *which MCP servers and skills are installed but never actually\nused? where did a tool retry-loop burn tokens? how many turns and tokens did a session\ntake? what is happening in my agent sessions right now?*\n\n**Everything runs locally** — no network calls, no telemetry, transcripts never leave your\nmachine. Secret redaction is on by default.\n\n```console\n$ toktop summary\nraw events: 84120\nsessions: 1109\nturns: 3195\ninvocations: 38964\ntool calls: 26397\ninput tokens: 14.8M\noutput tokens: 41.3M\ncache read tokens: 3.9B\n```\n\n\u003e This README is a quick tour — a simple intro and getting started. The full reference (every\n\u003e command, flag, HTTP route, and config key) lives on the docs site at\n\u003e [toktop.unceas.dev](https://toktop.unceas.dev).\n\n---\n\n## Install\n\n**macOS / Linux**\n\n```bash\ncurl -fsSL https://toktop.unceas.dev/install.sh | sh\n```\n\n**Windows (PowerShell)**\n\n```powershell\nirm https://toktop.unceas.dev/install.ps1 | iex\n```\n\nThis drops a prebuilt binary in `~/.local/bin` (or `%LOCALAPPDATA%\\toktop\\bin` on Windows) —\nno compiler needed, and the web UI is embedded. Override the location with `TOKTOP_INSTALL_DIR`.\nRe-run the same command to upgrade (it overwrites in place). Releases are signed with\n[cosign](https://docs.sigstore.dev/) and the installer verifies them automatically.\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from source\u003c/summary\u003e\n\nRequires **Go 1.26+**, CGO (a C compiler), and the mandatory `sqlite_fts5` build tag — toktop\nprobes for FTS5 on startup and refuses to run without it.\n\n```bash\ngit clone https://github.com/toktop/toktop \u0026\u0026 cd toktop\nCGO_ENABLED=1 go build -tags sqlite_fts5 -o toktop ./cmd/toktop\n```\n\nA source build has **no embedded web UI**; run `make ui` (needs Node + pnpm) to build the SPA\nand embed it. `make build` stamps git-derived version metadata.\n\n\u003c/details\u003e\n\n---\n\n## Quick start\n\n```bash\ntoktop init        # create ~/.toktop/{config,data}\ntoktop ingest      # import Claude Code / Codex / opencode sessions (idempotent)\ntoktop summary     # imported counts and token totals\ntoktop status      # what's happening in your sessions right now\n```\n\n`toktop ingest` auto-detects which providers are present on disk and is idempotent (IDs are\ncontent-hashed), so re-run it any time — unchanged transcripts are skipped. Run `toktop doctor`\nif something looks off.\n\n```\nClaude Code / Codex transcripts (JSONL) · opencode session store (SQLite)\n        │  collect + parse (per provider)\n        ▼\n   provider-neutral trace index\n   sessions → turns → invocations → tool calls   (+ MCP servers, skills)\n        │  store\n        ▼\n   local SQLite (+ FTS5 full-text index)  ──►  CLI · HTTP API · live SSE stream\n```\n\nYour session data is the **source of truth**: toktop stores normalized rows plus a pointer\nback to the transcript and re-reads on demand.\n\n---\n\n## Analyze your usage\n\nAnalytics read the local SQLite DB directly (no daemon needed), reflecting the database as of\nthe last `toktop ingest` or daemon reconcile.\n\n| Command | Shows |\n| --- | --- |\n| `toktop summary` | Trace counts + token totals |\n| `toktop sessions` | Sessions, most-recent first (`sessions inspect \u003cid\u003e` for one) |\n| `toktop turns` | Turns (`turns inspect\\|timeline\\|components \u003cid\u003e` for one) |\n| `toktop search \u003cquery\u003e` | Full-text search over turn text and tool calls (FTS5) |\n| `toktop mcps` | MCP server usage (`mcps unused` = declared but never called) |\n| `toktop skills` | Skill usage (`skills unused` = installed but never used) |\n| `toktop tools` | Tool-call usage per tool (`tools calls --name \u003ctool\u003e` drills into individual calls) |\n| `toktop models` | Model invocation usage (calls / turns / tokens, per provider+model) |\n| `toktop projects` | Per-project session / turn / tool counts |\n| `toktop suggestions` | Rule-engine findings over your history |\n| `toktop sources` | Configured providers and their discovery roots |\n\nMost commands share filter flags (`--sources`, `--project`, `--session`, `--status`,\n`--since`/`--until`, `--subagents`) and output flags (`--format table|json|ndjson|csv|markdown|html`,\n`--output`, `--columns`). Subagent transcripts are excluded by default; `--subagents` folds them in.\n\n```bash\ntoktop turns --sources claude-code --since 24h --sort tokens_desc --limit 10\ntoktop search 'rate limit' kind:turn source:claude-code --limit 20\ntoktop tools calls --name Bash --status failed\n```\n\n---\n\n## Live status \u0026 event stream\n\ntoktop is a **real-time event broker**, not just a transcript analyzer. A background daemon\nwatches your transcript roots (and, with hooks installed, receives status callbacks from the\nagents themselves), fans events out over SSE, and answers a current live-status query — so\ndashboards, status bars, and RGB indicators can react to what your agents are doing right now.\n\n```bash\ntoktop status                                      # every active session's current state\ntoktop stream                                      # subscribe to the live event stream (SSE)\ntoktop stream claude-code:ID --status-only         # status changes only, no firehose\ntoktop stream --status success,failed,completed    # filter by tidy provider-neutral status\ntoktop stream --type hook.stop                      # filter by raw event type\n```\n\n`status` / `stream` auto-start a daemon on demand and it idle-stops when no consumer is\nlistening. Install observer hooks to make status near-instant, or run a daemon explicitly:\n\n```bash\ntoktop hooks install --sources=claude-code,codex   # opencode installs a plugin instead\ntoktop daemon serve                                 # watch transcripts + serve HTTP/SSE + broker\n```\n\nThe status vocabulary, the `--status`/`--type` filter grains, per-provider hook/plugin setup,\nand `toktop emit` are covered on the docs site.\n\n---\n\n## Web UI\n\n`toktop ui` opens a local web interface backed by the daemon. It mirrors the CLI's read\nsurface as browsable screens — a **dashboard**, **sessions**, full-text **search**, a live\n**events** view, **analytics**, and **daemon** status/control — plus a **settings** page, the\nonly place the UI can write.\n\n```bash\ntoktop ui                   # bind a random loopback port, open the browser\ntoktop ui --no-browser      # print the URL instead of opening a browser\n```\n\nPrebuilt binaries ship with the UI embedded. It runs as a loopback-only reverse-proxy that\ninjects the daemon token so the browser never sees it — no remote access, no telemetry.\n\n---\n\n## Handoff\n\nHit a quota limit or an interruption mid-workflow and want to continue in the *other* agent?\n`toktop handoff` packages one session as an **Evidence-based Handoff Package** another agent\ncan pick up — symmetric between Claude Code and Codex.\n\n```bash\ntoktop handoff create --session \u003cid\u003e   # → ~/.toktop/handoff/\u003csession\u003e/\n```\n\nIt leads with a lean `digest.md` (the user→assistant narrative, no tool-call bloat) and, for a\nmulti-agent workflow, recovers each completed sub-agent's real result so they are reused, not\nre-run. The same package is served at `GET /v1/sessions/{id}/handoff`. To consume one, use the\n[`toktop-resume`](skills/toktop-resume/) agent skill (`npx skills add toktop/toktop/skills/toktop-resume`).\n\n---\n\n## HTTP API \u0026 configuration\n\nAn HTTP API v1 exposes the same read surface plus the live stream. By default it binds a unix\nsocket (`~/.toktop/run/toktop.sock`, mode `0600`, same-user only); TCP is opt-in via config and\nrequires a bearer token off loopback.\n\n```bash\ntoktop serve            # HTTP API only (no transcript watching)\ntoktop daemon serve     # API + transcript watching + live broker\n```\n\n`~/.toktop/config/config.json` is the single source of truth for every persistent setting\n(edits hot-reload):\n\n```bash\ntoktop config get                          # all effective values + their source\ntoktop config set addr tcp://127.0.0.1:8787\n```\n\nThe full route table and every config key are on the docs site.\n\n---\n\n## Privacy \u0026 uninstall\n\n- **Local-first** — no network calls, no telemetry; transcripts never leave your machine.\n- **Redaction** is on by default over persisted/indexed text (turn text, tool input/output) — never the raw transcript bytes.\n- **Same-user only** — the default unix socket is `0600`; TCP off loopback requires a token.\n\n```bash\ntoktop uninstall              # stop daemon, remove injected hooks, delete ~/.toktop\ntoktop uninstall --keep-data  # keep config / data / DB\n```\n\ntoktop only ever *reads* your transcripts (its hooks are its only writes), so removing it\nleaves Claude Code, Codex, and their history untouched.\n\n---\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoktop%2Ftoktop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoktop%2Ftoktop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoktop%2Ftoktop/lists"}