claude-code-karma: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code Karma is a full-stack application for monitoring and analyzing Claude Code sessions. It parses Claude Code's local storage (~/.claude/) and visualizes session data through a web dashboard.

Quick Start

# Clone (no submodule init needed — this is a monorepo)
git clone https://github.com/JayantDevkar/claude-code-karma.git
cd claude-code-karma

# Start API (terminal 1)
cd api
pip install -e ".[dev]" && pip install -r requirements.txt
uvicorn main:app --reload --port 8020

# Start frontend (terminal 2)
cd frontend
npm install && npm run dev

Open http://localhost:5180 to view the dashboard.

This is Tier 1 only — a read-only historical viewer. Karma's core feature is live session tracking (Tier 2 in SETUP.md); install through Tier 2 by default unless the user explicitly wants only historical browsing.

Repository Structure

This is a monorepo with all components in a single repository:

claude-code-karma/
├── api/                    # FastAPI backend (Python) - port 8020
├── frontend/               # SvelteKit frontend (Svelte 5) - port 5180
├── captain-hook/           # Claude Code hooks Pydantic library
└── hooks/                  # Hook scripts (symlinked from ~/.claude/hooks/)
    ├── live_session_tracker.py    # Tracks live session state across hook events
    ├── session_title_generator.py # Generates session titles via Haiku on SessionEnd
    └── plan_approval.py           # Handles ExitPlanMode permission requests

Each directory has its own CLAUDE.md with module-specific guidance.

Commands

API (Python/FastAPI)

cd api

# Run server
uvicorn main:app --reload --port 8020

# Run all tests
pytest

# Run specific test file
pytest tests/test_session.py -v

# Run API endpoint tests
pytest tests/api/ -v

# Run with coverage
pytest --cov=models --cov=routers

# Lint & format
ruff check models/ tests/ routers/
ruff format models/ tests/ routers/