From 1f273cae3c3d406c1086990b1620fdedcc72318b Mon Sep 17 00:00:00 2001
From: Chris Wanstrath <2+defunkt@users.noreply.github.com>
Date: Tue, 27 Jan 2026 16:59:57 -0800
Subject: [PATCH] toes

---
 CLAUDE.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d338bdc
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# 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