# Toes - Claude Code Guide

## What It Is
Personal web server framework that auto-discovers and runs multiple web apps on your home network. "Set it up, turn it on, forget about the cloud."

## How It Works
1. Host server scans `/apps` directory for valid apps
2. Valid app = has `package.json` with `scripts.toes` entry
3. Each app spawned as child process with unique port (3001+)
4. Dashboard UI shows all running apps with links

## Key Files
- `src/server/apps.ts` - **The heart**: app discovery, process management, lifecycle
- `src/server/index.tsx` - Entry point (minimal, just initializes Hype)
- `src/pages/index.tsx` - Dashboard UI
- `apps/*/package.json` - Must have `"toes": "bun run --watch index.tsx"` script
- `TODO.md` - User-maintained task list (read this!)

## Tech Stack
- **Bun** runtime (not Node)
- **Hype** (custom HTTP framework wrapping Hono) from git+https://git.nose.space/defunkt/hype
- **Forge** (typed CSS-in-JS) from git+https://git.nose.space/defunkt/forge
- TypeScript + Hono JSX

## Running
```bash
bun run --hot src/server/index.tsx  # Dev mode with hot reload
```

## App Structure
```tsx
// apps/example/index.tsx
import { Hype } from 'hype'
const app = new Hype()
app.get('/', c => c.html(<h1>Content</h1>))
export default app.defaults
```

## Conventions
- Apps get `PORT` env var from host
- Each app is isolated process with own dependencies
- No path-based routing - apps run on separate ports
- `DATA_DIR` env controls where apps are discovered

## Current State
- Core infrastructure: ✓ Complete (discovery, spawn, watch, ports, UI)
- Apps: basic, profile (working); risk, tictactoe (empty)
- Check TODO.md for planned features