toes/CLAUDE.md

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 apps with current status, logs, and 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

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

App Structure

// 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