Add Claude context configuration files

Add .claude/CLAUDE.md with project documentation (architecture, commands, conventions, env vars) and .claude/settings.json with tool permissions for streamlined agent development.
2025-12-25 20:41:20 +01:00
parent 812bc4dc08
commit fb2f3407b4
2 changed files with 206 additions and 0 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,175 @@
+# Open Agent
+
+Minimal autonomous coding agent in Rust with **full machine access** (not sandboxed).
+
+## Quick Reference
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Backend (Rust) | `src/` | HTTP API + agent system |
+| Dashboard (Next.js) | `dashboard/` | Web UI (uses **Bun**, not npm) |
+| iOS Dashboard | `ios_dashboard/` | Native iOS app (Swift/SwiftUI) |
+| MCP configs | `.open_agent/mcp/config.json` | Model Context Protocol servers |
+| Tuning | `.open_agent/tuning.json` | Calibration data |
+
+## Commands
+
+```bash
+# Backend
+cargo build --release           # Build
+cargo run --release             # Run server (port 3000)
+RUST_LOG=debug cargo run        # Debug mode
+cargo test                      # Run tests
+cargo fmt                       # Format code
+cargo clippy                    # Lint
+
+# Dashboard (uses Bun, NOT npm)
+cd dashboard
+bun install                     # Install deps
+bun dev                         # Dev server (port 3001)
+bun run build                   # Production build
+
+# Deployment
+ssh root@95.216.112.253 'cd /root/open_agent && git pull && cargo build --release && cp target/release/open_agent /usr/local/bin/ && systemctl restart open_agent'
+```
+
+## Architecture
+
+```
+SimpleAgent
+    └── TaskExecutor → runs tools in a loop with auto-upgrade
+```
+
+### Module Map
+
+```
+src/
+├── agents/           # Agent system
+│   ├── simple.rs     # SimpleAgent (main entry point)
+│   └── leaf/         # TaskExecutor
+├── budget/           # Cost tracking, pricing, smart retry
+│   ├── benchmarks.rs # Model capability scores
+│   ├── pricing.rs    # OpenRouter pricing + model allowlist
+│   └── resolver.rs   # Model family auto-upgrade system
+├── memory/           # Supabase + pgvector persistence
+│   ├── supabase.rs   # Database client
+│   ├── context.rs    # ContextBuilder, SessionContext
+│   ├── retriever.rs  # Semantic search
+│   └── writer.rs     # Event recording
+├── mcp/              # MCP server registry + config
+├── llm/              # OpenRouter client
+├── tools/            # File ops, terminal, git, web, search, desktop
+├── task/             # Task types + verification
+├── config.rs         # Config + env vars
+└── api/              # HTTP routes (axum)
+```
+
+## Model Preferences
+
+**NEVER use Claude models** (anthropic/claude-*) - they are prohibitively expensive.
+
+**Preferred models (in order):**
+1. `google/gemini-3-flash-preview` - Fast, cheap, excellent tool use, **default**
+2. `qwen/qwen3-235b-a22b-instruct` - Strong reasoning, affordable
+3. `deepseek/deepseek-v3.2` - Good value, capable
+4. `x-ai/grok-4.1-fast` - Fast alternative
+
+## API Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/api/task` | Submit task |
+| `GET` | `/api/task/{id}` | Get status |
+| `GET` | `/api/task/{id}/stream` | SSE progress |
+| `GET` | `/api/health` | Health check |
+| `POST` | `/api/control/message` | Send message to agent |
+| `GET` | `/api/control/stream` | SSE event stream |
+| `GET` | `/api/models` | List available models |
+
+## Environment Variables
+
+### Required
+| Variable | Description |
+|----------|-------------|
+| `OPENROUTER_API_KEY` | OpenRouter API key (sk-or-v1-...) |
+
+### Production Auth
+| Variable | Description |
+|----------|-------------|
+| `DEV_MODE` | `true` bypasses auth |
+| `DASHBOARD_PASSWORD` | Password for dashboard login |
+| `JWT_SECRET` | HMAC secret for JWT signing |
+
+### Optional
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEFAULT_MODEL` | `google/gemini-3-flash-preview` | Default LLM |
+| `WORKING_DIR` | `/root` (prod), `.` (dev) | Working directory |
+| `HOST` | `127.0.0.1` | Bind address |
+| `PORT` | `3000` | Server port |
+| `MAX_ITERATIONS` | `50` | Max agent loop iterations |
+| `SUPABASE_URL` | - | Supabase project URL |
+| `SUPABASE_SERVICE_ROLE_KEY` | - | Service role key |
+| `TAVILY_API_KEY` | - | Web search API key |
+
+## Secrets
+
+Use `secrets.json` (gitignored) for local development. Template: `secrets.json.example`
+
+```bash
+# Read secrets
+jq -r '.openrouter.api_key' secrets.json
+```
+
+**Rules:**
+- Never paste secret values into code, comments, or docs
+- Read secrets from environment variables at runtime
+
+## Code Conventions
+
+### Rust
+1. **Never panic** - always return `Result<T, E>`
+2. **Exhaustive matches** - no `_` catch-all patterns in enums
+3. **Document invariants** as `/// Precondition:` and `/// Postcondition:` comments
+4. Costs are in **cents (u64)** - never use floats for money
+
+### Dashboard (Next.js + Bun)
+- Package manager: **Bun** (not npm/yarn/pnpm)
+- Icons: **Lucide React** (`lucide-react`)
+- API base: `process.env.NEXT_PUBLIC_API_URL ?? 'http://127.0.0.1:3000'`
+- Auth: JWT stored in `sessionStorage`
+
+### Design System
+- **Dark-first** aesthetic
+- No pure black - use deep charcoal (#121214)
+- Use `white/[opacity]` for text (e.g., `text-white/80`)
+- Accent color: indigo-500 (#6366F1)
+- Borders: very subtle (0.06-0.08 opacity)
+
+## Production
+
+| Property | Value |
+|----------|-------|
+| Host | `95.216.112.253` |
+| SSH | `ssh root@95.216.112.253` |
+| Backend URL | `https://agent-backend.thomas.md` |
+| Dashboard URL | `https://agent.thomas.md` |
+| Binary | `/usr/local/bin/open_agent` |
+| Env file | `/etc/open_agent/open_agent.env` |
+| Service | `systemctl status open_agent` |
+
+## Adding New Components
+
+### New Tool
+1. Add to `src/tools/` (new file or extend existing)
+2. Implement `Tool` trait: `name()`, `description()`, `parameters()`, `call()`
+3. Register in `src/tools/mod.rs` → `create_tools()`
+
+### New API Endpoint
+1. Add handler in `src/api/`
+2. Register route in `src/api/mod.rs`
+3. Update this doc
+
+### After Significant Changes
+- Update `.cursor/rules/` if architecture changes
+- Update `CLAUDE.md` for new env vars or commands
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cargo build:*)",
+      "Bash(cargo run:*)",
+      "Bash(cargo test:*)",
+      "Bash(cargo fmt:*)",
+      "Bash(cargo clippy:*)",
+      "Bash(bun:*)",
+      "Bash(cd dashboard && bun:*)",
+      "Bash(git:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(mkdir:*)",
+      "Bash(rm:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(jq:*)",
+      "Bash(ssh:*)",
+      "Bash(scp:*)",
+      "Bash(python:*)",
+      "Bash(curl:*)",
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep"
+    ],
+    "deny": []
+  }
+}