Contributing to Claude Code Karma

Contributing to Claude Code Karma

Thank you for your interest in contributing to Claude Code Karma! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

Please review our [Code of Conduct](./CODE_OF_CONDUCT.md) and follow it in all interactions with the project community.

Getting Started

Prerequisites

Before you begin, ensure you have:

• Python 3.9+
• Node.js 18+
• npm 7+
• Git
• Claude Code sessions (to test with real data)

Verify your setup:

python3 --version    # 3.9 or higher
node --version       # 18 or higher
npm --version        # 7 or higher
git --version        # any version

Development Setup

1. Clone the repository

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

1. Set up the API

cd api
pip install -e ".[dev]"
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

The API will be available at `http://localhost:8000`.

1. Set up the Frontend (in a new terminal)

cd frontend
npm install
npm run dev

The frontend will be available at `http://localhost:5173`.

1. Set up Captain Hook (if making changes)

cd captain-hook
pip install -e ".[dev]"
pytest tests/test_models.py -v

Reporting Issues

Reporting Bugs

If you find a bug:

1. Check if it's already reported — Search existing issues
2. Create a new issue with:
   • Clear title describing the bug
   • Step-by-step reproduction steps
   • Expected vs actual behavior
   • Python version, Node version, OS
   • Relevant logs or screenshots

Suggesting Features

To suggest a feature:

1. Check if it's already requested — Search existing issues
2. Create a new issue with:
   • Clear title describing the feature
   • Use case and motivation
   • Proposed solution (if any)
   • Additional context or examples

Development Workflow

Creating a Feature Branch

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Use descriptive branch names:

• feature/add-export-button
• fix/session-timeline-crash
• docs/update-api-guide

Code Style

Python (API & Captain Hook)

We use **ruff** for linting and formatting.

# Check for style issues
ruff check models/ routers/ tests/

# Auto-format code
ruff format models/ routers/ tests/

# Run linting in CI
ruff check --select E,F,W --line-length 120

Guidelines:

• Follow PEP 8
• Use type hints for all functions
• Document public functions with docstrings
• Max line length: 120 characters
• Use ConfigDict(frozen=True) for Pydantic models

Frontend (SvelteKit/Svelte 5)

We use **prettier** and **eslint** for formatting and linting.

# Check for style issues
npm run lint

# Auto-format code
npm run format

# Type check