agent-optic 0.2.0 → 0.3.0

package/README.md

@@ -2,14 +2,14 @@
 
 > Reads local assistant history directories and returns structured JSON — sessions, costs, timesheets, work patterns.
 
-Zero-dependency, local-first TypeScript library for reading session data from provider directories such as `~/.claude/`, `~/.codex/`, `~/.cursor/`, and `~/.windsurf/`.
+Zero-dependency, local-first TypeScript library for reading session data from provider directories such as `~/.claude/`, `~/.codex/`, `~/.pi/`, `~/.cursor/`, and `~/.windsurf/`.
 
 > **Security Warning**: Provider home directories contain highly sensitive data — API keys, source code, credentials, and personal information may be present in plaintext session files. This library is designed with privacy as the primary concern. See [SECURITY.md](./SECURITY.md).
 
 ## Try it
 
 ```bash
-bunx agent-optic sessions
+bunx --silent agent-optic sessions
 ```
 
 ## Features
@@ -17,7 +17,8 @@ bunx agent-optic sessions
 - **Zero runtime dependencies**
 - **No network access**
 - **Privacy by default** — strips tool results and thinking blocks
-- **Two-tier session loading** — fast (`history.jsonl`) or detailed (full parse)
+- **Multi-tier session loading** — index, meta, detail, and transcript streaming
+- **Agent-first CLI contract** — stable JSON envelope + JSONL streaming + machine-readable errors
 - **Bun-native** — `Bun.file()`, `Bun.Glob`
 
 ## Install
@@ -69,9 +70,9 @@ Timesheet: 2026-02-10 → 2026-02-14
 ==========================================================================================
 Day   Date        Project                           Hours   Sessions    Prompts
 ------------------------------------------------------------------------------------------
-Mon   2026-02-10  claude-optic                       2.3          4         18
+Mon   2026-02-10  agent-optic                        2.3          4         18
                   my-app                               1.1          2          8
-Tue   2026-02-11  claude-optic                       3.5          6         32
+Tue   2026-02-11  agent-optic                        3.5          6         32
 ------------------------------------------------------------------------------------------
       TOTAL                                            6.9         12         58
 ```
@@ -98,7 +99,8 @@ sonnet-4-5-20250929            45     8.1M      2.3M     6.2M      4.5M       $4
 Export sampled prompts grouped by project as JSON — pipe to an LLM for categorization or analysis.
 
 ```bash
-bun examples/prompt-history.ts --from 2026-01-01 | claude "categorize these prompts by intent"
+# Pipe to your preferred LLM CLI
+bun examples/prompt-history.ts --from 2026-01-01 | your-llm-cli "categorize these prompts by intent"
 ```
 
 ### Session Digest
@@ -106,7 +108,8 @@ bun examples/prompt-history.ts --from 2026-01-01 | claude "categorize these prom
 Compact session summaries as JSON — first prompt, branch, model, token counts, cost, duration.
 
 ```bash
-bun examples/session-digest.ts --days 7 | claude "which sessions were the most productive?"
+# Pipe to your preferred LLM CLI
+bun examples/session-digest.ts --days 7 | your-llm-cli "which sessions were the most productive?"
 ```
 
 ### Work Patterns
@@ -114,7 +117,8 @@ bun examples/session-digest.ts --days 7 | claude "which sessions were the most p
 Aggregated work pattern metrics as JSON — hour distribution, late-night/weekend counts, longest and most expensive sessions.
 
 ```bash
-bun examples/work-patterns.ts | claude "analyze my work patterns and suggest improvements"
+# Pipe to your preferred LLM CLI
+bun examples/work-patterns.ts | your-llm-cli "analyze my work patterns and suggest improvements"
 ```
 
 ### Commit Tracker
@@ -168,14 +172,14 @@ const ch = createHistory({ provider: "claude" });
 // List today's sessions (fast — reads only history.jsonl)
 const sessions = await ch.sessions.list();
 
-// List with metadata (slower — peeks session files for branch/model/tokens)
+// List with metadata (slower — reads session files for branch/model/tokens)
 const withMeta = await ch.sessions.listWithMeta();
 
-// Get full session detail
-const detail = await ch.sessions.detail(sessionId, projectPath);
+// Get full session detail (projectPath is optional for codex/openai)
+const detail = await ch.sessions.detail(sessionId);
 
-// Stream transcript entries
-for await (const entry of ch.sessions.transcript(sessionId, projectPath)) {
+// Stream transcript entries (projectPath is optional for codex/openai)
+for await (const entry of ch.sessions.transcript(sessionId)) {
   console.log(entry.message?.role, entry.timestamp);
 }
 
@@ -192,31 +196,35 @@ const cost = estimateCost(withMeta[0]); // USD
 
 ## API
 
+The public package surface is intentionally small: `createHistory`, core types, privacy profiles, pricing helpers, and a few date/project helpers. Low-level readers, parsers, and JSONL utilities remain internal.
+
 ### `createHistory(config?)`
 
 ```typescript
 const ch = createHistory({
-  provider: "claude",                // "claude" | "codex" | "openai" | "cursor" | "windsurf"
+  provider: "claude",                // "claude" | "codex" | "openai" | "pi" | "cursor" | "windsurf"
   providerDir: "~/.claude",          // default: provider-specific home directory
   privacy: "local",                  // "local" | "shareable" | "strict" | Partial<PrivacyConfig>
-  cache: true,                       // default: true
 });
 ```
 
 `openai` is currently an alias of Codex-format local history and defaults to `~/.codex`.
 
-`createClaudeHistory()` is still exported for backward compatibility and behaves like `createHistory({ provider: "claude" })`.
+`pi` reads from `~/.pi/agent/sessions/` — Pi has no `history.jsonl`, so sessions are discovered by scanning the directory tree. Pi sessions include `totalCost` from accumulated message costs.
+
 
 ### Sessions
 
 | Method | Speed | Reads | Returns |
 |--------|-------|-------|---------|
 | `sessions.list(filter?)` | Fast | `history.jsonl` only | `SessionInfo[]` |
-| `sessions.listWithMeta(filter?)` | Medium | + peeks session files | `SessionMeta[]` |
-| `sessions.detail(id, project)` | Slow | Full session parse | `SessionDetail` |
-| `sessions.transcript(id, project)` | Streaming | Full session file | `AsyncGenerator<TranscriptEntry>` |
+| `sessions.listWithMeta(filter?)` | Medium | + reads session files for metadata | `SessionMeta[]` |
+| `sessions.detail(id, project?)` | Slow | Full session parse | `SessionDetail` |
+| `sessions.transcript(id, project?)` | Streaming | Full session file | `AsyncGenerator<TranscriptEntry>` |
 | `sessions.count(filter?)` | Fast | `history.jsonl` only | `number` |
 
+For `codex`, `openai`, and `pi`, `project` is optional because project/cwd is resolved from session metadata.
+
 ### Other Data
 
 ```typescript
@@ -294,33 +302,38 @@ const ch = createHistory({
 
 ```bash
 # Agent-friendly list (JSONL stream)
-bunx agent-optic sessions --provider codex --format jsonl
+bunx --silent agent-optic sessions --provider codex --format jsonl
 
 # Detail for one session
-bunx agent-optic detail 019c9aea-484d-7200-87fd-07a545276ac4 --provider openai
+bunx --silent agent-optic detail 019c9aea-484d-7200-87fd-07a545276ac4 --provider openai
 
 # Transcript stream (limit + selected fields)
-bunx agent-optic transcript 019c9aea-484d-7200-87fd-07a545276ac4 --provider openai --format jsonl --limit 50 --fields timestamp,message
+bunx --silent agent-optic transcript 019c9aea-484d-7200-87fd-07a545276ac4 --provider openai --format jsonl --limit 50 --fields timestamp,message
 
 # Tool usage report
-bunx agent-optic tool-usage --provider codex --from 2026-02-01 --to 2026-02-26
+bunx --silent agent-optic tool-usage --provider codex --from 2026-02-01 --to 2026-02-26
 
 # Daily summary
-bunx agent-optic daily --date 2026-02-09
+bunx --silent agent-optic daily --date 2026-02-09
 
 # Raw output without envelope
-bunx agent-optic sessions --provider claude --date 2026-02-09 --raw
+bunx --silent agent-optic sessions --provider claude --date 2026-02-09 --raw
 ```
 
 `--format json` returns a stable envelope (`schemaVersion`, `command`, `provider`, `generatedAt`, `data`) by default.
 Use `--raw` for data-only output and `--format jsonl` for one JSON object per line.
 
+Common agent commands:
+- `sessions [session-id?]` list sessions (or filter to one ID)
+- `detail <session-id>` full parsed session
+- `transcript <session-id>` transcript stream/output
+- `tool-usage` aggregated tool analytics
+
 ## Architecture
 
 ```
 src/
-  agent-optic.ts      # Main factory: createHistory()
-  claude-optic.ts     # Backward-compatible Claude aliases
+  agent-optic.ts      # Main factory and runtime API
   pricing.ts            # Model pricing data and cost estimation
   types/                # Type definitions (one file per domain)
   readers/              # File readers (history, session, tasks, plans, projects, stats)

package/examples/annotate-commits.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+/**
+ * annotate-commits.ts — Write AI cost data as git notes on each commit in .ai-usage.jsonl
+ *
+ * Usage:
+ *   bun examples/annotate-commits.ts [path-to-repo]   # default: cwd
+ *   bun examples/annotate-commits.ts --push           # also push notes to origin
+ *
+ * After running, git log --show-notes displays AI cost inline:
+ *
+ *   commit ad7ac31...
+ *       Fix messageCount: also exclude toolUseResult carriers
+ *
+ *   Notes:
+ *       AI: $2.71 | out: 21K | cache: 5.8M | sessions: 9 | claude-sonnet-4-6
+ */
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+
+interface UsageRecord {
+	commit: string;
+	tokens: { input: number; output: number; cache_read: number; cache_write: number };
+	cost_usd: number;
+	models: string[];
+	session_ids: string[];
+}
+
+function fmt(n: number): string {
+	if (n >= 1_000_000_000) return (n / 1_000_000_000).toFixed(1) + "B";
+	if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
+	if (n >= 1_000) return (n / 1_000).toFixed(0) + "K";
+	return String(n);
+}
+
+// ── CLI args ──────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const push = args.includes("--push");
+const repoArg = args.find((a) => !a.startsWith("--"));
+const repoPath = repoArg ? repoArg : process.cwd();
+const trackingPath = join(repoPath, ".ai-usage.jsonl");
+
+if (!existsSync(trackingPath)) {
+	console.error(`No .ai-usage.jsonl found in ${repoPath}`);
+	console.error("Run: bun examples/commit-tracker.ts init");
+	process.exit(1);
+}
+
+// ── Load records ──────────────────────────────────────────────────────
+
+const records: UsageRecord[] = [];
+for (const line of (await Bun.file(trackingPath).text()).trim().split("\n")) {
+	if (!line.trim()) continue;
+	try { records.push(JSON.parse(line) as UsageRecord); } catch {}
+}
+
+if (records.length === 0) {
+	console.log("No records found.");
+	process.exit(0);
+}
+
+// ── Annotate ──────────────────────────────────────────────────────────
+
+let annotated = 0;
+let skipped = 0;
+
+for (const r of records) {
+	const model = r.models[0] ?? "unknown";
+
+	const note = [
+		`AI: $${r.cost_usd.toFixed(2)}`,
+		`out: ${fmt(r.tokens.output)}`,
+		`cache: ${fmt(r.tokens.cache_read)}`,
+		`sessions: ${r.session_ids.length}`,
+		model,
+	].join(" | ");
+
+	const proc = Bun.spawn(["git", "notes", "add", "-f", "-m", note, r.commit], {
+		cwd: repoPath,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+
+	if (exitCode === 0) {
+		annotated++;
+	} else {
+		const err = await new Response(proc.stderr).text();
+		// "bad object" means the commit hash doesn't exist in this repo — skip silently
+		if (!err.includes("bad object") && !err.includes("not a valid")) {
+			console.warn(`  skipped ${r.commit}: ${err.trim()}`);
+		}
+		skipped++;
+	}
+}
+
+console.log(`${annotated} commits annotated, ${skipped} skipped (not in this repo)`);
+console.log(`\nView with: git log --show-notes`);
+
+// ── Push notes ────────────────────────────────────────────────────────
+
+if (push) {
+	console.log("\nPushing notes to origin...");
+	const proc = Bun.spawn(["git", "push", "origin", "refs/notes/commits"], {
+		cwd: repoPath,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	const out = await new Response(proc.stdout).text();
+	const err = await new Response(proc.stderr).text();
+	if (exitCode === 0) {
+		console.log("Notes pushed. Others can fetch with:");
+		console.log("  git fetch origin refs/notes/commits:refs/notes/commits");
+	} else {
+		console.error("Push failed:", err.trim() || out.trim());
+	}
+}