@klars/agentobs 0.2.0 → 0.2.2

package/README.md

@@ -36,16 +36,31 @@ account, no cloud, no telemetry.
 ```bash
 npm install -g @klars/agentobs
 agentobs init
+agentobs import
 ```
 
-`init` prints a hook configuration block. Paste it into `~/.claude/settings.json`
-(or a project's `.claude/settings.json`), then:
+`import` reads Claude Code's own session transcripts from `~/.claude/projects/`
+and backfills everything you have already done — no configuration, no hooks.
+Then:
 
 ```bash
 agentobs dashboard
 ```
 
-Run Claude Code as usual. Tool calls appear in the dashboard within seconds.
+That is the fastest path to real data, and the one to try first.
+
+### Live capture (optional)
+
+`import` is after-the-fact. To record calls **as they happen** — and to let
+guardrails actually block them — add the hook configuration that
+`agentobs init` prints to `~/.claude/settings.json`, then restart Claude Code.
+
+> **If hooks record nothing:** this has been observed on at least one Windows
+> install, where Claude Code did not invoke the configured command at all — a
+> plain two-line `.cmd` file also never fired, so it is not specific to
+> AgentObs. Check by running any tool and then `agentobs stats --today`. If it
+> stays at zero, keep using `agentobs import`, which needs no hooks; only
+> guardrail *blocking* depends on them.
 
 ---
 
@@ -85,6 +100,7 @@ Everything lives in `~/.agentobs/`. Uninstalling is `rm -rf ~/.agentobs`.
 
 ```
 agentobs init                        Set up ~/.agentobs and print the hook config
+agentobs import [--days n] [--all]   Import Claude Code transcripts (no hooks needed)
 agentobs dashboard [--port] [--host] Serve the dashboard (default 127.0.0.1:4300)
 agentobs stats [--today] [--since]   Print totals in the terminal
 agentobs run -- <command...>         Observe any command (coarse detail)
@@ -148,22 +164,37 @@ Two deliberate behaviours worth knowing:
 
 ## Agent support
 
-| Agent           | How                        | Detail                                            |
-| --------------- | -------------------------- | ------------------------------------------------- |
-| **Claude Code** | Native hooks               | **Rich** — every tool call, plus policy enforcement |
-| Any CLI agent   | `agentobs run -- <cmd>`    | **Coarse** — duration and exit code only          |
-| Custom / in-house | `agentobs watch <file>`  | **Rich**, if it writes JSONL                      |
+| Agent | How | Detail | Needs setup? |
+| --- | --- | --- | --- |
+| **Claude Code** | `agentobs import` | **Rich** — every tool call, tokens, cost | **No** |
+| **Claude Code** | Native hooks | **Rich**, live, and can *block* calls | Yes — hook config |
+| Any CLI agent | `agentobs run -- <cmd>` | **Coarse** — duration and exit code only | No |
+| Custom / in-house | `agentobs watch <file>` | **Rich**, if it writes JSONL | No |
+
+`import` and hooks read the same underlying data. The difference is timing:
+hooks see a call *before* it runs, which is what makes blocking possible;
+`import` reads the transcript afterwards. If you only want observability,
+`import` is enough and needs no configuration.
 
 The dashboard labels coarse sessions as `coarse` rather than implying detail it
-does not have.
+does not have, and `agentobs stats` explains why a coarse-only range shows zero
+tool calls.
 
 ### A note on cost accuracy
 
-Claude Code's `PostToolUse` hook payload carries **no token or cost fields**.
-AgentObs therefore reads token usage from the session transcript at
-`SessionEnd`, which makes **session-level cost accurate** but leaves
-**per-tool-call cost blank** for hook-sourced data. It does not divide a total
-across calls to manufacture a number.
+Claude Code's `PostToolUse` hook payload carries **no token or cost fields**,
+so token usage comes from the session transcript — at `SessionEnd` for hooks,
+or directly via `agentobs import`. That makes **session-level cost accurate**
+while leaving **per-tool-call cost blank**: usage is reported per assistant
+message, not per tool call, and dividing a total across calls would be a
+manufactured number.
+
+**Cache tokens dominate a long session.** A cached conversation replays its
+whole context on every turn, so `cache_read` can reach hundreds of millions of
+tokens in a single session. AgentObs tracks cache reads (billed at 0.1x input)
+and cache writes (1.25x) separately from fresh tokens, and `agentobs import`
+prints the four lines separately — a single unexplained total looks like a bug
+when the cache line legitimately dwarfs everything else.
 
 Model prices live in `~/.agentobs/pricing.json` and are yours to edit. A model
 missing from that file shows cost as `—`, never `$0.00`.

package/dist/adapters/claude-transcript.js

@@ -135,14 +135,19 @@ export async function importTranscript(db, file) {
         const message = (row.message ?? {});
         const usage = message.usage;
         if (usage && typeof usage === 'object') {
-            // Only genuinely fresh input tokens go in tokensIn. Cache writes and
-            // reads are tracked separately because they bill at different rates,
-            // and because a cache read replays the whole context every turn - the
-            // headline token count must not include the same tokens hundreds of
-            // times.
-            result.tokensIn += usage.input_tokens ?? 0;
+            // Fresh input = uncached input + cache writes. A cache write is real
+            // new content being sent for the first time (just stored for reuse), so
+            // excluding it made "tokens in" absurd: 24K in against 4.6M out, when
+            // real agent usage is heavily input-weighted. It is still tracked
+            // separately for costing, since it bills at 1.25x.
+            //
+            // Cache *reads* stay out of this total: they replay the entire context
+            // on every turn, so counting them would report the same tokens hundreds
+            // of times (2.4 billion across three sessions).
+            const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+            result.tokensIn += (usage.input_tokens ?? 0) + cacheWrite;
             result.tokensOut += usage.output_tokens ?? 0;
-            result.cacheWriteTokens += usage.cache_creation_input_tokens ?? 0;
+            result.cacheWriteTokens += cacheWrite;
             // cache_read is the whole conversation context replayed on every single
             // message, so it re-counts the same tokens on each turn - summing it
             // reported 413 million tokens for one session. It is tracked separately
@@ -186,6 +191,8 @@ export async function importTranscript(db, file) {
     }
     if (!sessionStarted)
         return result;
+    // tokensIn already contains the cache-write tokens, so they are costed once
+    // at the base rate here and only topped up by the extra 0.25x premium.
     const baseCost = computeCost(result.model, result.tokensIn, result.tokensOut);
     const readCost = computeCost(result.model, result.cacheReadTokens, 0);
     const writeCost = computeCost(result.model, result.cacheWriteTokens, 0);
@@ -194,7 +201,7 @@ export async function importTranscript(db, file) {
             ? null
             : baseCost +
                 (readCost ?? 0) * CACHE_READ_RATE +
-                (writeCost ?? 0) * CACHE_WRITE_RATE;
+                (writeCost ?? 0) * (CACHE_WRITE_RATE - 1);
     // Session totals come from the transcript's own usage blocks, which are
     // authoritative - the per-call rows have no tokens to sum.
     db.prepare(`UPDATE sessions

package/dist/server/public/app.js

@@ -191,10 +191,10 @@ function renderTools(rows) {
   body.replaceChildren();
   if (rows.length === 0) {
     const tr = document.createElement('tr');
-    const msg =
-      state.summary && state.summary.coarse_sessions > 0
-        ? 'Coarse sessions record no tool calls — connect the Claude Code hook for per-tool detail.'
-        : 'No tool calls recorded yet.';
+    const msg =
+      state.summary && state.summary.coarse_sessions > 0
+        ? 'Coarse sessions record no tool calls — connect the Claude Code hook for per-tool detail.'
+        : 'No tool calls recorded yet.';
     tr.append(Object.assign(cell(msg, 'empty'), { colSpan: 5 }));
     body.append(tr);
     return;
@@ -630,6 +630,16 @@ function renderDelta(el, current, previous, { goodWhenUp = true } = {}) {
     return;
   }
   const change = ((current - previous) / previous) * 100;
+  // A tiny previous period produces a huge, meaningless percentage - "+2300%"
+  // says nothing except that yesterday was nearly empty. Cap the display so
+  // the chip stays informative rather than theatrical.
+  if (Math.abs(change) > 999) {
+    el.className = `delta ${change > 0 === goodWhenUp ? 'delta-good' : 'delta-bad'}`;
+    el.textContent = `${change > 0 ? '▲' : '▼'} vs ${previous}`;
+    el.title = `Previous period had only ${previous}; a percentage would be misleading`;
+    el.removeAttribute('hidden');
+    return;
+  }
   if (!Number.isFinite(change) || Math.abs(change) < 0.5) {
     // Below half a percent is noise; a chip there implies a signal that
     // isn't real.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klars/agentobs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Observability and control layer for AI coding agents - see every tool call, token, and dollar your agents spend, and stop them before they do something risky.",
   "license": "MIT",
   "author": "Klars AI",