Learn and Vibe

Analytics and insights for vibe-based learning sessions

This repository contains the Learn and Vibe project, starting with Claude Code Chat Analytics.

📁 Repository Structure

learn_and_vibe/                    ← You are here (repository root)
├── chat-analytics/                ← The Next.js application
│   ├── app/                       ← Next.js pages and API routes
│   ├── lib/                       ← Core business logic
│   ├── components/                ← React components
│   └── docs/                      ← Technical documentation
├── PRD.md                         ← Product requirements
├── sdk_docs.md                    ← Claude SDK reference
└── README.md                      ← This file

⚠️ Important: The actual application is in the chat-analytics/ directory. Unless otherwise noted, all commands in this documentation assume you're working from chat-analytics/.

Claude Code Chat Analytics

Transform your Claude Code chat histories into actionable insights

A Next.js 15 progressive web application that automatically discovers, analyzes, and extracts value from your Claude Code conversations. Built with TypeScript and modern React patterns.

🎯 What This Does

Claude Code Chat Analytics automatically:

Discovers all your Claude Code projects from ~/.claude/projects/
Analyzes conversation patterns using Claude's own AI via Agent SDK
Extracts reusable code snippets and identifies time sinks
Provides actionable recommendations to improve your workflow
Stores everything locally in SQLite for instant access

Think of it as retrospective analytics for your AI-assisted development.

✨ Key Features

🔍 Automatic Discovery

Scans ~/.claude/projects/ to find all chat histories
Extracts actual project paths from session metadata
Organizes sessions chronologically with modification dates

🧠 AI-Powered Analysis

Uses Claude Agent SDK to analyze conversations
Detects repetitive patterns and time sinks
Identifies "quick wins" - solutions that worked efficiently
Extracts code snippets with language detection and tagging

📊 Insightful Metrics

Time spent estimates per project
Turn counts and session durations
Tool usage statistics (Read, Write, Edit, Bash, etc.)
Session timelines with date range filtering

💾 Local Storage

SQLite database with WAL mode for concurrency
Persistent analysis cache to avoid re-analysis
Project starring/bookmarking
Full-text storage of original sessions

🎨 Modern UI

shadcn/ui components with Radix primitives
Tailwind CSS for responsive design
Server and Client Components architecture
Date range picker for targeted analysis

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Next.js 15 App                          │
│                    (App Router + RSC)                       │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   File Scanner  │  │  JSONL Parser   │  │  Claude Agent   │
│   (scanner.ts)  │  │ (jsonl-parser)  │  │  (analyzer.ts)  │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              ▼
                    ┌─────────────────┐
                    │  SQLite DB      │
                    │  (better-sqlite3)│
                    └─────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
    [projects]          [sessions]          [analyses]
    [patterns]          [code_snippets]     [settings]

🚀 Quick Start

Prerequisites

Required:

Node.js 18+ (tested with Node 24.4.0)
Claude Code CLI (must be installed and authenticated)

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Authenticate (opens Claude Console):

claude

You'll need:

Active billing at console.anthropic.com
macOS 10.15+, Ubuntu 20.04+, or Windows 10+ (with WSL)

📚 Full Claude Code installation guide

Installation

📍 Starting location: Repository root (learn_and_vibe/)

Navigate to the application directory:
```
cd chat-analytics
```

Install dependencies:

# From: learn_and_vibe/chat-analytics/
npm install

Configure environment (optional):

# From: learn_and_vibe/chat-analytics/
cp .env.example .env.local

Available options in .env.local:

# Claude model to use for analysis (default: claude-sonnet-4-5-20250929)
CLAUDE_MODEL=claude-sonnet-4-5-20250929

Run the development server:

# From: learn_and_vibe/chat-analytics/
npm run dev

Open your browser: Navigate to http://localhost:3000

💡 Tip: All subsequent commands in this guide assume you're in the chat-analytics/ directory unless explicitly stated otherwise.

🚀 Quick Launch with `cca` Alias (Optional)

For instant access from anywhere, create a global cca command that launches the app.

⚠️ Run this from chat-analytics/ directory:

# 1. Navigate to the app directory (if not already there)
cd learn_and_vibe/chat-analytics

# 2. Verify you're in the right place
pwd
# ✅ Should end with: /learn_and_vibe/chat-analytics

# 3. Create the alias
# For Zsh (macOS default):
echo "alias cca=\"$(pwd)/launch-cca.sh\"" >> ~/.zshrc
source ~/.zshrc

# For Bash (Linux/older macOS):
echo "alias cca=\"$(pwd)/launch-cca.sh\"" >> ~/.bashrc
source ~/.bashrc

# 4. Verify it worked
type cca
# Should show: cca is an alias for /full/path/to/learn_and_vibe/chat-analytics/launch-cca.sh

What this does:

Cleans up old processes on port 3000
Starts the server in the background
Monitors output for "Ready in" message
Opens browser only when server is actually ready (no more waiting!)
Shows server logs in foreground (Ctrl+C to stop)

Now launch from anywhere:

cca  # Cleans up old processes, opens browser, starts server

To stop the server:

# Press Ctrl+C in the terminal, or:
lsof -ti:3000 | xargs kill -9

📖 See chat-analytics/CCA_SETUP.md for detailed setup instructions and troubleshooting.

💻 Installing as a Desktop App (PWA)

You can install this as a Progressive Web App on your laptop for a native app-like experience!

Quick Install

Start the server:
```
cd chat-analytics
npm run dev
```
Open in Chrome/Edge/Brave: Navigate to http://localhost:3000
Install:
- Look for the install icon (⊕) in the address bar
- Or click Menu → "Install Claude Code Chat Analytics..."
- Click "Install" in the confirmation dialog
Done! The app will:
- Open in its own window (no browser UI)
- Be added to your Applications folder
- Appear in Spotlight search (macOS) or Start Menu (Windows)
- Launch like a native app

⚠️ Important: The PWA creates a desktop shortcut, but you still need to run npm run dev each time before using the app (e.g., after restarting your computer). The installed app connects to your local server.

💡 Solutions:

Auto-start: See Auto-Start Solutions for LaunchAgent (macOS), Task Scheduler (Windows), or systemd (Linux) setup to automatically start the server on boot

⚠️ Note: This app cannot be deployed to cloud platforms (Vercel, Netlify, etc.) because it requires local file access to ~/.claude/projects/ and your local Claude CLI. It must run on your machine.

See PWA Installation Guide for detailed instructions, troubleshooting, and platform-specific steps.

📖 Usage Guide

1. First-Time Setup

When you first open the app:

Click "Scan Projects" on the dashboard
Wait for the scan to complete (usually 2-10 seconds)
All discovered projects will appear as cards

2. Analyzing a Project

Select a project by clicking its card
Choose a date range using the date picker (defaults to last 7 days)
Click "Analyze Sessions"
Wait for analysis to complete (30s - 2min depending on session count)
View results in tabs:
- Overview: Summary and metrics
- Patterns: Repetitive prompts, time sinks, quick wins
- Code Snippets: Extracted code with language/tags
- Recommendations: Actionable suggestions

3. Starring Projects

Click the star icon ⭐ on any project card to bookmark it. Starred projects appear at the top of your dashboard.

4. Settings

Navigate to /settings to:

Check Claude CLI status
View CLI installation path
See authentication status
Configure analysis preferences (future)

🗄️ Database Schema

The app uses SQLite with the following tables:

Table	Purpose
`projects`	Discovered Claude Code projects
`sessions`	Individual chat sessions (JSONL files)
`analyses`	Analysis results with summaries
`patterns`	Detected patterns (repetitive, time_sink, quick_win)
`code_snippets`	Extracted code with metadata
`settings`	User preferences and configuration

See DATABASE.md for full schema details.

🛠️ Tech Stack

Core

Next.js 15 - App Router, Server Components, Server Actions
React 19 - Latest React features
TypeScript 5 - Full type safety
SQLite - Local database via better-sqlite3

AI/Analysis

Claude Agent SDK v0.1.5 - AI-powered analysis
Claude Code CLI - Local authentication

UI/Styling

shadcn/ui - Pre-built component library
Radix UI - Accessible primitives
Tailwind CSS 4 - Utility-first styling
Lucide React - Icon library

Data Handling

date-fns - Date manipulation
react-hook-form - Form state management
zod - Schema validation

📁 Detailed Project Structure

Understanding the Two-Level Structure:

This repository (learn_and_vibe/) is organized as a container for multiple learning analytics projects. Currently, it contains the Claude Code Chat Analytics application.

learn_and_vibe/                     ← Repository root
├── README.md                       ← This file (overview of all projects)
├── PRD.md                          ← Product Requirements Document
├── sdk_docs.md                     ← Claude SDK reference documentation
├── CLAUDE.md                       ← Project-wide Claude Code instructions
│
└── chat-analytics/                 ← 📦 Application root (Next.js app)
    │
    ├── README.md                   ← App-specific installation guide
    ├── package.json                ← Dependencies and scripts
    ├── tsconfig.json               ← TypeScript config (defines @/* alias)
    ├── next.config.ts              ← Next.js configuration
    ├── tailwind.config.ts          ← Tailwind CSS config
    │
    ├── app/                        ← Next.js App Router (pages & APIs)
    │   ├── page.tsx                  # Dashboard (project list)
    │   ├── layout.tsx                # Root layout with CLI status banner
    │   ├── projects/[projectId]/     # Dynamic project detail pages
    │   ├── settings/                 # Settings page
    │   └── api/                      # API route handlers
    │       ├── scan/route.ts           # POST: Discover Claude projects
    │       ├── analyze/route.ts        # POST: Run AI analysis
    │       ├── projects/route.ts       # GET: Fetch projects
    │       └── claude-status/route.ts  # GET: Check CLI installation
    │
    ├── lib/                        ← Core business logic
    │   ├── db.ts                     # SQLite database helpers
    │   ├── scanner.ts                # Filesystem scanner
    │   ├── jsonl-parser.ts           # Parse Claude session files
    │   ├── analyzer.ts               # Claude Agent SDK integration
    │   ├── cache-builder.ts          # Analysis caching
    │   ├── date-utils.ts             # Date utilities
    │   └── utils.ts                  # General utilities
    │
    ├── components/                 ← React components
    │   ├── project-card.tsx          # Project cards on dashboard
    │   ├── session-timeline.tsx      # Session visualization
    │   ├── nav-bar.tsx               # Navigation
    │   └── ui/                       # shadcn/ui components
    │
    ├── docs/                       ← Technical documentation
    │   ├── ARCHITECTURE.md           # System design deep-dive
    │   ├── DATABASE.md               # Schema documentation
    │   ├── API.md                    # API reference
    │   └── DEVELOPMENT.md            # Developer guide
    │
    ├── public/                     ← Static assets
    ├── analysis-cache/             ← Cached results (gitignored)
    └── chat-analytics.db           ← SQLite database (gitignored)

Path Alias Explanation:

The TypeScript compiler is configured in chat-analytics/tsconfig.json with:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

This means @/ resolves to chat-analytics/ (the app root), so:

@/lib/db → chat-analytics/lib/db.ts
@/components/ui/button → chat-analytics/components/ui/button.tsx

Where to Run Commands:

Unless explicitly stated, all npm commands and scripts should be run from chat-analytics/:

cd chat-analytics/    # Navigate to app root
npm install           # Install dependencies
npm run dev           # Start dev server

🔌 API Endpoints

`POST /api/scan`

Scans ~/.claude/projects/ and saves to database.

Response:

{
  "success": true,
  "projectsFound": 12,
  "totalSessions": 247
}

`POST /api/analyze`

Runs Claude Agent analysis on project sessions.

Request:

{
  "projectId": 1,
  "dateFrom": "2025-01-01",
  "dateTo": "2025-01-31",
  "customPrompts": ["What authentication patterns were used?"]
}

Response:

{
  "success": true,
  "analysisId": 42,
  "analysis": {
    "projectSummary": "...",
    "timeSpentMinutes": 180,
    "patterns": [...],
    "codeSnippets": [...],
    "recommendations": [...]
  }
}

`GET /api/projects`

Fetches all projects with session counts.

Response:

[
  {
    "id": 1,
    "name": "my-awesome-app",
    "path": "/Users/you/projects/my-awesome-app",
    "total_sessions": 23,
    "last_analyzed": "2025-01-15T10:30:00.000Z",
    "is_starred": 1
  }
]

`POST /api/projects/star`

Toggles project star status.

Request:

{
  "projectId": 1
}

`GET /api/claude-status`

Checks if Claude CLI is installed and working.

Response (success):

{
  "available": true,
  "path": "/Users/you/.claude/local/claude",
  "message": "Claude CLI is ready to use"
}

Response (not found):

{
  "available": false,
  "error": "CLAUDE_CLI_NOT_FOUND",
  "message": "Claude CLI not found. Install: npm install -g @anthropic-ai/claude-code"
}

See API.md for detailed endpoint documentation.

🧪 Testing

The app includes comprehensive testing documentation:

Manual Testing: Step-by-step scenarios in TESTING_STRATEGY.md
Unit Tests: (Coming soon) Test database helpers and parsers
Integration Tests: (Coming soon) Test API routes
E2E Tests: (Coming soon) Playwright tests for critical flows

Quick Test

# Check Claude CLI status
curl http://localhost:3000/api/claude-status | jq

# Scan projects
curl -X POST http://localhost:3000/api/scan | jq

# Verify Claude CLI works
claude --version

🚧 Troubleshooting

"Claude CLI not found" error

Symptoms: Red banner appears, analysis fails

Solutions:

Install Claude Code: npm install -g @anthropic-ai/claude-code
Authenticate: claude (opens browser)
Verify installation: which claude
Restart the app: npm run dev

Common causes:

Claude Code not in PATH
Installed with --prefix flag to non-standard location
Using NVM and Claude installed in different Node version

See the Settings page for detailed installation instructions.

Analysis takes too long

Symptoms: Analysis running for 5+ minutes

Solutions:

Reduce date range to analyze fewer sessions
Check Claude CLI works: claude --version
Check network connection (Claude needs internet)
View console logs: npm run dev shows analysis progress

Database locked error

Symptoms: SQLITE_BUSY errors in console

Solutions:

Stop any duplicate dev servers
Delete chat-analytics.db-wal and chat-analytics.db-shm
Restart: npm run dev

The database uses WAL mode which should prevent this, but multiple processes accessing the DB can cause conflicts.

Sessions not appearing

Symptoms: Scan completes but shows 0 sessions

Solutions:

Verify Claude Code projects exist: ls ~/.claude/projects/
Check JSONL files exist: ls ~/.claude/projects/*/
Check file permissions: ensure files are readable
Try manual path in Settings (future feature)

🗺️ Roadmap

v1.0 (Current)

v1.1 (Next)

Custom analysis prompts UI
Export analysis to Markdown/PDF
Search across all sessions
Session-level analysis (not just project-wide)
Better caching with TTL
Comparison view (compare two date ranges)

v2.0 (Future)

Tag-based organization
Multi-project analysis
Trend charts (time spent over time)
Code snippet favorites/collections
Manual session upload (for non-Claude Code histories)
Dark mode
Desktop app (Electron/Tauri)

🤝 Contributing

Contributions welcome! See DEVELOPMENT.md for:

Development setup
Code style guidelines
Testing requirements
PR process

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

Anthropic for Claude Code and the Agent SDK
Vercel for Next.js 15
shadcn for the beautiful UI component library
The open source community for all the amazing tools

📚 Additional Resources

Product Requirements Document - Original design spec
Architecture Guide - System design deep-dive
Database Schema - Full schema documentation
API Documentation - Complete API reference
Testing Strategy - How to test the app
Claude Code Docs - Official Claude Code documentation
Claude Agent SDK - SDK reference documentation

Last updated: 2025-10-05

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/workflows		.github/workflows
chat-analytics		chat-analytics
CLAUDE.md		CLAUDE.md
PRD.md		PRD.md
README.md		README.md
sdk_docs.md		sdk_docs.md

samuelleecong/learn_and_vibe

Folders and files

Latest commit

History

Repository files navigation

Learn and Vibe

📁 Repository Structure

Claude Code Chat Analytics

🎯 What This Does

✨ Key Features

🔍 Automatic Discovery

🧠 AI-Powered Analysis

📊 Insightful Metrics

💾 Local Storage

🎨 Modern UI

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

🚀 Quick Launch with cca Alias (Optional)

💻 Installing as a Desktop App (PWA)

Quick Install

📖 Usage Guide

1. First-Time Setup

2. Analyzing a Project

3. Starring Projects

4. Settings

🗄️ Database Schema

🛠️ Tech Stack

Core

AI/Analysis

UI/Styling

Data Handling

📁 Detailed Project Structure

🔌 API Endpoints

POST /api/scan

POST /api/analyze

GET /api/projects

POST /api/projects/star

GET /api/claude-status

🧪 Testing

Quick Test

🚧 Troubleshooting

"Claude CLI not found" error

Analysis takes too long

Database locked error

Sessions not appearing

🗺️ Roadmap

v1.0 (Current)

v1.1 (Next)

v2.0 (Future)

🤝 Contributing

📄 License

🙏 Acknowledgments

📚 Additional Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

🚀 Quick Launch with `cca` Alias (Optional)

`POST /api/scan`

`POST /api/analyze`

`GET /api/projects`

`POST /api/projects/star`

`GET /api/claude-status`

Packages