sidekick-shared

Shared data access library for Sidekick Agent Hub.

Types, parsers, providers, readers, formatters, aggregation, search, reporting, credentials, and quota for AI agent session monitoring. Used by both the VS Code extension and the CLI dashboard.

Installation

npm install sidekick-shared

API Overview

| Module | Description | |--------|-------------| | Types | Session events, OpenCode/Codex format types, persistence schemas (tasks, decisions, notes, plans, historical data) | | Paths | Config directory resolution, project data paths, workspace encoding | | Readers | Read tasks, decisions, notes, history, handoff, and plans from ~/.config/sidekick/ | | Providers | Session provider abstraction with Claude Code, OpenCode, and Codex implementations; auto-detection via filesystem | | Parsers | JSONL event parsing, OpenCode/Codex format normalization, subagent scanning, session path resolution, debug log parsing | | Watchers | Live session file watching with event bridging | | Formatters | Tool summary, noise classification, session dump (text/markdown/JSON), event highlighting | | Search | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date) | | Aggregation | Event aggregation, frequency tracking, activity heatmaps, pattern extraction | | Report | Self-contained HTML session report generation | | Credentials | Claude Max OAuth credential reading from ~/.claude/.credentials.json | | Quota | Claude Max subscription quota fetching (5-hour and 7-day windows) |

Usage Examples

Detect the active session provider

import { detectProvider } from 'sidekick-shared';

const provider = await detectProvider('/path/to/project');
if (provider) {
  console.log(`Active provider: ${provider.id}`);
  const sessions = await provider.listSessions();
}

Read persisted tasks

import { readTasks, getProjectSlug } from 'sidekick-shared';

const slug = getProjectSlug('/path/to/project');
const tasks = readTasks({ projectSlug: slug });
console.log(`Found ${tasks.length} tasks`);

Fetch subscription quota

import { fetchQuota, readClaudeMaxCredentials } from 'sidekick-shared';

const creds = readClaudeMaxCredentials();
if (creds) {
  const quota = await fetchQuota(creds.accessToken);
  console.log(`5-hour utilization: ${quota.fiveHour.percentUsed}%`);
}

Building

npm run build

Compiles TypeScript to dist/ via tsc.

Testing

npm test

Uses Vitest. Run npm run test:watch for watch mode.

See Also

• Sidekick for Max — VS Code extension
• Sidekick CLI — Terminal dashboard (npm install -g sidekick-agent-hub)

License

MIT