agent-optic 0.2.0

package/examples/timesheet.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env bun
+/**
+ * timesheet.ts — Generate a weekly timesheet from Claude session timestamps.
+ *
+ * Usage:
+ *   bun examples/timesheet.ts [--from YYYY-MM-DD] [--to YYYY-MM-DD]
+ *
+ * Groups sessions by day and project, uses gap-capped hour estimation,
+ * and outputs a table suitable for time tracking or invoicing.
+ */
+
+import { createClaudeHistory, today, toLocalDate, type SessionMeta } from "../src/index.js";
+
+const args = process.argv.slice(2);
+function getArg(name: string): string | undefined {
+	const idx = args.indexOf(name);
+	return idx !== -1 ? args[idx + 1] : undefined;
+}
+
+const now = Date.now();
+const dayOfWeek = new Date(now).getDay();
+const mondayOffset = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+
+const from = getArg("--from") ?? toLocalDate(now - mondayOffset * 86400000);
+const to = getArg("--to") ?? today();
+
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+async function main() {
+	const ch = createClaudeHistory();
+	const sessions = await ch.sessions.listWithMeta({ from, to });
+
+	const byDateProject = new Map<string, Map<string, SessionMeta[]>>();
+
+	for (const s of sessions) {
+		const date = toLocalDate(s.timeRange.start);
+		const project = s.projectName || "unknown";
+
+		let projectMap = byDateProject.get(date);
+		if (!projectMap) {
+			projectMap = new Map();
+			byDateProject.set(date, projectMap);
+		}
+
+		const list = projectMap.get(project) ?? [];
+		list.push(s);
+		projectMap.set(project, list);
+	}
+
+	const dates = [...byDateProject.keys()].sort();
+
+	console.log(`Timesheet: ${from} → ${to}`);
+	console.log("=".repeat(90));
+	console.log(
+		"Day".padEnd(6),
+		"Date".padEnd(12),
+		"Project".padEnd(30),
+		"Hours".padStart(8),
+		"Sessions".padStart(10),
+		"Prompts".padStart(10),
+	);
+	console.log("-".repeat(90));
+
+	let totalHours = 0;
+	let totalSessions = 0;
+	let totalPrompts = 0;
+
+	for (const date of dates) {
+		const projectMap = byDateProject.get(date)!;
+		const dayName = DAYS[new Date(date + "T12:00:00").getDay()];
+		let first = true;
+
+		const projects = [...projectMap.entries()].map(([project, sess]) => ({
+			project,
+			sessions: sess,
+			hours: ch.aggregate.estimateHours(sess),
+			prompts: sess.reduce((s, x) => s + x.prompts.length, 0),
+		}));
+		projects.sort((a, b) => b.hours - a.hours);
+
+		for (const p of projects) {
+			console.log(
+				(first ? dayName : "").padEnd(6),
+				(first ? date : "").padEnd(12),
+				p.project.slice(0, 29).padEnd(30),
+				p.hours.toFixed(1).padStart(8),
+				String(p.sessions.length).padStart(10),
+				String(p.prompts).padStart(10),
+			);
+			totalHours += p.hours;
+			totalSessions += p.sessions.length;
+			totalPrompts += p.prompts;
+			first = false;
+		}
+	}
+
+	console.log("-".repeat(90));
+	console.log(
+		"".padEnd(6),
+		"TOTAL".padEnd(12),
+		"".padEnd(30),
+		totalHours.toFixed(1).padStart(8),
+		String(totalSessions).padStart(10),
+		String(totalPrompts).padStart(10),
+	);
+
+	const allByProject = new Map<string, SessionMeta[]>();
+	for (const s of sessions) {
+		const project = s.projectName || "unknown";
+		const list = allByProject.get(project) ?? [];
+		list.push(s);
+		allByProject.set(project, list);
+	}
+
+	console.log(`\nSummary by Project`);
+	console.log("-".repeat(50));
+
+	const projectTotals = [...allByProject.entries()]
+		.map(([project, sess]) => ({ project, hours: ch.aggregate.estimateHours(sess) }))
+		.sort((a, b) => b.hours - a.hours);
+
+	for (const p of projectTotals) {
+		console.log(`  ${p.project.padEnd(30)} ${p.hours.toFixed(1).padStart(8)}h`);
+	}
+}
+
+main().catch(console.error);

package/examples/work-patterns.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env bun
+/**
+ * work-patterns.ts — Export aggregated work pattern metrics as JSON.
+ *
+ * Usage:
+ *   bun examples/work-patterns.ts [--from YYYY-MM-DD] [--to YYYY-MM-DD]
+ *
+ * Outputs hour distribution, late-night/weekend counts, longest and most
+ * expensive sessions — all as JSON for an LLM to interpret.
+ */
+
+import { createClaudeHistory, estimateCost, toLocalDate, type SessionMeta } from "../src/index.js";
+
+const args = process.argv.slice(2);
+function getArg(name: string, fallback: string): string {
+	const idx = args.indexOf(name);
+	return idx !== -1 ? (args[idx + 1] ?? fallback) : fallback;
+}
+
+const from = getArg("--from", toLocalDate(Date.now() - 30 * 86400000));
+const to = getArg("--to", toLocalDate(Date.now()));
+
+function durationMinutes(s: SessionMeta): number {
+	return (s.timeRange.end - s.timeRange.start) / 60000;
+}
+
+async function main() {
+	const ch = createClaudeHistory();
+	const sessions = await ch.sessions.listWithMeta({ from, to });
+
+	if (sessions.length === 0) {
+		console.log(JSON.stringify({ period: { from, to }, totalSessions: 0 }, null, 2));
+		return;
+	}
+
+	const totalCost = sessions.reduce((s, x) => s + estimateCost(x), 0);
+	const totalHours = ch.aggregate.estimateHours(sessions);
+	const totalTokens = sessions.reduce(
+		(s, x) => s + x.totalInputTokens + x.totalOutputTokens + x.cacheCreationInputTokens + x.cacheReadInputTokens,
+		0,
+	);
+
+	const hourBuckets = new Array(24).fill(0);
+	for (const s of sessions) {
+		hourBuckets[new Date(s.timeRange.start).getHours()]++;
+	}
+
+	const lateNightCount = sessions.filter((s) => {
+		const h = new Date(s.timeRange.start).getHours();
+		return h >= 22 || h < 5;
+	}).length;
+
+	const weekendCount = sessions.filter((s) => {
+		const day = new Date(s.timeRange.start).getDay();
+		return day === 0 || day === 6;
+	}).length;
+
+	const byDate = new Map<string, number>();
+	for (const s of sessions) {
+		const date = toLocalDate(s.timeRange.start);
+		byDate.set(date, (byDate.get(date) ?? 0) + 1);
+	}
+	const busiestDay = [...byDate.entries()].sort((a, b) => b[1] - a[1])[0];
+
+	const peakHour = hourBuckets.indexOf(Math.max(...hourBuckets));
+
+	const byDuration = [...sessions].sort((a, b) => durationMinutes(b) - durationMinutes(a));
+	const byCost = [...sessions].sort((a, b) => estimateCost(b) - estimateCost(a));
+
+	const longestSessions = byDuration.slice(0, 5).map((s) => ({
+		date: toLocalDate(s.timeRange.start),
+		project: s.projectName,
+		durationMinutes: Math.round(durationMinutes(s)),
+		prompts: s.prompts.length,
+	}));
+
+	const mostExpensiveSessions = byCost.slice(0, 5).map((s) => ({
+		date: toLocalDate(s.timeRange.start),
+		project: s.projectName,
+		model: s.model ?? null,
+		estimatedCostUsd: +estimateCost(s).toFixed(4),
+	}));
+
+	// Per-project breakdown (top 10)
+	const projectMap = new Map<string, SessionMeta[]>();
+	for (const s of sessions) {
+		const arr = projectMap.get(s.projectName) ?? [];
+		arr.push(s);
+		projectMap.set(s.projectName, arr);
+	}
+	const byProject = [...projectMap.entries()]
+		.sort((a, b) => b[1].length - a[1].length)
+		.slice(0, 10)
+		.map(([project, projectSessions]) => ({
+			project,
+			sessions: projectSessions.length,
+			estimatedHours: +ch.aggregate.estimateHours(projectSessions).toFixed(1),
+			estimatedCostUsd: +projectSessions.reduce((s, x) => s + estimateCost(x), 0).toFixed(2),
+		}));
+
+	console.log(
+		JSON.stringify(
+			{
+				period: { from, to },
+				totalSessions: sessions.length,
+				totalEstimatedHours: +totalHours.toFixed(1),
+				totalTokens,
+				totalEstimatedCostUsd: +totalCost.toFixed(2),
+				peakHour,
+				hourDistribution: Object.fromEntries(hourBuckets.map((count, hour) => [hour, count]).filter(([, c]) => c > 0)),
+				lateNightSessions: lateNightCount,
+				weekendSessions: weekendCount,
+				busiestDay: busiestDay ? { date: busiestDay[0], sessions: busiestDay[1] } : null,
+				byProject,
+				longestSessions,
+				mostExpensiveSessions,
+			},
+			null,
+			2,
+		),
+	);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "agent-optic",
+	"version": "0.2.0",
+	"description": "Zero-dependency, local-first framework for reading AI assistant session data from provider home directories",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"bin": {
+		"agent-optic": "./src/cli/index.ts",
+		"claude-optic": "./src/cli/index.ts"
+	},
+	"files": ["src", "examples"],
+	"keywords": [
+		"ai",
+		"assistant",
+		"claude",
+		"codex",
+		"cursor",
+		"windsurf",
+		"session-history",
+		"developer-tools",
+		"productivity"
+	],
+	"author": "Kristoffer",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Kristoffer88/agent-optic"
+	},
+	"scripts": {
+		"knip": "knip"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.2.2",
+		"knip": "^5.83.1"
+	}
+}

package/src/agent-optic.ts

@@ -0,0 +1,325 @@
+import type { PrivacyConfig, PrivacyProfile } from "./types/privacy.js";
+import type { SessionInfo, SessionMeta, SessionDetail } from "./types/session.js";
+import type { TranscriptEntry } from "./types/transcript.js";
+import type { TaskInfo, TodoItem } from "./types/task.js";
+import type { PlanInfo } from "./types/plan.js";
+import type { ProjectInfo, ProjectMemory } from "./types/project.js";
+import type { StatsCache } from "./types/stats.js";
+import type { Provider } from "./types/provider.js";
+import type {
+	DailySummary,
+	ProjectSummary,
+	ToolUsageReport,
+	DateFilter,
+	SessionListFilter,
+} from "./types/aggregations.js";
+
+import { providerPaths } from "./utils/paths.js";
+import { resolveDateRange } from "./utils/dates.js";
+import { canonicalProvider } from "./utils/providers.js";
+import { resolvePrivacyConfig } from "./privacy/config.js";
+import { setPricing, type ModelPricing } from "./pricing.js";
+
+import { readHistory } from "./readers/history-reader.js";
+import { peekSession, streamTranscript } from "./readers/session-reader.js";
+import { readTasks, readTodos } from "./readers/task-reader.js";
+import { readPlans } from "./readers/plan-reader.js";
+import { readProjects, readProjectMemory } from "./readers/project-reader.js";
+import { readStats } from "./readers/stats-reader.js";
+import { readSkills, readSkillContent } from "./readers/skill-reader.js";
+
+import { parseSessionDetail } from "./parsers/session-detail.js";
+
+import { buildDailySummary, buildDailyRange } from "./aggregations/daily.js";
+import { buildProjectSummaries } from "./aggregations/project.js";
+import { buildToolUsageReport } from "./aggregations/tools.js";
+import { estimateHours } from "./aggregations/time.js";
+
+export interface HistoryConfig {
+	/** Assistant provider. Defaults to "claude". */
+	provider?: Provider;
+	/** Path to provider data directory. Defaults to provider-specific home folder. */
+	providerDir?: string;
+	/** Privacy profile name or partial config. Defaults to "local" */
+	privacy?: PrivacyProfile | Partial<PrivacyConfig>;
+	/** Enable caching of repeated reads. Defaults to true */
+	cache?: boolean;
+	/** Override or extend model pricing (USD per million tokens). Merges with built-in defaults. */
+	pricing?: Record<string, ModelPricing>;
+}
+
+export interface History {
+	sessions: {
+		/** Fast: reads only history.jsonl */
+		list(filter?: SessionListFilter): Promise<SessionInfo[]>;
+		/** Medium: also peeks session files for branch/model/tokens */
+		listWithMeta(filter?: SessionListFilter): Promise<SessionMeta[]>;
+		/** Full: parses entire session JSONL */
+		detail(sessionId: string, projectPath?: string): Promise<SessionDetail>;
+		/** Streaming: yields transcript entries one at a time */
+		transcript(sessionId: string, projectPath?: string): AsyncGenerator<TranscriptEntry>;
+		/** Count sessions matching filter */
+		count(filter?: SessionListFilter): Promise<number>;
+	};
+	projects: {
+		list(): Promise<ProjectInfo[]>;
+		memory(projectPath: string): Promise<ProjectMemory | null>;
+	};
+	tasks: {
+		list(filter: DateFilter): Promise<TaskInfo[]>;
+	};
+	todos: {
+		list(filter: DateFilter): Promise<TodoItem[]>;
+	};
+	plans: {
+		list(filter: DateFilter): Promise<PlanInfo[]>;
+	};
+	skills: {
+		list(): Promise<string[]>;
+		read(name: string): Promise<string>;
+	};
+	stats: {
+		get(): Promise<StatsCache | null>;
+	};
+	aggregate: {
+		daily(date: string): Promise<DailySummary>;
+		dailyRange(from: string, to: string): Promise<DailySummary[]>;
+		byProject(filter?: SessionListFilter): Promise<ProjectSummary[]>;
+		toolUsage(filter?: SessionListFilter): Promise<ToolUsageReport>;
+		estimateHours(sessions: SessionInfo[]): number;
+	};
+}
+
+/** Create a provider-aware History instance for reading session data. */
+export function createHistory(config?: HistoryConfig): History {
+	const requestedProvider = config?.provider ?? "claude";
+	const provider = canonicalProvider(requestedProvider);
+	const paths = providerPaths({
+		provider: requestedProvider,
+		providerDir: config?.providerDir,
+	});
+
+	if (config?.pricing) {
+		setPricing(config.pricing);
+	}
+
+	const privacy: PrivacyConfig =
+		typeof config?.privacy === "string"
+			? resolvePrivacyConfig(config.privacy)
+			: resolvePrivacyConfig(undefined, config?.privacy);
+
+	const dailyPaths = {
+		historyFile: paths.historyFile,
+		projectsDir: paths.projectsDir,
+		sessionsDir: paths.sessionsDir,
+		tasksDir: paths.tasksDir,
+		plansDir: paths.plansDir,
+		todosDir: paths.todosDir,
+	};
+
+	return {
+		sessions: {
+			async list(filter?: SessionListFilter): Promise<SessionInfo[]> {
+				const { from, to } = resolveDateRange(filter);
+				let sessions = await readHistory(paths.historyFile, from, to, privacy, {
+					provider,
+					sessionsDir: paths.sessionsDir,
+				});
+
+				if (filter?.project) {
+					const f = filter.project.toLowerCase();
+					sessions = sessions.filter((s) => s.projectName.toLowerCase().includes(f));
+				}
+
+				return sessions;
+			},
+
+			async listWithMeta(filter?: SessionListFilter): Promise<SessionMeta[]> {
+				const { from, to } = resolveDateRange(filter);
+				let sessions = await readHistory(paths.historyFile, from, to, privacy, {
+					provider,
+					sessionsDir: paths.sessionsDir,
+				});
+
+				if (filter?.project) {
+					const f = filter.project.toLowerCase();
+					sessions = sessions.filter((s) => s.projectName.toLowerCase().includes(f));
+				}
+
+				return Promise.all(
+					sessions.map((s) =>
+						peekSession(provider, s, {
+							projectsDir: paths.projectsDir,
+							sessionsDir: paths.sessionsDir,
+						}, privacy),
+					),
+				);
+			},
+
+			async detail(sessionId: string, projectPath?: string): Promise<SessionDetail> {
+				let session: SessionInfo | undefined;
+
+				if (!projectPath || provider === "codex") {
+					const all = await readHistory(
+						paths.historyFile,
+						"2000-01-01",
+						"2099-12-31",
+						privacy,
+						{
+							provider,
+							sessionsDir: paths.sessionsDir,
+						},
+					);
+					session = all.find((s) => s.sessionId === sessionId);
+				}
+
+				if (!session) {
+					const effectiveProjectPath = projectPath ?? `(unknown)/${sessionId}`;
+					session = {
+						sessionId,
+						project: effectiveProjectPath,
+						projectName:
+							effectiveProjectPath.split("/").pop() || effectiveProjectPath,
+						prompts: [],
+						promptTimestamps: [],
+						timeRange: { start: 0, end: 0 },
+					};
+				}
+
+				return parseSessionDetail(provider, session, {
+					projectsDir: paths.projectsDir,
+					sessionsDir: paths.sessionsDir,
+				}, privacy);
+			},
+
+			async *transcript(
+				sessionId: string,
+				projectPath?: string,
+			): AsyncGenerator<TranscriptEntry> {
+				yield* streamTranscript(
+					provider,
+					sessionId,
+					projectPath ?? `(unknown)/${sessionId}`,
+					{
+						projectsDir: paths.projectsDir,
+						sessionsDir: paths.sessionsDir,
+					},
+					privacy,
+				);
+			},
+
+			async count(filter?: SessionListFilter): Promise<number> {
+				const { from, to } = resolveDateRange(filter);
+				const sessions = await readHistory(paths.historyFile, from, to, privacy, {
+					provider,
+					sessionsDir: paths.sessionsDir,
+				});
+				if (filter?.project) {
+					const f = filter.project.toLowerCase();
+					return sessions.filter((s) => s.projectName.toLowerCase().includes(f)).length;
+				}
+				return sessions.length;
+			},
+		},
+
+		projects: {
+			async list(): Promise<ProjectInfo[]> {
+				return readProjects(paths.projectsDir, privacy);
+			},
+
+			async memory(projectPath: string): Promise<ProjectMemory | null> {
+				return readProjectMemory(projectPath, paths.projectsDir);
+			},
+		},
+
+		tasks: {
+			async list(filter: DateFilter): Promise<TaskInfo[]> {
+				const { from, to } = resolveDateRange(filter);
+				return readTasks(paths.tasksDir, from, to);
+			},
+		},
+
+		todos: {
+			async list(filter: DateFilter): Promise<TodoItem[]> {
+				const { from, to } = resolveDateRange(filter);
+				return readTodos(paths.todosDir, from, to);
+			},
+		},
+
+		plans: {
+			async list(filter: DateFilter): Promise<PlanInfo[]> {
+				const { from, to } = resolveDateRange(filter);
+				return readPlans(paths.plansDir, from, to);
+			},
+		},
+
+		skills: {
+			async list(): Promise<string[]> {
+				return readSkills(paths.skillsDir);
+			},
+
+			async read(name: string): Promise<string> {
+				return readSkillContent(paths.skillsDir, name);
+			},
+		},
+
+		stats: {
+			async get(): Promise<StatsCache | null> {
+				return readStats(paths.statsCache);
+			},
+		},
+
+		aggregate: {
+			async daily(date: string): Promise<DailySummary> {
+				return buildDailySummary(provider, date, dailyPaths, privacy);
+			},
+
+			async dailyRange(from: string, to: string): Promise<DailySummary[]> {
+				return buildDailyRange(provider, from, to, dailyPaths, privacy);
+			},
+
+			async byProject(filter?: SessionListFilter): Promise<ProjectSummary[]> {
+				return buildProjectSummaries(
+					provider,
+					filter ?? {},
+					paths.historyFile,
+					{ projectsDir: paths.projectsDir, sessionsDir: paths.sessionsDir },
+					privacy,
+				);
+			},
+
+			async toolUsage(filter?: SessionListFilter): Promise<ToolUsageReport> {
+				return buildToolUsageReport(
+					provider,
+					filter ?? {},
+					paths.historyFile,
+					{ projectsDir: paths.projectsDir, sessionsDir: paths.sessionsDir },
+					privacy,
+				);
+			},
+
+			estimateHours(sessions: SessionInfo[]): number {
+				return estimateHours(sessions);
+			},
+		},
+	};
+}
+
+/** Backward-compatible Claude-specific config. */
+export interface ClaudeHistoryConfig extends Omit<HistoryConfig, "provider" | "providerDir"> {
+	/** Path to ~/.claude directory. Defaults to ~/.claude */
+	claudeDir?: string;
+}
+
+/** Backward-compatible Claude-specific alias. */
+export type ClaudeHistory = History;
+
+/** Create a ClaudeHistory instance for reading session data. */
+export function createClaudeHistory(config?: ClaudeHistoryConfig): ClaudeHistory {
+	const { claudeDir, ...rest } = config ?? {};
+	return createHistory({
+		...rest,
+		provider: "claude",
+		providerDir: claudeDir,
+	});
+}

package/src/aggregations/daily.ts

@@ -0,0 +1,90 @@
+import type { PrivacyConfig } from "../types/privacy.js";
+import type { Provider } from "../types/provider.js";
+import type { DailySummary } from "../types/aggregations.js";
+import { readHistory } from "../readers/history-reader.js";
+import { readTasks, readTodos } from "../readers/task-reader.js";
+import { readPlans } from "../readers/plan-reader.js";
+import { readProjectMemories } from "../readers/project-reader.js";
+import { parseSessions } from "../parsers/session-detail.js";
+
+interface DailyPaths {
+	historyFile: string;
+	projectsDir: string;
+	sessionsDir: string;
+	tasksDir: string;
+	plansDir: string;
+	todosDir: string;
+}
+
+/** Build a complete DailySummary for a single date. */
+export async function buildDailySummary(
+	provider: Provider,
+	date: string,
+	paths: DailyPaths,
+	privacy: PrivacyConfig,
+): Promise<DailySummary> {
+	// Read history (fast)
+	const sessionInfos = await readHistory(paths.historyFile, date, date, privacy, {
+		provider,
+		sessionsDir: paths.sessionsDir,
+	});
+
+	// Parse sessions into detailed + short
+	const { detailed, short } = await parseSessions(
+		provider,
+		sessionInfos,
+		{ projectsDir: paths.projectsDir, sessionsDir: paths.sessionsDir },
+		privacy,
+	);
+
+	// Read tasks, plans, todos in parallel
+	const [tasks, plans, todos] = await Promise.all([
+		readTasks(paths.tasksDir, date, date),
+		readPlans(paths.plansDir, date, date),
+		readTodos(paths.todosDir, date, date),
+	]);
+
+	// Read project memories
+	const projectPaths = [...new Set(sessionInfos.map((s) => s.project))];
+	const projectMemory = await readProjectMemories(projectPaths, paths.projectsDir);
+
+	const projects = [...new Set(sessionInfos.map((s) => s.projectName))];
+	const totalPrompts = sessionInfos.reduce((sum, s) => sum + s.prompts.length, 0);
+
+	return {
+		date,
+		sessions: detailed,
+		shortSessions: short,
+		tasks,
+		plans,
+		todos,
+		totalPrompts,
+		totalSessions: sessionInfos.length,
+		projects,
+		projectMemory,
+	};
+}
+
+/** Build DailySummary objects for a date range. */
+export async function buildDailyRange(
+	provider: Provider,
+	from: string,
+	to: string,
+	paths: DailyPaths,
+	privacy: PrivacyConfig,
+): Promise<DailySummary[]> {
+	const summaries: DailySummary[] = [];
+	const start = new Date(from);
+	const end = new Date(to);
+
+	for (let d = new Date(start); d <= end; d.setDate(d.getDate() + 1)) {
+		const dateStr = d.toISOString().slice(0, 10);
+		const summary = await buildDailySummary(provider, dateStr, paths, privacy);
+		// Only include days that have activity
+		if (summary.totalSessions > 0 || summary.tasks.length > 0 || summary.plans.length > 0) {
+			summaries.push(summary);
+		}
+	}
+
+	return summaries;
+}