Instruction file imported from rajbos/ai-engineering-fluency (.github/instructions/cli.instructions.md). Copyright stays with the author.

CLI — Architecture & Integration Guide

The CLI (cli/) is a standalone command-line tool that shares the session discovery and data access classes from the repo-root src/ folder but has its own aggregation pipeline. It is built with TypeScript and bundled via cli/esbuild.js into cli/dist/cli.js.

Key Files

• cli/src/helpers.ts: Shared helper functions — session discovery, file processing, stats aggregation. Imports all data access classes from src/.
• cli/src/commands/: One file per sub-command (stats, usage, environmental, fluency, diagnostics).
• cli/esbuild.js: Build script. Copies JSON data files from src/ to a temp location before bundling, then removes them.
• cli/tsconfig.json: paths alias points to ../src/*.

Developer Workflow

cd cli
npm install
npm run build            # development build
npm run build:production # minified release build

Or from the repo root:

./build.ps1 -Project cli

Adding a New Editor / Data Source

When adding support for a new editor or data source, wire it into both the shared src/ folder (see .github/instructions/vscode-extension.instructions.md) and this CLI.

Adapter architecture (issue #654): The CLI shares the adapter classes from src/adapters/ via buildAdapterRegistry and createDataAccessInstances in src/adapters/adapterRegistry.ts. Currently 11 adapters are registered: OpenCode, Crush, Continue, ClaudeCode, ClaudeDesktop, VisualStudio, MistralVibe, GeminiCli, CopilotChat, CopilotCli, JetBrains. The Copilot and JetBrains adapters own discovery but their handles() returns false, so processSessionFile() falls through to the existing per-format helpers (JSONL/JSON parsing) for those files. Order matters — register Copilot/JetBrains adapters last.

CLI Files to Update

Integration Points in cli/src/helpers.ts

Data-access instantiation is centralised in src/adapters/adapterRegistry.ts via createDataAccessInstances. To add a new editor, update only that file for instantiation. Then in cli/src/helpers.ts add only the routing/processing hooks:

1. statSessionFile() — add guard routing virtual paths to the real DB file (before the generic fs.promises.stat() fallthrough)
2. getEditorSourceFromPath() — add a path pattern check before the generic '/code/' or 'vscode' fallthrough, returning a stable lowercase identifier (e.g. 'neweditor')
3. processSessionFile() — add a guard block calling getTokens(), countInteractions(), getModelUsage() from the data access class and returning a SessionData object
4. calculateUsageAnalysisStats() deps — pass the new instance so analyzeSessionUsage() can route to it

Checklist

• src/adapters/adapterRegistry.ts — concrete import, createDataAccessInstances entry, buildAdapterRegistry entry
• cli/src/helpers.ts — detection, stat routing, processSessionFile block, usageAnalysis deps
• cli/src/commands/stats.ts — getEditorDisplayName() entry
• cli/README.md — "Data Sources" section updated
• docs/vscode-extension/README.md — add the new editor to the "Supported editors shown in the chart" list in the Chart View section
• npm run build passes (from cli/)
• CLI stats command shows the new editor in the session list
• Token counts are non-zero and plausible