# Project Overview

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

- Skill: `tools-only/project-overview-12` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/project-overview-12`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/project-overview-12/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/project-overview-12

---

# CLAUDE.md

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

## Project Overview

Heavy3 Code Audit (`/h3`) is a Claude Code skill providing AI-powered multi-model code reviews via OpenRouter. Tiers:
- **Lite (default)**: DeepSeek V3.2, up to 100K tokens
- **Pro ($59 Founder / $99 Regular)**: 3-model council (GPT 5.2 + Gemini 3 Pro + Grok 4), up to 200K tokens
- **Free**: Rotating free models from OpenRouter

## Local Development Setup

```bash
# Symlink for Claude Code discovery
mkdir -p ~/.claude/skills && ln -sf "$(pwd)/skill" ~/.claude/skills/h3

# Make scripts executable
chmod +x skill/scripts/*.py

# Install dependency
pip install requests

# Required env var
export OPENROUTER_API_KEY="your-key"
```

## Architecture

The skill uses YAML frontmatter + markdown format in `SKILL.md` to define the skill manifest that Claude reads during `/h3` execution.

```
skill/
├── SKILL.md              # Skill manifest: YAML frontmatter + instructions for Claude
├── config.json           # User config (tier, model, license_key, context limits)
└── scripts/
    ├── review.py         # Lite mode: OpenRouter API calls, prompt templates
    ├── council.py        # Pro mode: 3-parallel reviews with local license check
    ├── license.py        # License activation and verification
    └── list-free-models.py # OpenRouter free model discovery
```

**Data Flow:**
1. User invokes `/h3 code|plan|pr <number>` in Claude Code
2. Claude reads SKILL.md, gathers context (git diff, files, docs)
3. Context compiled to JSON and passed to review script via `--context-file`
4. Script calls OpenRouter API, returns review
5. Claude synthesizes findings, proposes fixes for user approval

## Testing the Skill

### Automated Tests (pytest)

```bash
# Install test dependencies
cd skill && pip install -r requirements-dev.txt

# Run all tests
cd scripts && python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_context.py -v
python -m pytest tests/test_review.py -v
python -m pytest tests/test_streaming.py -v
python -m pytest tests/test_council.py -v
```

### Manual Integration Tests

After symlinking, test in Claude Code:
- `/h3 code` - Review uncommitted changes
- `/h3 plan` - Review implementation plan
- `/h3 pr <number>` - Review GitHub PR
- `/h3 --council` - Pro council mode (requires license)

### Testing Requirements

**Every new feature MUST have:**
1. **Unit tests** - Test individual functions/modules in isolation
2. **Integration tests** (for major features) - Test the full workflow end-to-end

**Before merging:**
- All existing tests must pass: `python -m pytest tests/ -v`
- New tests must be added for new functionality
- Test coverage should not decrease

## Key Implementation Details

- **Model shortcuts**: `--model gpt`, `--model deepseek`, `--model free` resolve to full OpenRouter model IDs
- **Context limits**: Lite 100K tokens (~400K chars), Pro 200K tokens (~800K chars)
- **Large changes**: SKILL.md instructs Claude to detect >50 files or >10K lines and break into module-by-module reviews
- **PR review**: Uses `gh pr view` and `gh pr diff` for GitHub integration
- **Council synthesis**: Pro mode outputs a comparison table across 3 reviewer perspectives (Correctness/Security/Performance)