|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +**promptplay** is a tool that uses the [Claude Agent SDK](https://github.com/anthropics/anthropic-sdk-python) to transform natural language prompts into fully functional, playable games. The agent receives a game description, uses Claude to write complete HTML/JavaScript game code, and outputs the result. |
| 8 | + |
| 9 | +## Setup & Common Commands |
| 10 | + |
| 11 | +### Initial Setup |
| 12 | +```bash |
| 13 | +# Create and activate virtual environment |
| 14 | +python -m venv venv |
| 15 | +source venv/bin/activate # Windows: venv\Scripts\activate |
| 16 | + |
| 17 | +# Install dependencies |
| 18 | +pip install -r requirements.txt |
| 19 | + |
| 20 | +# Configure API key |
| 21 | +cp .env.example .env |
| 22 | +# Edit .env and add your ANTHROPIC_API_KEY |
| 23 | +``` |
| 24 | + |
| 25 | +### Running the Agent |
| 26 | +```bash |
| 27 | +# Generate a game from the current prompt in agent.py |
| 28 | +python agent.py |
| 29 | + |
| 30 | +# Redirect output to an HTML file and open it |
| 31 | +python agent.py > my_game.html && open my_game.html |
| 32 | +``` |
| 33 | + |
| 34 | +### Code Quality |
| 35 | +```bash |
| 36 | +# Check for import errors (run by CI) |
| 37 | +python -c "import agent; print('✓ All imports OK')" |
| 38 | + |
| 39 | +# Lint with ruff (only checks critical issues: syntax, undefined names, etc.) |
| 40 | +pip install ruff |
| 41 | +ruff check . --select=E9,F63,F7,F82 --show-source |
| 42 | +``` |
| 43 | + |
| 44 | +## Architecture |
| 45 | + |
| 46 | +The project is minimal and focused: |
| 47 | + |
| 48 | +- **agent.py**: Single entry point using the Claude Agent SDK |
| 49 | + - Uses `query()` async function with ClaudeAgentOptions |
| 50 | + - Configurable model, allowed_tools, and effort level |
| 51 | + - Streams responses and prints the result (typically HTML game code) |
| 52 | + - Currently set to Haiku model for quick iteration |
| 53 | + |
| 54 | +- **Key Dependencies**: |
| 55 | + - `claude-agent-sdk`: Provides the `query()` function and agent orchestration |
| 56 | + - `python-dotenv`: Loads ANTHROPIC_API_KEY from .env file |
| 57 | + |
| 58 | +## Development Workflow |
| 59 | + |
| 60 | +1. **To test a prompt**: Edit the `prompt` string in `agent.py`, then run `python agent.py` |
| 61 | +2. **To switch models**: Change the `model` parameter (e.g., `"claude-opus-4-8"` for complex games) |
| 62 | +3. **To enable more tools**: Add tools to `allowed_tools` list (e.g., `["Bash", "Glob", "Read", "Write"]`) |
| 63 | +4. **Before committing**: Run the import check and verify the code runs without errors |
| 64 | + |
| 65 | +## Testing & CI |
| 66 | + |
| 67 | +- CI runs on Python 3.10, 3.11, 3.12 |
| 68 | +- Tests verify: imports work, ruff linting passes |
| 69 | +- No dedicated test suite yet (see CONTRIBUTING.md for good first issues) |
| 70 | + |
| 71 | +## Key Files |
| 72 | + |
| 73 | +- `agent.py` – Main agent logic (async query to Claude) |
| 74 | +- `requirements.txt` – Dependencies |
| 75 | +- `.env.example` – Template for API key configuration |
| 76 | +- `CHANGELOG.md` – Version history |
| 77 | +- `CONTRIBUTING.md` – Guidelines for contributors |
0 commit comments