claude-sessions 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# claude-sessions
+
+Read Claude Code session data (sessions, projects, tasks, teams, costs) without running lm-assist.
+
+## Install
+
+```bash
+npm install claude-sessions
+```
+
+## Quick Start
+
+```typescript
+import {
+  createSessionReader,
+  createSessionParser,
+  createSessionCache,
+  createProjectsService,
+  createTasksService,
+  createAgentTeamsService,
+  createCostCalculator,
+} from 'claude-sessions';
+
+// List all projects and sessions
+const reader = createSessionReader();
+const projects = reader.listProjects();
+const sessions = reader.listSessions('/path/to/project');
+
+// Parse a session with full detail
+const parser = createSessionParser();
+const session = await parser.parseSession('session-uuid', '/path/to/project');
+console.log(session.userPrompts);
+console.log(session.toolUses);
+console.log(session.totalCostUsd);
+
+// Get conversation in simplified format
+const convo = await parser.getConversation({
+  sessionId: 'session-uuid',
+  toolDetail: 'summary',
+  includeThinking: true,
+});
+
+// LMDB-backed cache for fast repeated reads
+const cache = createSessionCache();
+const data = await cache.getSessionData('/path/to/session.jsonl');
+const allSessions = cache.getAllSessionsFromCache();
+cache.close();
+
+// Projects with git info and cost
+const projService = createProjectsService({ sessionCache: cache });
+const projs = projService.listProjects();
+
+// Tasks
+const tasks = createTasksService();
+const lists = await tasks.listTaskLists();
+const taskList = await tasks.getTaskList('list-id');
+
+// Teams
+const teams = createAgentTeamsService();
+const teamList = teams.listTeams();
+
+// Cost calculation
+const calc = createCostCalculator();
+const cost = calc.calculateCost(
+  { inputTokens: 100000, outputTokens: 5000, cacheCreationInputTokens: 50000, cacheReadInputTokens: 200000 },
+  'claude-sonnet-4'
+);
+console.log(calc.formatCost(cost.totalCost));
+```
+
+## API Overview
+
+### SessionReader
+Low-level JSONL file discovery and reading from `~/.claude/projects/`.
+
+- `listProjects()` — List all projects
+- `listSessions(cwd?)` — List sessions for a project
+- `listSessionsWithDetails(cwd?)` — Sessions with model/cost/status
+- `readSessionLines(sessionId, cwd?)` — Raw JSONL lines
+- `listSubagentFiles(sessionId?, cwd?)` — Subagent file metadata
+
+### SessionParser
+Parse JSONL sessions into structured data. No server dependencies.
+
+- `parseSession(sessionId, cwd?)` — Full session parse
+- `getConversation(options)` — Simplified conversation format
+
+### SessionCache
+LMDB-backed cache for fast repeated reads with incremental parsing.
+
+- `getSessionData(filePath)` — Cached session data (async)
+- `getSessionDataSync(filePath)` — Synchronous variant
+- `getRawMessages(filePath)` — Raw parsed messages
+- `getAllSessionsFromCache()` — All cached sessions
+- `getProjectSessionsFromCache(projectPath)` — Project sessions from cache
+- `getPerProjectCosts()` — Per-project cost totals
+- `startWatching()` — File watcher (requires chokidar)
+- `close()` — Shut down LMDB
+
+### ProjectsService
+Project discovery with git info and cost metadata.
+
+- `listProjects(options?)` — All projects with metadata
+- `listProjectSessions(projectPath, options?)` — Sessions with enriched data
+- `getGitInfo(projectPath)` — Git branch, remotes, commit
+
+### TasksService
+Read Claude Code task files from `~/.claude/tasks/`.
+
+- `listTaskLists()` — All task lists
+- `getTaskList(listId)` — Tasks in a list
+- `getReadyTasks(listId)` — Unblocked tasks
+- `getAllTasksFlat()` — All tasks across all lists
+
+### AgentTeamsService
+Read team configs from `~/.claude/teams/`.
+
+- `listTeams()` — All teams
+- `getTeam(teamName)` — Team config
+
+### CostCalculator
+Token cost calculation with tiered pricing.
+
+- `calculateCost(usage, model?)` — Calculate cost from token usage
+- `getPricing(model)` — Get pricing for a model
+- `formatCost(cost)` — Format as `$X.XX`
+
+### Path Utilities
+- `legacyEncodeProjectPath(path)` — Dash-encoded path
+- `encodePath(path)` / `decodePath(encoded)` — Base64 path encoding
+- `getProjectsDir()` — `~/.claude/projects/`
+- `extractProjectPath(storagePath)` — Extract project path from storage path
+
+## Optional Dependencies
+
+- **chokidar** — File watching for live cache updates. Install with `npm install chokidar` if you need `SessionCache.startWatching()`.
+
+## License
+
+MIT

package/data/model-pricing.json

@@ -0,0 +1,113 @@
+[
+  {
+    "modelPattern": "claude-opus-4-6",
+    "displayName": "Claude Opus 4.6",
+    "inputPricePerMillion": 5.0,
+    "outputPricePerMillion": 25.0,
+    "cache5mWritePricePerMillion": 6.25,
+    "cache1hWritePricePerMillion": 10.0,
+    "cacheReadPricePerMillion": 0.5,
+    "inputPricePerMillionAbove200k": 10.0,
+    "outputPricePerMillionAbove200k": 37.5,
+    "cache5mWritePricePerMillionAbove200k": 12.5,
+    "cache1hWritePricePerMillionAbove200k": 20.0,
+    "cacheReadPricePerMillionAbove200k": 1.0,
+    "tieredThreshold": 200000
+  },
+  {
+    "modelPattern": "claude-opus-4-5",
+    "displayName": "Claude Opus 4.5",
+    "inputPricePerMillion": 5.0,
+    "outputPricePerMillion": 25.0,
+    "cache5mWritePricePerMillion": 6.25,
+    "cache1hWritePricePerMillion": 10.0,
+    "cacheReadPricePerMillion": 0.5
+  },
+  {
+    "modelPattern": "claude-sonnet-4-6",
+    "displayName": "Claude Sonnet 4.6",
+    "inputPricePerMillion": 3.0,
+    "outputPricePerMillion": 15.0,
+    "cache5mWritePricePerMillion": 3.75,
+    "cache1hWritePricePerMillion": 6.0,
+    "cacheReadPricePerMillion": 0.3,
+    "inputPricePerMillionAbove200k": 6.0,
+    "outputPricePerMillionAbove200k": 22.5,
+    "cache5mWritePricePerMillionAbove200k": 7.5,
+    "cache1hWritePricePerMillionAbove200k": 12.0,
+    "cacheReadPricePerMillionAbove200k": 0.6,
+    "tieredThreshold": 200000
+  },
+  {
+    "modelPattern": "claude-sonnet-4-5",
+    "displayName": "Claude Sonnet 4.5",
+    "inputPricePerMillion": 3.0,
+    "outputPricePerMillion": 15.0,
+    "cache5mWritePricePerMillion": 3.75,
+    "cache1hWritePricePerMillion": 6.0,
+    "cacheReadPricePerMillion": 0.3,
+    "inputPricePerMillionAbove200k": 6.0,
+    "outputPricePerMillionAbove200k": 22.5,
+    "cache5mWritePricePerMillionAbove200k": 7.5,
+    "cache1hWritePricePerMillionAbove200k": 12.0,
+    "cacheReadPricePerMillionAbove200k": 0.6,
+    "tieredThreshold": 200000
+  },
+  {
+    "modelPattern": "claude-sonnet-4",
+    "displayName": "Claude Sonnet 4",
+    "inputPricePerMillion": 3.0,
+    "outputPricePerMillion": 15.0,
+    "cache5mWritePricePerMillion": 3.75,
+    "cache1hWritePricePerMillion": 6.0,
+    "cacheReadPricePerMillion": 0.3,
+    "inputPricePerMillionAbove200k": 6.0,
+    "outputPricePerMillionAbove200k": 22.5,
+    "cache5mWritePricePerMillionAbove200k": 7.5,
+    "cache1hWritePricePerMillionAbove200k": 12.0,
+    "cacheReadPricePerMillionAbove200k": 0.6,
+    "tieredThreshold": 200000
+  },
+  {
+    "modelPattern": "claude-haiku-4-5",
+    "displayName": "Claude Haiku 4.5",
+    "inputPricePerMillion": 1.0,
+    "outputPricePerMillion": 5.0,
+    "cache5mWritePricePerMillion": 1.25,
+    "cache1hWritePricePerMillion": 2.0,
+    "cacheReadPricePerMillion": 0.1
+  },
+  {
+    "modelPattern": "claude-3-5-sonnet",
+    "displayName": "Claude 3.5 Sonnet",
+    "inputPricePerMillion": 3.0,
+    "outputPricePerMillion": 15.0,
+    "cache5mWritePricePerMillion": 3.75,
+    "cache1hWritePricePerMillion": 6.0,
+    "cacheReadPricePerMillion": 0.3,
+    "inputPricePerMillionAbove200k": 6.0,
+    "outputPricePerMillionAbove200k": 30.0,
+    "cache5mWritePricePerMillionAbove200k": 7.5,
+    "cache1hWritePricePerMillionAbove200k": 12.0,
+    "cacheReadPricePerMillionAbove200k": 0.6,
+    "tieredThreshold": 200000
+  },
+  {
+    "modelPattern": "claude-3-5-haiku",
+    "displayName": "Claude 3.5 Haiku",
+    "inputPricePerMillion": 0.8,
+    "outputPricePerMillion": 4.0,
+    "cache5mWritePricePerMillion": 1.0,
+    "cache1hWritePricePerMillion": 1.6,
+    "cacheReadPricePerMillion": 0.08
+  },
+  {
+    "modelPattern": "claude-3-opus",
+    "displayName": "Claude 3 Opus",
+    "inputPricePerMillion": 15.0,
+    "outputPricePerMillion": 75.0,
+    "cache5mWritePricePerMillion": 18.75,
+    "cache1hWritePricePerMillion": 30.0,
+    "cacheReadPricePerMillion": 1.5
+  }
+]

package/dist/cost-calculator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cost Calculator
+ * Calculate token costs based on model pricing.
+ *
+ * Pricing is loaded from data/model-pricing.json with a hardcoded
+ * fallback. Supports tiered pricing (above-200k token threshold) per
+ * the LiteLLM/ccusage convention. An optional lazy LiteLLM fetch provides
+ * pricing for unknown models.
+ */
+import type { TokenUsage, ModelPricing, CostEstimate, UsageSummary } from './types';
+/**
+ * Default model pricing — loaded from data/model-pricing.json,
+ * falling back to hardcoded values if the file is missing.
+ */
+export declare const DEFAULT_MODEL_PRICING: ModelPricing[];
+/**
+ * Cost Calculator class
+ */
+export declare class CostCalculator {
+    private pricing;
+    private defaultModel;
+    constructor(options?: {
+        customPricing?: ModelPricing[];
+        defaultModel?: string;
+    });
+    getPricing(model: string): ModelPricing;
+    private calculateTieredTokenCost;
+    calculateCost(usage: TokenUsage, model?: string, options?: {
+        cumulative?: boolean;
+    }): CostEstimate;
+    estimatePromptCost(promptChars: number, expectedOutputChars: number, contextChars: number, model?: string): CostEstimate;
+    aggregateCosts(estimates: CostEstimate[]): CostEstimate;
+    formatCost(cost: number): string;
+    formatTokens(tokens: number): string;
+    getAllPricing(): ModelPricing[];
+    addPricing(pricing: ModelPricing): void;
+    setDefaultModel(model: string): void;
+    createUsageSummary(data: Array<{
+        sessionId: string;
+        date: Date;
+        model: string;
+        tokens: TokenUsage;
+    }>): UsageSummary;
+}
+export declare function createCostCalculator(options?: {
+    customPricing?: ModelPricing[];
+    defaultModel?: string;
+}): CostCalculator;
+//# sourceMappingURL=cost-calculator.d.ts.map

package/dist/cost-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-calculator.d.ts","sourceRoot":"","sources":["../src/cost-calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA0GpF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAAY,EACJ,CAAC;AAwF7C;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,YAAY,CAAS;gBAEjB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAK/E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IA0BvC,OAAO,CAAC,wBAAwB;IAchC,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,YAAY;IA4DlG,kBAAkB,CAChB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,EAC3B,YAAY,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,YAAY;IAiBf,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,YAAY;IA2CvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAUhC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IASpC,aAAa,IAAI,YAAY,EAAE;IAI/B,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIvC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIpC,kBAAkB,CAChB,IAAI,EAAE,KAAK,CAAC;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,IAAI,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,UAAU,CAAC;KACpB,CAAC,GACD,YAAY;CAmDhB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,CAEjB"}