OmoiOS

# CLAUDE.md

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

## Project Overview

OmoiOS is a spec-driven, multi-agent orchestration system that scales development without scaling headcount. It combines autonomous agent execution with structured workflows (Requirements → Design → Tasks → Execution) using the Claude Agent SDK and OpenHands SDK.

**Production URLs:**
- Frontend: `https://omoios.dev`
- Backend API: `https://api.omoios.dev`

### Deployment Infrastructure

**Vercel Projects** (org: `automation-workz`):

| Project | URL | Directory | Purpose |
|---------|-----|-----------|---------|
| `omoios-frontend` | `https://www.omoios.dev` | `frontend/` | Main production frontend |
| `omoi-os` | `https://omoi-os.vercel.app` | — | Legacy/alternate frontend |
| `landing-pages` | `https://landing-pages-automation-workz.vercel.app` | `landing-pages/` | Marketing landing pages |
| `omoi-prompt-frontend` | `https://prompt.omoios.dev` | — | Prompt playground frontend |

```bash
# List all Vercel projects
vercel project ls

# Manage env vars for the main frontend (run from frontend/)
cd frontend && vercel env ls
vercel env add <NAME> production
vercel env rm <NAME> production
```

**Railway** (project: `aomoi-os-backend`):

| Service | Environment | Purpose |
|---------|-------------|---------|
| `omoi-api` | `production` | FastAPI backend API |

```bash
# Link to the Railway project
railway link

# List env vars
railway variables

# Set an env var
railway variables set KEY=value
```

**Important notes:**
- `.env` files are gitignored and protected by detect-secrets pre-commit hook — never modify them for deployment config
- Frontend env vars with `NEXT_PUBLIC_` prefix are embedded in the client-side JS bundle
- Production secrets (Sentry tokens, PostHog keys, etc.) live exclusively in Vercel/Railway env var storage
- The `omoios-frontend` Vercel project already has all production env vars configured

## Monorepo Structure

This project uses **uv workspaces** for unified Python dependency management:

```
senior_sandbox/
├── pyproject.toml          # Root workspace config
├── uv.lock                  # Single lock file for all packages
├── backend/                 # FastAPI backend (omoi-os package)
│   ├── omoi_os/             # Main Python package
│   └── CLAUDE.md            # Backend-specific guide (detailed)
├── frontend/                # Next.js 15 frontend
├── subsystems/
│   └── spec-sandbox/        # Spec execution runtime
├── docs/                    # Documentation (30,000+ lines)
├── scripts/                 # Development scripts
└── Justfile                 # Task runner (see `just --list`)
```

## Development Commands

### Quick Start (Recommended: Use Justfile)

```bash
# Show all available commands
just --list

# Full stack development (Docker with hot-reload)
just watch                    # Backend services with hot-reload
just frontend-dev             # Frontend dev server
just dev-all                  # Everything at once

# Testing
just test                     # Run affected tests only (testmon)
just test-all                 # Full test suite
just test-coverage            # With HTML coverage report

# Code quality
just format                   # Format code
just lint                     # Lint check
just check                    # All quality checks
```

### Manual Commands (Backend)

```bash
cd backend

# Dependencies (uv sync from root handles workspaces)
uv sync                       # Install all
uv sync --group test          # Include test deps

# API server
uv run uvicorn omoi_os.api.main:app --host 0.0.0.0 --port 18000 --reload

# Database
uv run alembic upgrade head   # Run migrations
uv run alembic revision -m "description"  # Create migration

# Testing
uv run pytest                 # All tests
uv run pytest tests/path/test_file.py::TestClass::test_method -v  # Single test
```

### Manual Commands (Frontend)

```bash
cd frontend
pnpm install                  # Install dependencies
pnpm dev                      # Dev server (port 3000)
pnpm build                    # Production build
pnpm lint                     # Lint check
```

## Architecture Highlights

### Backend Tech Stack
- **Framework**: FastAPI 0.104+ with async
- **Database**: PostgreSQL 16 + pgvector (SQLAlchemy 2.0+)
- **Cache/Queue**: Redis 7 + Taskiq
- **LLM**: Claude Agent SDK, Anthropic Claude
- **Sandbox**: Daytona for isolated workspace execution
- **Auth**: JWT (custom auth service)
- **Observability**: Sentry + OpenTelemetry + Logfire

### Frontend Tech Stack
- **Framework**: Next.js 15 (App Router)
- **UI**: ShadCN UI (Radix + Tailwind)
- **State**: Zustand (client) + React Query (server)
- **Graphs**: React Flow v12, @xyflow/react
- **Terminal**: xterm.js

### Core Services
- **SpecStateMachine**: Multi-phase spec workflow (EXPLORE → REQUIREMENTS → DESIGN → TASKS → SYNC)
- **TaskQueueService**: Priority-based task assignment with dependencies
- **AgentHealthService**: 30s heartbeats, 90s timeout
- **EventBusService**: Redis pub/sub for real-time state
- **IntelligentGuardian**: LLM-powered trajectory analysis

### Port Configuration
| Service | Port | Note |
|---------|------|------|
| PostgreSQL | 15432 | +10000 offset |
| Redis | 16379 | +10000 offset |
| Backend API | 18000 | +10000 offset |
| Frontend | 3000 | Standard |

## Critical Rules

> **Full rules directory**: [`docs/rules/`](docs/rules/README.md). Each file
> captures one class of recurring bug — the stack trace, why it happens in
> this codebase, and the pattern that prevents it. Check the index before
> writing dependencies, route handlers, or models.

### SQLAlchemy Reserved Keywords (NEVER USE)
- `metadata` - Use `change_metadata`, `item_metadata`, `config_data`
- `registry` - Use `agent_registry`, `service_registry`
- Full write-up: [`docs/rules/sqlalchemy-reserved-keywords.md`](docs/rules/sqlalchemy-reserved-keywords.md)

### SQLAlchemy Session Handling (DetachedInstanceError)
Any FastAPI dependency that loads an ORM object inside `with db.get_session()` and returns it **must** force-load lazy attributes, call `session.refresh(obj)`, then `session.expunge(obj)` before returning. Skipping this produces `DetachedInstanceError` at the caller's access site, nowhere near the real bug.
- Full write-up: [`docs/rules/sqlalchemy-session-handling.md`](docs/rules/sqlalchemy-session-handling.md)

### Feature-Flagged v1 API Surfaces
Agent-workspace v1 surfaces (`sessions_api_v1`, `environments_v1`, `broker_enabled`, `egress_proxy_enabled`, `artifacts_unified_v1`, `webhooks_enabled`) default to **off** and return 404. Enable via `FEATURE_*=true` in `backend/.env`, then **restart** uvicorn (`--reload` won't pick up env vars).
- Full write-up: [`docs/rules/feature-flag-surfaces.md`](docs/rules/feature-flag-surfaces.md)

### LLM Service Usage
Always use `structured_output()` for LLM responses needing structured data:
```python
from omoi_os.services.llm_service import get_llm_service
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    score: float
    summary: str

llm = get_llm_service()
result = await llm.structured_output(prompt="...", output_type=AnalysisResult)
result_dict = result.model_dump(mode='json')  # For JSONB storage
```

### Datetime Handling
Always use `omoi_os.utils.datetime.utc_now()` - never `datetime.utcnow()`.

### Configuration Pattern
- **YAML**: Application settings (version controlled in `config/*.yaml`)
- **.env**: Secrets only (DATABASE_URL, API keys) - never committed

## Testing

Tests use pytest-testmon for smart execution (only affected tests):

```bash
just test              # Fast: affected tests only (~10-30s)
just test-all          # Full suite (~5-10 min)
just test-unit         # Unit tests
just test-integration  # Integration tests
```

Test configuration: `backend/config/test.yaml` (NOT .env)

## Documentation

Key docs for understanding the system:
- `backend/CLAUDE.md` - Comprehensive backend guide
- `docs/product_vision.md` - Complete product vision
- `docs/design/frontend/` - Frontend architecture
- `docs/requirements/monitoring/` - Monitoring architecture

## Subsystems

### spec-sandbox
Lightweight spec execution runtime used by backend:
```python
from spec_sandbox import ...  # Via workspace reference
```

CLI: `spec-sandbox` (see `subsystems/spec-sandbox/`)

## Workflow Orchestration

### 1. Plan Mode Default
- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately - don't keep pushing
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity

### 2. Subagent Strategy
- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents
- One task per subagent for focused execution

### 3. Self-Improvement Loop
- After ANY correction from the user: update `tasks/lessons.md` with the pattern
- Write rules for yourself that prevent the same mistake
- Ruthlessly iterate on these lessons until mistake rate drops
- Review lessons at session start for relevant project

### 4. Verification Before Done
- Never mark a task complete without proving it works
- Diff behavior between main and your changes when relevant
- Ask yourself: "Would a staff engineer approve this?"
- Run tests, check logs, demonstrate correctness

### 5. Demand Elegance (Balanced)
- For non-trivial changes: pause and ask "is there a more elegant way?"
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
- Skip this for simple, obvious fixes - don't over-engineer
- Challenge your own work before presenting it

### 6. Autonomous Bug Fixing
- When given a bug report: just fix it. Don't ask for hand-holding
- Point at logs, errors, failing tests - then resolve them
- Zero context switching required from the user
- Go fix failing CI tests without being told how

## Task Management

1. **Plan First**: Write plan to `tasks/todo.md` with checkable items
2. **Verify Plan**: Check in before starting implementation
3. **Track Progress**: Mark items complete as you go
4. **Explain Changes**: High-level summary at each step
5. **Document Results**: Add review section to `tasks/todo.md`
6. **Capture Lessons**: Update `tasks/lessons.md` after corrections

## Proactive Memory System

This project uses a WAL (Write-Ahead Log) protocol for session continuity. Memory files persist context across sessions so agents don't start from zero.

### Session Start Protocol

At the start of every session, read these files in order:
1. `MEMORY.md` — Project state, active workstreams, architecture decisions
2. `memory/working-buffer.md` — What was happening most recently (WAL target)
3. `tasks/todo.md` — Active work items
4. `tasks/lessons.md` — Patterns to avoid

### During Session

- **WAL Protocol**: When the user makes a correction, decision, or states a preference — write it to `memory/working-buffer.md` BEFORE continuing work. Context vanishes. The buffer won't.
- **Track progress**: Update `tasks/todo.md` as items complete
- **Capture lessons**: When something fails unexpectedly, add the pattern to `tasks/lessons.md`
- **Daily log**: Write significant actions to `memory/YYYY-MM-DD.md`

### Session End Protocol

Before ending a session:
1. Update `memory/working-buffer.md` with current state and next steps
2. Mark completed items in `tasks/todo.md`
3. If new lessons learned: update `tasks/lessons.md`
4. If architecture decisions were made: add to the ADL table in `MEMORY.md`
5. Write daily log entry to `memory/YYYY-MM-DD.md`

### Memory File Structure

```
MEMORY.md                    # Curated long-term project state
memory/
├── working-buffer.md        # Active working memory (WAL target)
└── YYYY-MM-DD.md            # Daily raw capture logs
tasks/
├── todo.md                  # Active work items
└── lessons.md               # Patterns to avoid
```

### Key References

| What | Where |
|------|-------|
| Architecture overview | `ARCHITECTURE.md` |
| Integration gaps | `docs/architecture/14-integration-gaps.md` |
| Live preview plan | `docs/design/live-preview/prototype-plan.md` |
| Backend guide | `backend/CLAUDE.md` |

## Core Principles

- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.

<!-- code-review-graph MCP tools -->
## MCP Tools: code-review-graph

**IMPORTANT: This project has a knowledge graph. ALWAYS use the
code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
the codebase.** The graph is faster, cheaper (fewer tokens), and gives
you structural context (callers, dependents, test coverage) that file
scanning cannot.

### When to use graph tools FIRST

- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
- **Architecture questions**: `get_architecture_overview` + `list_communities`

Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.

### Key Tools

| Tool | Use when |
| ------ | ---------- |
| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
| `get_review_context` | Need source snippets for review — token-efficient |
| `get_impact_radius` | Understanding blast radius of a change |
| `get_affected_flows` | Finding which execution paths are impacted |
| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
| `semantic_search_nodes` | Finding functions/classes by name or keyword |
| `get_architecture_overview` | Understanding high-level codebase structure |
| `refactor_tool` | Planning renames, finding dead code |

### Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use `detect_changes` for code review.
3. Use `get_affected_flows` to understand impact.
4. Use `query_graph` pattern="tests_for" to check coverage.