agent-session-inspector 0.1.4 → 0.1.5

package/app/README.md

@@ -5,9 +5,14 @@
 [![node](https://img.shields.io/node/v/agent-session-inspector)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/agent-session-inspector)](LICENSE)
 
-A local web UI for reading coding-agent transcripts (Claude Code, Codex, GitHub
-Copilot, OpenCode, Hermes): what the agent did, how long it took, and where the
-tokens went.
+See exactly where a coding-agent session's tokens and dollars went. A local
+inspector for Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode
+and Hermes transcripts: every prompt, thought, tool call and injected piece of
+context in order, each with its own token count and cost.
+
+It answers the questions a usage total cannot: why one session cost $12, which
+turn blew up the context, how much of it was system prompt and tool results
+rather than conversation, and which tool kept failing.
 
 > **Your sessions never leave your machine.** The app collects nothing: no
 > telemetry, no analytics, no account, no cloud. It reads the transcript files
@@ -58,6 +63,130 @@ rm -rf ~/.agent-session-inspector ~/.local/bin/agent-session-inspector
 The install script needs bash, so it covers macOS, Linux and WSL. On Windows
 use `npx`.
 
+## Features
+
+### Inspect one session
+
+**Step-by-step timeline.** Prompts, reasoning, tool calls and their results in
+order, with per-step token counts and cost. What the agent was given shows up
+too: system prompt, tool catalog, MCP instructions and skill listings appear as
+events with their size. Expand any event to see its content, or open the raw
+record.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/timeline-dark.png">
+  <img alt="Event timeline showing user prompt, thinking, and Grep/Read tool calls" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/timeline.png">
+</picture>
+
+**Token Optimizer.** What the session cost by token class, model and turn, where
+the context went (system prompt vs. tool results vs. replies), which tools ran
+most, and hints for trimming expensive sessions.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/token-optimizer-dark.png">
+  <img alt="Token Optimizer: estimated cost by token class and model, and a cost-by-turn chart" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/token-optimizer.png">
+</picture>
+
+**Session health.** A score out of 100 and a grade for how smoothly the session
+ran, with links to the failed tools, retry loops and interrupted turns that cost
+it points. See [Session health](#session-health).
+
+**Edits per turn.** A session's Edits tab lists each prompt with the files the
+agent wrote, edited or patched in response, linked to the event in the timeline.
+
+### Find the session worth inspecting
+
+**Full-text search.** `⌘K` / `Ctrl+K` searches every transcript of every agent:
+prompts, replies, reasoning, tool arguments and tool results, as well as titles,
+repos and branches. Each hit shows the matching line and what kind of event it
+came from.
+
+**All sessions in one place.** Every session of every supported agent on the
+machine, filterable by agent. Each card shows turns, tool calls, health grade,
+cost and tokens in/out at a glance.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/sessions-dark.png">
+  <img alt="Session list with agent filters, search and per-session health, cost and token counts" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/sessions.png">
+</picture>
+
+**Analytics across sessions.** Cost, messages, tool calls and active time for
+the selected range, with an activity calendar and filters for project, agent
+and model.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/analytics-dark.png">
+  <img alt="Analytics tab: cost, session and token totals above an activity calendar" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/analytics.png">
+</picture>
+
+**Projects.** Sessions are grouped by the repository they ran in, so work
+started from a subfolder or a git worktree lands in the same project. The
+Projects tab lists each one with its sessions, cost and tokens, and picking a
+project filters Analytics, Usage and Sessions together. Outside a repository,
+the working directory is the project; the dated scratch folders the Codex app
+creates for project-less chats count as one project.
+
+**Activity.** One day at a time: how many sessions were working at once in each
+15-minute slot, the agent time and cost of each session, and the day's split by
+project, model and agent.
+
+**Skills and MCP tools.** The Analytics tab counts which skills were loaded and
+which MCP servers and tools were called, for the selected range.
+
+> Screenshots use synthetic demo data. To reproduce them locally, see
+> [CONTRIBUTING.md](CONTRIBUTING.md#demo-data).
+
+## Terminal reports
+
+The same numbers are available without the web UI. Each command reads the
+transcripts, prints a report and exits:
+
+```bash
+npx agent-session-inspector usage      # tokens and estimated cost per day
+npx agent-session-inspector stats      # sessions, messages, tools and time, by agent
+npx agent-session-inspector sessions   # recent sessions with cost and health
+```
+
+```
+$ npx agent-session-inspector usage --by model --all
+Token usage · all time · by model
+
+Model                      Sessions  Input  Output  Cache read  Cache write   Total  Est. cost
+─────────────────────────  ────────  ─────  ──────  ──────────  ───────────  ──────  ─────────
+claude-opus-5-5                   1   2.5K    3.4K      318.0K        23.1K  347.0K      $0.26  ████████████████
+claude-sonnet-5                   1   2.0K    2.5K      235.1K        19.1K  258.8K      $0.12  ███████▊
+gpt-5.1                           1  11.6K    1.6K       27.3K            0   40.5K      $0.03  ██▏
+─────────────────────────  ────────  ─────  ──────  ──────────  ───────────  ──────  ─────────
+Total                             3  16.1K    7.5K      580.4K        42.2K  646.3K      $0.41
+```
+
+Reports cover the last 30 days unless `--days <n>` or `--all` says otherwise.
+`--agent`, `--project` and `--model` narrow them, and `--json` prints the data
+for scripts. `usage` groups by day by default; `--by` takes `week`, `month`,
+`project`, `model` or `agent`. `sessions --sort cost` lists the most expensive
+sessions first. `<command> --help` lists every option.
+
+#### Scripting
+
+The tables are for reading: values are rounded, and piping one drops the rules
+and bars but keeps the rounding. For automation use `--json`, which prints exact
+numbers under stable names:
+
+```bash
+npx agent-session-inspector usage --days 1 --json | jq '.total.costUSD'
+npx agent-session-inspector sessions --sort cost --json | jq -r '.sessions[].id'
+```
+
+Every report carries `schemaVersion` (currently `1`) and `days` (`null` for all
+time). New fields may appear within a version; a field is renamed or removed
+only with a new one. Costs are US dollars, or `null` where no price is known.
+
+| Command    | Fields                                                                                                   |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| `usage`    | `by`, `rows[]`, `total`, `unpricedModels`. A row has `key`, `sessions`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `totalTokens`, `costUSD`; `total` has the same without `key`. |
+| `stats`    | `totals`, `messagesPerSession`, `agents[]`, `projects[]`, `tools[]`, `skills[]`, `mcpServers[]`, `unpricedModels`. |
+| `sessions` | `sort`, `total` (matches before `--limit`), `sessions[]`. A session has `agent`, `id`, `title`, `project`, `model`, `createdAt`, `updatedAt`, `userMessages`, `toolCalls`, `inputTokens`, `outputTokens`, `estimatedCostUSD`, `health`. |
+
 ## Supported agents
 
 | Agent                         | Reads from                                     | Session titles        | Logs |
@@ -69,18 +198,26 @@ use `npx`.
 | OpenAI Codex CLI              | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `session_index.jsonl` | no   |
 | OpenCode                      | `~/.local/share/opencode/opencode.db`          | `session` table       | no   |
 | Hermes Agent                  | `~/.hermes/state.db`                           | `sessions` table      | no   |
+| Gemini CLI                    | `~/.gemini/tmp/<project>/chats/session-*`      | session summary       | no   |
+| Cursor                        | `<Cursor>/User/globalStorage/state.vscdb`      | chat name             | no   |
 
-`<Code>` and `<Claude>` are the desktop apps' data folders: `~/Library/Application
-Support/…` on macOS, `%APPDATA%\…` on Windows, `~/.config/…` on Linux. VS Code
-Insiders is read too. The two SQLite stores are opened read-only.
+`<Code>`, `<Claude>` and `<Cursor>` are the desktop apps' data folders:
+`~/Library/Application Support/…` on macOS, `%APPDATA%\…` on Windows,
+`~/.config/…` on Linux. VS Code Insiders is read too. The SQLite stores are
+opened read-only.
 
-Two things differ from the CLIs that log every request:
+Three things differ from the CLIs that log every request:
 
 - **Copilot Chat** meters a whole request, and its prompt count is that of the
   last model round. For a request that called tools, input tokens and cost are a
   floor.
 - **Hermes** counts tokens per session, so its usage appears as one checkpoint at
   the end of the timeline rather than per message.
+- **Cursor** rarely writes token counts to disk, so most of its sessions show the
+  timeline, tools and timing but no tokens or cost. Only the chat table of
+  `state.vscdb` is read. A session that is not in it, such as one from the
+  Cursor CLI, is read from the plainer transcript under `~/.cursor/projects`,
+  which has no tool results and is timed to the minute.
 
 Whichever directories exist on the machine show up; the rest are hidden.
 
@@ -105,64 +242,15 @@ You don't have to take this on trust. The code is open, and the browser's
 Network tab shows every request going to `localhost` and nowhere else; the app
 works the same with the network disconnected.
 
-## Features
-
-**Analytics across sessions.** Cost, messages, tool calls and active time for
-the selected range, with an activity calendar and filters for project, agent
-and model.
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/analytics-dark.png">
-  <img alt="Analytics tab: cost, session and token totals above an activity calendar" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/analytics.png">
-</picture>
-
-**All sessions in one place.** Every session of every supported agent on the
-machine, filterable by agent and searchable by title, repo, branch or id.
-Each card shows turns, tool calls, health grade, cost and tokens in/out at a
-glance.
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/sessions-dark.png">
-  <img alt="Session list with agent filters, search and per-session health, cost and token counts" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/sessions.png">
-</picture>
+## How it compares
 
-**Step-by-step timeline.** Prompts, reasoning, tool calls and their results in
-order, with per-step token counts and cost. Expand any event to see its content, or open
-the raw record.
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/timeline-dark.png">
-  <img alt="Event timeline showing user prompt, thinking, and Grep/Read tool calls" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/timeline.png">
-</picture>
-
-**Token Optimizer.** What the session cost by token class, model and turn, where
-the context went (system prompt vs. tool results vs. replies), which tools ran
-most, and hints for trimming expensive sessions.
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/token-optimizer-dark.png">
-  <img alt="Token Optimizer: estimated cost by token class and model, and a cost-by-turn chart" src="https://raw.githubusercontent.com/kishanmundha/agent-session-inspector/main/docs/screenshots/token-optimizer.png">
-</picture>
-
-**Projects.** Sessions are grouped by the repository they ran in, so work
-started from a subfolder or a git worktree lands in the same project. The
-Projects tab lists each one with its sessions, cost and tokens, and picking a
-project filters Analytics, Usage and Sessions together. Outside a repository,
-the working directory is the project; the dated scratch folders the Codex app
-creates for project-less chats count as one project.
-
-**Activity.** One day at a time: how many sessions were working at once in each
-15-minute slot, the agent time and cost of each session, and the day's split by
-project, model and agent.
-
-**Edits per turn.** A session's Edits tab lists each prompt with the files the
-agent wrote, edited or patched in response, linked to the event in the timeline.
-
-**Skills and MCP tools.** The Analytics tab counts which skills were loaded and
-which MCP servers and tools were called, for the selected range.
-
-> Screenshots use synthetic demo data. To reproduce them locally, see
-> [CONTRIBUTING.md](CONTRIBUTING.md#demo-data).
+[AgentsView](https://github.com/kenn-io/agentsview) and
+[ccusage](https://github.com/ryoppippi/ccusage) read the same transcript files.
+AgentsView is an archive and search tool across all your sessions; ccusage
+prints usage and cost reports in the terminal. This project is for the step
+after that: opening one session to see what the agent was given, what it did
+with it, and what each step cost. It keeps no database and makes no outbound
+requests.
 
 ## How it works
 
@@ -184,6 +272,8 @@ src/lib/providers/
   codex.ts      ~/.codex adapter
   opencode.ts   OpenCode's opencode.db
   hermes.ts     Hermes Agent's state.db
+  gemini.ts     Gemini CLI: replays the session logs under ~/.gemini/tmp
+  cursor.ts     Cursor's state.vscdb, else its ~/.cursor/projects transcripts
   index.ts      registry: listSessions / getSession / listLogs across providers
 ```
 

package/app/bin/agent-session-inspector.mjs

@@ -7,17 +7,30 @@ import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import net from "node:net";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const NAME = "agent-session-inspector";
 const MIN_NODE = [22, 13];
 const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const SERVER = path.join(PKG_DIR, "app", "server.js");
 
+// Report commands print to the terminal instead of starting the server; they
+// live in the bundle scripts/build-cli.mjs writes to <package>/cli/.
+const CLI = path.join(PKG_DIR, "cli", "cli.mjs");
+const COMMANDS = ["usage", "stats", "sessions"];
+
 const HELP = `Usage: ${NAME} [options]
+       ${NAME} <command> [options]
+
+Browse Claude Code, Codex, Copilot, Cursor, Gemini CLI, OpenCode and Hermes
+session transcripts in a local web UI, or print a report in the terminal.
+
+Commands:
+  usage               Tokens and estimated cost by day, model, project or agent
+  stats               Sessions, messages, tool calls and time, by agent
+  sessions            Recent sessions with their cost and health
 
-Browse Claude Code, Codex, Copilot, OpenCode and Hermes session transcripts in a
-local web UI.
+  Run a command with --help for its options.
 
 Options:
   -p, --port <port>   Port to listen on (default: 3000, or the next free one)
@@ -118,7 +131,12 @@ function openBrowser(url) {
     .unref();
 }
 
-const opts = parseArgs(process.argv.slice(2));
+const argv = process.argv.slice(2);
+const command = COMMANDS.includes(argv[0]) ? argv[0] : null;
+if (!command && argv[0] && !argv[0].startsWith("-")) {
+  fail(`unknown command ${argv[0]}\n\n${HELP}`);
+}
+const opts = command ? null : parseArgs(argv);
 
 // npx only warns about package.json "engines", and the app needs node:sqlite.
 const [major, minor] = process.versions.node.split(".").map(Number);
@@ -126,6 +144,21 @@ if (major < MIN_NODE[0] || (major === MIN_NODE[0] && minor < MIN_NODE[1])) {
   fail(`Node.js ${MIN_NODE.join(".")} or newer is required (found ${process.version}).`);
 }
 
+// node:sqlite still announces itself as experimental on Node 22; not useful here.
+const emitWarning = process.emitWarning;
+process.emitWarning = (warning, ...rest) => {
+  if (String(warning).includes("SQLite is an experimental feature")) return;
+  emitWarning.call(process, warning, ...rest);
+};
+
+if (command) {
+  if (!existsSync(CLI)) {
+    fail(`no command bundle found at ${CLI}\nRun \`pnpm cli ${command}\` from a checkout.`);
+  }
+  const { run } = await import(pathToFileURL(CLI).href);
+  process.exit(run(command, argv.slice(1)));
+}
+
 if (!existsSync(SERVER)) {
   fail(`no build found at ${SERVER}\nRun scripts/package-release.sh and use dist/${NAME}/bin/${NAME}.mjs.`);
 }
@@ -142,13 +175,6 @@ process.env.NEXT_TELEMETRY_DISABLED = "1";
 process.env.PORT = String(port);
 process.env.HOSTNAME = opts.host;
 
-// node:sqlite still announces itself as experimental on Node 22; not useful here.
-const emitWarning = process.emitWarning;
-process.emitWarning = (warning, ...rest) => {
-  if (String(warning).includes("SQLite is an experimental feature")) return;
-  emitWarning.call(process, warning, ...rest);
-};
-
 // server.js is CommonJS and starts listening on load.
 createRequire(import.meta.url)(SERVER);
 

package/app/eslint.config.mjs

@@ -12,6 +12,7 @@ const eslintConfig = defineConfig([
     "out/**",
     "build/**",
     "dist/**",
+    "cli/**",
     "next-env.d.ts",
   ]),
 ]);

package/app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-session-inspector",
-  "version": "0.1.4",
-  "description": "Inspect Claude Code, Codex, GitHub Copilot, OpenCode and Hermes agent sessions in a local web UI: timeline, tokens, cost and analytics.",
+  "version": "0.1.5",
+  "description": "See where a coding-agent session's tokens and dollars went: a local inspector for Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode and Hermes sessions, with a step-by-step timeline, per-step cost and analytics.",
   "keywords": [
     "agent",
     "ai-agent",
@@ -12,6 +12,8 @@
     "copilot-chat",
     "vscode",
     "codex",
+    "cursor",
+    "gemini-cli",
     "opencode",
     "hermes",
     "llm",
@@ -37,6 +39,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "eslint",
+    "cli": "node scripts/build-cli.mjs && node bin/agent-session-inspector.mjs",
     "deploy:docker": "./scripts/deploy-docker.sh",
     "package": "./scripts/package-release.sh"
   },
@@ -65,6 +68,7 @@
     "@types/node": "^22.20.4",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "esbuild": "^0.28.2",
     "eslint": "^9",
     "eslint-config-next": "16.3.0",
     "tailwindcss": "^4",