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

Coding Guidelines

TS files should be organized in the following way:

• imports
• re-exports
• const/lets
• enums
• interfaces
• types
• classes
• functions
• module init (top level function calls)

In each section, put the exports first, in alphabetical order.

Then, after the exports (if there were any), put everything else, also in alphabetical order.

For single-line functions, use const fn = () => {} and put them in the "functions" section of the file.

All other functions use the function blah(){} format.

Example:

import { code } from "coders"
import { something } from "somewhere"

export type { SomeType }

const RETRY_TIMES = 5
const WIDTH = 480

enum State {
  Stopped,
  Starting,
  Running,
}

interface Config {
  name: string
  port: number
}

type Handler = (req: Request) => Response

class App {
  config: Config

  constructor(config: Config) {
    this.config = config
  }
}

const isApp = (name: string) =>
  apps.has(name)

function createApp(name: string): App {
  const app = new App({ name, port: 3000 })
  apps.set(name, app)
  return app
}

function start(app: App): void {
  console.log(`Starting ${app.config.name}`)
}