karma

Karma — Claude Code Session Dashboard

Manage the Claude Code Karma dashboard (session browser, analytics, live monitoring).

Location: ~/claude-code-karma Ports: API = 9005, Frontend = 5199

Commands

When the user invokes /karma, parse their intent and run the appropriate action.

Start (default)

Start both API and frontend servers. If already running, report status instead.

# Check if already running
if lsof -ti:9005 > /dev/null 2>&1; then
  echo "API already running on :9005"
else
  cd ~/claude-code-karma/api
  source venv/bin/activate
  uvicorn main:app --reload --port 9005 &
  echo "API starting on :9005"
fi

if lsof -ti:5199 > /dev/null 2>&1; then
  echo "Frontend already running on :5199"
else
  cd ~/claude-code-karma/frontend
  npm run dev -- --port 5199 &
  echo "Frontend starting on :5199"
fi

Then tell the user to open http://localhost:5199

Stop

lsof -ti:9005 | xargs kill 2>/dev/null && echo "API stopped" || echo "API not running"
lsof -ti:5199 | xargs kill 2>/dev/null && echo "Frontend stopped" || echo "Frontend not running"

Status

curl -s http://localhost:9005/health | python3 -m json.tool 2>/dev/null || echo "API not running"
curl -s -o /dev/null -w "%{http_code}" http://localhost:5199 2>/dev/null || echo "Frontend not running"

Reindex

Force the API to reindex all sessions from ~/.claude/projects/:

curl -X POST http://localhost:8000/admin/reindex

Update

Pull latest changes and reinstall dependencies:

cd ~/claude-code-karma
git pull origin main
cd api && source venv/bin/activate && pip install -r requirements.txt
cd ../frontend && npm install

Then restart both servers.

Usage Examples

• /karma or /karma start — start the dashboard
• /karma stop — stop both servers
• /karma status — check if running, show session count
• /karma reindex — force session reindex
• /karma update — pull latest + reinstall deps

Troubleshooting

• CORS errors: API allows localhost:5199 by default. If changed, set CLAUDE_KARMA_CORS_ORIGINS.
• Empty projects: Check ls ~/.claude/projects/ has session data.
• Port conflict: Kill existing processes with /karma stop first.
• Venv issues: cd ~/claude-code-karma/api && python3 -m venv venv && source venv/bin/activate && pip install -e ".[dev]" && pip install -r requirements.txt