tools

CLAUDE.md

@@ -48,6 +48,51 @@ Personal web appliance that auto-discovers and runs multiple web apps on your ho
 - `apps/*/package.json` - Must have `"toes": "bun run --watch index.tsx"` script
 - `TODO.txt` - Task list
 
+## Tools
+
+Tools are special apps that appear as tabs in the dashboard rather than standalone entries in the sidebar. They integrate directly into the Toes UI and can interact with the currently selected app.
+
+### Creating a Tool
+
+Add `toes.tool` to your app's `package.json`:
+
+```json
+{
+  "toes": {
+    "icon": "🔧",
+    "tool": true
+  },
+  "scripts": {
+    "toes": "bun run --watch index.tsx"
+  }
+}
+```
+
+### How Tools Work
+
+- Tools run as regular apps (spawned process with unique port)
+- Displayed as iframes overlaying the tab content area
+- Receive `?app=<name>` query parameter for the currently selected app
+- Iframes are cached per tool+app combination (never recreated once loaded)
+- Tool state persists across tab switches
+
+### CLI Flags
+
+```bash
+toes list           # Lists regular apps only (excludes tools)
+toes list --tools   # Lists tools only
+toes list --all     # Lists all apps including tools
+```
+
+### Tool vs App
+
+| Aspect | Regular App | Tool |
+|--------|-------------|------|
+| `toes.tool` | absent/false | true |
+| UI location | Sidebar | Tab bar |
+| Rendering | New browser tab | Iframe in dashboard |
+| Context | Standalone | Knows selected app via query param |
+
 ## Tech Stack
 
 - **Bun** runtime (not Node)