melagiri · melagiri · Mar 28, 2026 · Mar 28, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -91,8 +91,9 @@ code-insights status                   # Show sync statistics
 code-insights open                     # Open dashboard in browser (no server start)
 code-insights dashboard                # Start server + open dashboard (auto-syncs first)
 code-insights dashboard --no-sync      # Start server + open dashboard without syncing
-code-insights install-hook             # Auto-sync on session end
-code-insights uninstall-hook           # Remove auto-sync hook
+code-insights install-hook             # Auto-sync + auto-analysis on session end
+code-insights install-hook --sync-only # Install sync hook only (no analysis)
+code-insights uninstall-hook           # Remove all Code Insights hooks
 code-insights config                   # Show current configuration
 code-insights config llm               # Configure LLM provider interactively
 code-insights reset --confirm          # Delete all local data
@@ -104,6 +105,12 @@ code-insights telemetry                # Show telemetry status
 code-insights telemetry disable        # Opt out of anonymous telemetry
 code-insights telemetry enable         # Opt back in
 
+# Insights — session analysis
+code-insights insights <session_id>              # Analyze using configured LLM
+code-insights insights <session_id> --native     # Analyze using claude -p (no API key needed)
+code-insights insights --hook --native -q        # Hook mode (reads stdin, used by SessionEnd hook)
+code-insights insights check                     # Check for unanalyzed sessions (last 7 days)
+
 # Stats — terminal analytics
 code-insights stats                    # Dashboard overview (last 7 days)
 code-insights stats cost               # Cost breakdown by project and model
@@ -125,7 +132,7 @@ code-insights stats patterns           # Cross-session patterns summary
 
 - **Runtime**: Node.js (ES2022, ES Modules)
 - **CLI Framework**: Commander.js
-- **Database**: SQLite (better-sqlite3) — WAL mode, local at `~/.code-insights/data.db`, Schema V7
+- **Database**: SQLite (better-sqlite3) — WAL mode, local at `~/.code-insights/data.db`, Schema V7 (V8 planned)
 - **Dashboard**: Vite + React 19 SPA
 - **Server**: Hono
 - **UI**: Tailwind CSS 4 + shadcn/ui (New York), Lucide icons

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -19,8 +19,9 @@ Source tool session files -> Provider (discover + parse) -> SQLite -> Dashboard
 code-insights/
 ├── cli/                    # Node.js CLI (Commander.js, SQLite, providers)
 │   └── src/
-│       ├── commands/       # CLI commands (init, sync, status, stats, dashboard, config)
+│       ├── commands/       # CLI commands (init, sync, status, stats, dashboard, config, insights)
 │       ├── commands/stats/ # Stats command suite (4-layer architecture)
+│       ├── analysis/       # Prompt builders, response parsers, normalizers, runner interface (shared by CLI + server)
 │       ├── providers/      # Source tool providers (claude-code, cursor, codex, copilot, copilot-cli)
 │       ├── parser/         # JSONL parsing, title generation
 │       ├── db/             # SQLite schema, migrations, queries
@@ -43,7 +44,7 @@ code-insights/
 ├── server/                 # Hono API server
 │   └── src/
 │       ├── routes/         # REST API endpoints
-│       ├── llm/            # LLM client: session analysis, reflect synthesis, export, normalization, cost tracking; analysis prompts use provider-native caching for the shared conversation prefix
+│       ├── llm/            # LLM client, reflect synthesis, export, cost tracking; prompt builders re-exported from cli/src/analysis/
 │       └── index.ts        # Server entry point
 ├── docs/                   # Product docs, plans, roadmap
 │   └── plans/              # Design plans (pending implementation only)
@@ -54,7 +55,7 @@ code-insights/
 
 ### CLI Directory Detail (`/cli/src/`)
 
-- `commands/` — CLI commands (init, sync, status, dashboard, reset, install-hook, config, reflect, telemetry)
+- `commands/` — CLI commands (init, sync, status, dashboard, reset, install-hook, config, reflect, telemetry, insights)
 - `commands/stats/` — Stats command suite (4-layer architecture):
   - `data/types.ts` — `StatsDataSource` interface, `SessionRow`, error classes
   - `data/source.ts` — Data source factory

diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
@@ -21,7 +21,9 @@ Code Insights provides:
 1. **Automated extraction** — Parses session files from multiple AI coding tools and structures the data
 2. **Smart session titles** — Auto-generates meaningful titles from session content
 3. **Session classification** — Categorizes sessions (deep focus, bug hunt, feature build, etc.)
-4. **LLM-powered analysis** — Multi-provider insight generation (OpenAI, Anthropic, Gemini, Ollama) with your own API key
+4. **LLM-powered analysis** — Two analysis paths:
+   - **Native (zero-config):** Claude Code users get automatic analysis via `SessionEnd` hook using their existing Claude subscription. No API key needed. Install with `code-insights install-hook`.
+   - **On-demand:** Configure any LLM provider (OpenAI, Anthropic, Gemini, Ollama) with your own API key for manual analysis from the dashboard or CLI.
 5. **Visual dashboard** — Local web interface with charts, timelines, and filters at `http://localhost:7890`
 6. **CLI analytics** — Terminal stats via `code-insights stats` and subcommands
 

diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -227,6 +227,9 @@ This roadmap outlines the development phases for Code Insights. Timelines are fl
 | 4.3.0 | 10 | AI Fluency Score card V3, PQ dimension scores, conservative palette, tool logos | ✅ Done |
 | 4.4.0 | 11 | Global search & command palette, advanced filtering, reliability hardening | ✅ Done |
 | 4.5.0 | — | Parallel LLM analysis, search ESCAPE fix, dynamic review specialists | ✅ Done |
+| 4.6.1 | — | User profile on share cards, GitHub avatar CORS fix | ✅ Done |
+| 4.7.0 | — | Ollama auto-detection, LlmNudgeBanner for unconfigured LLM | ✅ Done |
+| 4.8.0 | 12 | Native analysis via Claude Code hooks, unified `insights` command, runner interface | Planned |
 
 ---
 
@@ -254,7 +257,24 @@ This roadmap outlines the development phases for Code Insights. Timelines are fl
 
 ---
 
-## What's Next
+## Phase 12: Native Analysis via Claude Code Hooks (Planned)
+
+**Goal:** Zero-config session analysis for Claude Code users — no API key needed. Uses the Claude subscription they already have.
+
+**Plan:** [`docs/plans/2026-03-28-native-analysis-hooks.md`](plans/2026-03-28-native-analysis-hooks.md)
+
+### Milestones
+
+- [ ] **12.1 Prompt Module Migration** (#238) — Move prompt builders from server to CLI for shared access
+- [ ] **12.2 Runner Interface** (#239) — AnalysisRunner abstraction with ClaudeNativeRunner + ProviderRunner
+- [ ] **12.3 `insights` CLI Command** (#240) — Unified command with `--native` and `--hook` modes, V8 schema migration
+- [ ] **12.4 Hook Installation** (#241) — `install-hook` adds SessionEnd analysis hook alongside existing sync hook
+- [ ] **12.5 Backfill Recovery** (#242) — `insights check` for unanalyzed sessions (7-day lookback)
+- [ ] **12.6 Dashboard + Docs** (#243) — Updated LlmNudgeBanner, analysis provenance, documentation
+
+---
+
+## What's Next (After Phase 12)
 
 - Progress tracking: weekly snapshots, friction-to-pattern affinity map, transformation detection, `driver`-based filtering for user growth signals
 - Test suite expansion (Vitest)