Skip to content

The agent that turns websites into APIs!

feat: autogenerate CLAUDE.md

kalil0321b2287df779e4
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..afbc8c9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,206 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Reverse API Engineer is a CLI tool that captures browser traffic (HAR files) and uses AI to automatically generate production-ready Python API clients. It supports three modes: manual browser capture, autonomous AI agent browsing, and re-engineering from previous captures.
+
+## Core Architecture
+
+### SDK Dispatch Pattern
+The project uses a **dual-SDK architecture** controlled by `config.json`:
+
+- **Claude SDK** (`engineer.py` → `ClaudeEngineer`): Uses `claude-agent-sdk` for direct Claude API integration
+- **OpenCode SDK** (`opencode_engineer.py` → `OpenCodeEngineer`): Uses httpx to communicate with local OpenCode server (http://127.0.0.1:4096)
+
+Both inherit from `BaseEngineer` (abstract base class) which defines the common interface and shared prompt building logic. The SDK selection is determined by the `sdk` field in config.
+
+### Key Components
+
+- **CLI Layer** (`cli.py`): Main entry point with mode cycling (manual/engineer/agent), slash commands, and interactive prompts
+- **Browser** (`browser.py`): Playwright-based HAR recording with stealth mode and anti-detection measures
+ - `ManualBrowser`: User-controlled browser with HAR capture
+ - `run_agent_browser()`: Autonomous agent browsing (browser-use or stagehand)
+- **Configuration** (`config.py`): JSON-based config manager at `~/.reverse-api/config.json`
+- **Session Management** (`session.py`): Tracks run history with costs and metadata
+- **Message Store** (`messages.py`): Persists full conversation logs per run
+- **UI** (`tui.py`, `opencode_ui.py`): Rich-based terminal UI for progress tracking
+
+### Data Flow
+1. Browser captures HAR → saved to `~/.reverse-api/runs/{run_id}/har/`
+2. Engineer analyzes HAR with LLM → generates Python scripts
+3. Scripts saved to:
+ - `~/.reverse-api/runs/{run_id}/scripts/` (permanent)
+ - `./scripts/{descriptive_name}/` (local copy)
+
+## Development Commands
+
+### Setup
+```bash
+# Clone and install dependencies
+git clone https://github.com/kalil0321/reverse-api-engineer.git
+cd reverse-api-engineer
+uv sync
+playwright install chromium
+
+# Run locally (development mode)
+uv run reverse-api-engineer
+```
+
+### Building
+```bash
+# Clean build (removes all caches and artifacts)
+./scripts/clean_build.sh
+
+# Manual build
+uv build
+```
+
+### Testing
+```bash
+# Test as installed package (creates isolated venv)
+python -m venv test_env
+test_env/bin/pip install dist/*.whl
+test_env/bin/reverse-api-engineer
+
+# Test with uv tool
+uv tool install .
+reverse-api-engineer
+```
+
+## Release Process
+
+**Single source of truth: `pyproject.toml`**
+
+1. Update version in `pyproject.toml` only
+2. Update `CHANGELOG.md`
+3. Run `./scripts/clean_build.sh`
+4. Commit and tag:
+ ```bash
+ git add pyproject.toml CHANGELOG.md
+ git commit -m "release: vX.Y.Z - description"
+ git tag vX.Y.Z
+ git push origin main
+ git push origin vX.Y.Z
+ ```
+5. Publish to PyPI:
+ ```bash
+ source .env # contains UV_PUBLISH_TOKEN or PYPI_TOKEN
+ uv publish
+ ```
+
+**Important:** Never edit `src/reverse_api/__init__.py` for versioning—it reads from package metadata via `importlib.metadata`.
+
+## Configuration System
+
+### Config Location
+`~/.reverse-api/config.json` with these fields:
+
+```json
+{
+ "claude_code_model": "claude-sonnet-4-5", // For Claude SDK
+ "opencode_provider": "anthropic", // For OpenCode SDK
+ "opencode_model": "claude-sonnet-4-5", // For OpenCode SDK
+ "sdk": "claude", // "claude" or "opencode"
+ "agent_provider": "browser-use", // "browser-use" or "stagehand"
+ "browser_use_model": "bu-llm", // Browser-use agent model
+ "stagehand_model": "openai/computer-use-preview-2025-03-11",
+ "output_dir": null // Custom output dir (null = use ~/.reverse-api/runs)
+}
+```
+
+### Model Naming
+- **Claude models**: `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-haiku-4-5`
+- **Gemini models**: `gemini-3-flash`, `gemini-3-pro`, `gemini-3-pro-low`, `gemini-3-pro-high`
+- **Antigravity models** (free tier): Require OpenCode SDK with `opencode_provider: "google"`
+- **Agent models**: Format varies by provider
+ - Browser-use: `bu-llm` or `{provider}/{model}` (e.g., `openai/gpt-4`)
+ - Stagehand: `{provider}/{model}` (e.g., `openai/computer-use-preview-2025-03-11`)
+
+## Pricing System
+
+### Three-tier fallback for cost calculation:
+1. **Local pricing** (`pricing.py`): Built-in prices for Claude/Gemini models
+2. **LiteLLM pricing** (optional `[pricing]` extra): Extended coverage for 100+ models
+3. **Default pricing**: Falls back to Claude Sonnet 4.5 pricing
+
+Pricing tracks:
+- Input/output tokens
+- Cache creation/read tokens
+- Reasoning tokens (for thinking models)
+
+## Agent Mode
+
+### Requirements
+Agent mode requires browser-use from specific git commit (has HAR recording support):
+```bash
+uv tool install 'reverse-api-engineer[agent]' --with 'browser-use @ git+https://github.com/browser-use/browser-use.git@49a345fb19e9f12befc5cc1658e0033873892455'
+```
+
+### Agent Providers
+- **browser-use**: Multi-model support (Browser-Use LLM, OpenAI, Google)
+- **stagehand**: Computer Use models only (OpenAI, Anthropic)
+
+API keys via environment variables: `BROWSER_USE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`
+
+## Code Style Conventions
+
+- **Type hints**: Use throughout (`from typing import Optional, Dict, Any`)
+- **Async/await**: Engineers use async for LLM streaming
+- **Error handling**: Wrap external calls in try-except with user-friendly messages
+- **UI consistency**: Use Rich for all terminal output (no plain print statements)
+- **Config migration**: `config.py` includes backward compatibility logic for renamed keys
+
+## Common Tasks
+
+### Adding a new model
+1. Add pricing to `pricing.py` MODEL_PRICING dict (if not in LiteLLM)
+2. Update model choices in `tui.py` get_model_choices() if needed
+3. Update README.md model list
+
+### Adding a new agent provider
+1. Add provider logic to `browser.py` run_agent_browser()
+2. Add config fields to `config.py` DEFAULT_CONFIG
+3. Update settings menu in `cli.py`
+4. Document in README.md
+
+### Debugging
+- **OpenCode**: Set `OPENCODE_DEBUG=1` for detailed logs
+- **Stagehand logs**: Suppressed by `_suppress_stagehand_logs()` in `browser.py`
+- **Message logs**: All LLM interactions saved to `~/.reverse-api/runs/{run_id}/messages/`
+
+## File Structure Notes
+
+```
+src/reverse_api/
+├── cli.py # Main entry point, mode cycling, slash commands
+├── base_engineer.py # Abstract base for SDK implementations
+├── engineer.py # Claude SDK implementation
+├── opencode_engineer.py # OpenCode SDK implementation
+├── browser.py # Playwright HAR capture + agent mode
+├── config.py # Configuration manager
+├── session.py # Run history and metadata
+├── messages.py # Message persistence
+├── pricing.py # Model pricing database
+├── tui.py # Terminal UI (Rich-based)
+├── opencode_ui.py # OpenCode-specific UI extensions
+└── utils.py # Path helpers, run ID generation
+
+~/.reverse-api/
+├── config.json # User configuration
+├── history.json # Run history with costs
+└── runs/{run_id}/ # Per-run data
+ ├── har/ # Captured traffic
+ ├── scripts/ # Generated API clients
+ └── messages/ # LLM conversation logs
+```
+
+## Dependencies Management
+
+Uses `uv` for dependency management:
+- **Core deps**: playwright, claude-agent-sdk, rich, questionary, anthropic
+- **Optional [agent]**: stagehand (browser-use must be installed separately from git)
+- **Optional [pricing]**: litellm (for extended model pricing)
+
+Always use `uv sync` after pulling changes.