From 2dea6d948f1ba6c0bf0bbac68de5c4cc089c1a84 Mon Sep 17 00:00:00 2001
From: Chris Wanstrath <chris@ozmm.org>
Date: Fri, 30 Jan 2026 18:17:20 -0800
Subject: [PATCH] tools

---
 CLAUDE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 670804d..ea2aeb5 100644
--- a/CLAUDE.md
+++ b/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)