Claude Code Karma Setup

Claude Code Karma Setup

Step-by-step guide for installing and configuring Claude Code Karma — a dashboard for monitoring and analyzing Claude Code sessions. Designed for both humans and AI agents (Claude Code, etc.).

---

What You'll Get

Claude Code Karma installs in **3 progressive tiers**. Start with the core dashboard, then add live monitoring and smart titles as needed.

Tier	Components	Dashboard Features	Installation Time
1: Core Dashboard	API + Frontend	Browse projects, view sessions, analytics	~5 min
2: Live Monitoring	+ Live Tracker Hook	Real-time session indicators, recently ended	+2 min
3: Smart Titles	+ Title Generator Hook	Human-readable session names	+2 min

**You can stop after Tier 1.** Tiers 2 and 3 are optional enhancements installed independently.

---

Prerequisites

Verify you have the required tools:

# Required
python3 --version    # 3.9+
node --version       # 18+
npm --version        # 7+
git --version        # any version

# Required (must have Claude Code sessions)
ls ~/.claude/projects/    # Should show encoded project directories

# Optional (for smart titles via Claude Haiku)
claude --version     # Claude CLI (any version)

Tool	Minimum	Required?	Why
Python	3.9+	Yes	API backend runs on Python
Node.js	18+	Yes	Frontend build system
npm	7+	Yes	Frontend package manager
Git	Any	Yes	Clone repository
Claude Code	2.1.19+	For Tier 2 subagent tracking	Track subagent spawning
Claude CLI	Any	For Tier 3 smart titles	Generate titles via Haiku

---

Tier 1: Core Dashboard (Required)

Step 1: Clone the Repository

**What:** Download the Claude Code Karma repository. **Why:** Gets all components — API, frontend, and hook scripts — in one go.

git clone https://github.com/JayantDevkar/claude-code-karma.git
cd claude-code-karma

**Verify:**

ls api/main.py frontend/package.json hooks/live_session_tracker.py

All three files must exist.

**Agent notes:** Confirm all three files exist. If `api/` or `frontend/` are empty, the clone may have failed — re-clone.

---

Step 2: Start the API

**What:** Launch the FastAPI backend on port 8000. **Why:** Parses Claude Code sessions and serves the REST API that the frontend consumes.

**Working directory:** `cd api`

**Install dependencies:**

# Option A: System Python (fastest)
pip install -e ".[dev]"
pip install -r requirements.txt

# Option B: Virtual environment (recommended for isolation)
python3 -m venv venv
source venv/bin/activate  # or: venv\Scripts\activate on Windows
pip install -e ".[dev]"
pip install -r requirements.txt

**Start the server:**

uvicorn main:app --reload --port 8000

**On first startup, the API will:**

1. Create ~/.claude_karma/ directory
2. Create `~/.claude_karma/metadat