loom-agent 1.2.0

package/LOOM.md

@@ -0,0 +1,235 @@
+# LOOM.md
+
+## Project Overview
+Loom Code is an AI-powered coding agent for the terminal — multi-provider support (Anthropic, OpenAI, NVIDIA, Google, OpenRouter, Local/Ollama) and a redesigned OpenTUI (SolidJS) terminal interface.
+
+## Build / Run Commands
+- `npm install` — install node dependencies (basic REPL)
+- `bun install` — install all deps including OpenTUI native modules
+- `node src/index.js` — run basic line-mode REPL
+- `bun run src/tui-open.tsx` — launch the new OpenTUI TUI for this project
+- `bun src/tui-open.tsx -p "query"` — one-shot/headless mode
+- `npm run tui` — alias for `bun run src/tui-open.tsx`
+- `npm start` — alias for `node src/index.js`
+- `bun build src/tui-open.tsx --outdir=dist --target=bun` — bundle the TUI
+
+## Test Commands
+- Manual TUI render test: `bun run src/tui-open.tsx` (visual check)
+- Interactive render test: `bun run src/tui/test-interactive.tsx` — verifies splash, slash popup, filtering, Enter execute, modals (asserts included)
+- Headless smoke (no TTY): pipe into `bun src/tui-open.tsx -p "hi"` — requires a valid provider API key
+- No unit test framework configured yet; add `bun test` tests under `src/**/*.test.tsx` using `testRender` from `@opentui/solid`
+
+## Code Style
+- CommonJS (`.js`) for legacy core (session, providers, tools, mcp, config, cli)
+- ES modules + TypeScript (`.ts`, `.tsx`) for the OpenTUI layer — `src/tui/**`, `src/tui-open.tsx`
+- SolidJS signals for state; `@opentui/solid` hooks (`useKeyboard`, `useRenderer`, `useTerminalDimensions`)
+- OpenTUI JSX intrinsics use kebab/underscore names per reconciliation rules:
+  - `<text>`, `<box>`, `<scrollbox>` — layout/display
+  - `<input>`, `<textarea>`, `<select>`, `<tab_select>` — inputs (underscore for `tab_select`)
+- Text styling uses **nested** modifier tags: `<strong>`, `<em>`, `<u>`, `<span fg="...">` — NOT props
+- Colors via palette helpers in `src/tui/theme.ts` (hex strings)
+
+## Architecture — TUI (new, OpenTUI/SolidJS)
+```
+src/tui-open.tsx        Entry point (bun) — render(<App/>)
+src/tui/
+  App.tsx               Root component — layout, keyboard routing, session submit loop, slash commands (command errors surface as toasts, not chat messages)
+  store.ts              SolidJS signals: messages, input, thinking, modal, suggestions, provider state, todos, pets
+  theme.ts              Color palette (loom dark/light), LOOM banner ASCII, VERSION
+  components/
+    SplashScreen.tsx    Full-screen banner + input prompt (shown when no messages)
+    ChatArea.tsx        Message list (user/assistant/tool/system bubbles, thinking indicator) — assistant bubbles render on a slightly darker patch; while the model edits files the view splits: chat left, diff panel right
+    Sidebar.tsx         Right-hand panel: provider, model, tabs (Info/Todos/Files), companion pet
+    InputBar.tsx        Bottom input with slash autocomplete (mouse click/wheel) + status line
+    Modals.tsx          Provider picker, model picker, key input, base-URL editor, confirm dialogs (mouse click/wheel)
+  companion/
+    openpets.ts         Optional OpenPets desktop app bridge (IPC via @open-pets/client)
+    (Companion.tsx lives in components/ — animated pet with blink frames, click reactions, speech bubbles)
+```
+
+The old `src/tui.js` (ink) has been removed. `src/core/cli.js` now spawns `bun src/tui-open.tsx` when TTY + bun available, else falls back to the basic readline REPL.
+
+## Architecture — Core (unchanged)
+```
+src/providers/      anthropic.js, openai.js, nvidia.js, google.js, openrouter.js, local.js
+                    All "OpenAI-compat" providers delegate to providers/openai-compat.js
+                    Base URLs resolved via config/settings.getBaseUrl(provider)
+                    Env overrides: ANTHROPIC_BASE_URL, OPENAI_BASE_URL, NVIDIA_BASE_URL, GOOGLE_BASE_URL, OPENROUTER_BASE_URL
+
+src/core/session.js         Session class — agentic tool loop (up to 50 iterations)
+src/core/model-router.js    Budget router — free/cheap/best/auto level → per-turn model pick
+src/core/usage.js           Usage & billing ledger + monthly spend governor (budgetStatus / setMonthlyBudget)
+src/core/events.js          Sync event bus (turn lifecycle, model:switch, tool calls)
+src/core/session-store.js   Save/load conversations in ~/.loom/sessions
+src/core/permissions.js     bash/edit/write permission gating
+src/core/plugin-cmd.js      /skills, /mcp, /diff, /debug, /editor, /export, /sessions, /fork handlers
+src/config/settings.js      ~/.loom/config.json persistence, API key + base URL helpers
+src/tools/index.js          read/write/edit/bash/grep/glob/webfetch/todowrite + MCP passthrough
+src/mcp/                    MCP client + manager (stdio servers)
+src/skills/                 Skill install/remove/list from ~/.loom/skills
+```
+
+## Companion Pet System
+- **5 built-in pets**: Cat, Robot, Fenrir (wolf), Luma (firefly), OpenPets (desktop sync)
+- **Animation**: 700ms blink interval, idle/thinking/working/happy/sleep poses, random phrases
+- **Interaction**: Click pet → celebrating mood + hearts counter + speech bubble
+- **Event-driven moods**: `notifyPet({ mood: "working"|"success"|"error"|"celebrating" ... })` called from chat lifecycle
+- **OpenPets desktop sync** (optional): `@open-pets/client` IPC bridge at `src/tui/companion/openpets.ts`
+  - Reactions: idle, thinking, working, editing, running, testing, waiting, waving, success, error, celebrating
+  - Auto-discovers desktop app via `%APPDATA%\OpenPets\runtime\ipc.json` (Win) or `~/.config/OpenPets/runtime/ipc.json` (Linux)
+  - Graceful no-op when desktop app not running
+- `/companion` opens picker modal; selection persisted to `~/.loom/tui.json`
+- Settings `[e]` toggles OpenPets sync on/off
+
+## Slash Commands (39 total)
+| Command | Args | Description |
+|---------|------|-------------|
+| `/help` | — | Show this help dialog |
+| `/build` | — | Build mode — full agent tools (all tools, executes changes) |
+| `/plan` | — | Plan mode — read-only analysis; model gets only read/glob/grep/webfetch/todowrite, mutations blocked by an execute guard; ends with "Plan complete — Tab to Build, send 'go'" |
+| `/chat` | — | Chat mode — conversation only, zero tools |
+| `/connect` | `[provider]` | Add/connect a provider (opens picker if no arg) |
+| `/key` | — | Edit API key for current provider |
+| `/baseurl` | `[provider] [url]` | Set provider base URL |
+| `/model` | `[model-id]` | Pick active model (or open picker) |
+| `/models` | — | List available models (grouped by provider) |
+| `/providers` | — | List supported providers |
+| `/status` | — | Show connection status (provider, model, key) |
+| `/usage` | — | Show token usage and billing breakdown (session + lifetime + monthly budget) |
+| `/budget` | `[level \| $]` | Budget routing — `free`/`cheap`/`best`/`auto`, or a dollar cap (`/budget 50`). Over-cap blocks paid turns (`/budget free` is the escape hatch) |
+| `/new` | — | Start a new session |
+| `/clear` | — | Clear the chat |
+| `/compact` | — | Compact conversation (keep last 10) |
+| `/restore` | — | Restore a snapshot point |
+| `/undo` | — | Undo last exchange |
+| `/redo` | — | Redo last undone exchange |
+| `/reset` | — | Reset the session |
+| `/settings` | — | Toggle details/thinking/sidebar/OpenPets |
+| `/sessions` | — | Browse saved sessions |
+| `/share` | — | Export the current session to JSON |
+| `/export` | — | Export to markdown |
+| `/thinking` | — | Toggle thinking visibility |
+| `/details` | — | Toggle tool detail visibility |
+| `/theme` | — | Theme picker (live switch + persist) |
+| `/permissions` | — | Saved permission rules (view / reset) |
+| `/editor` | — | Open external editor (LOOM.md) |
+| `/diff` | — | Show git diff |
+| `/init` | — | Create LOOM.md |
+| `/memory` | — | Show memory file locations |
+| `/doctor` | — | Run diagnostics |
+| `/skills` | `install <dir\|git> \| remove <name>` | Manage skills (`/skills install <path-or-url> [name]`, `/skills remove <name>`, `/skills help`) |
+| `/mcp` | `add <name> <cmd> \| remove \| toggle` | Manage MCP servers (`/mcp add <name> <command> [args...]`, `/mcp remove <name>`, `/mcp toggle <name>`, `/mcp help`) |
+| `/debug` | — | Show debug info |
+| `/fork` | — | Fork conversation |
+| `/companion` | — | Change your companion pet |
+| `/exit` | — | Quit Loom Code |
+
+### Leader Key (Ctrl+X)
+| Key | Slash Command |
+|-----|---------------|
+| `c` | `/compact` |
+| `e` | `/editor` |
+| `q` | `/exit` |
+| `x` | `/export` |
+| `h` | `/help` |
+| `m` | `/models` |
+| `n` | `/new` |
+| `r` | `/redo` |
+| `l` | `/sessions` |
+| `u` | `/undo` |
+| `s` | `/settings` |
+| `t` | `/thinking` |
+| `d` | `/details` |
+| `b` | `/build` |
+| `p` | `/plan` |
+
+### Autocomplete
+- **Slash (`/`)** — live-filtered commands with descriptions, 10-row scrollable window over the full list, UP/DOWN/TAB/ENTER/ESC
+- **At (`@`)** — fuzzy file search (project files, top 10)
+- **Bang (`!`)** — shell presets (`!ls -la`, `!git status`, `!git diff`, `!pwd`)
+- **Mouse** — click a suggestion row to select + execute it; scroll wheel scrolls through the full list and moves the selection (also in modals: provider/model/companion pickers + palette — model picker shows "showing N-M of X" range)
+
+### Keyboard Shortcuts
+| Keys | Action |
+|------|--------|
+| `Enter` | Submit prompt / pick autocomplete |
+| `Esc` | Interrupt thinking / close modal / clear input |
+| `Ctrl+C` | Exit TUI (clean terminal restore) |
+| `Ctrl+B` | Toggle sidebar |
+| `Ctrl+P` | Command palette (type to filter) |
+| `Ctrl+X` | Leader prefix (3s timeout) |
+| `Ctrl+I` | Cycle sidebar tab (Info/Todos/Files) |
+| `Tab` | Cycle autocomplete / cycle input mode (Build/Plan/Chat) |
+| `Up/Down` | Navigate autocomplete / suggestion list |
+| `Mouse wheel` | Scroll chat history (scrollbox) / move suggestion + modal selection |
+| `Mouse click` | Run a suggestion or modal option (autocomplete, pickers, palette) |
+
+## Configuration Format
+`~/.loom/config.json`:
+```json
+{
+  "provider": "nvidia",
+  "model":    { "nvidia": "deepseek-ai/deepseek-v4-flash", "anthropic": "claude-sonnet-4-20250514" },
+  "apiKeys":  { "nvidia": "..." },
+  "baseUrls": { "nvidia": "https://integrate.api.nvidia.com/v1" },
+  "maxTokens": 8192,
+  "temperature": 0.7
+}
+```
+
+## TUI State Persistence
+`~/.loom/tui.json`:
+```json
+{
+  "sidebarVisible": true,
+  "showToolDetails": false,
+  "showThinking": true,
+  "companion": "cat",
+  "openPetsSync": false,
+  "petEnabled": true
+}
+```
+
+## Native Modules Note
+`@opentui/core` ships per-platform native packages (`@opentui/core-win32-x64`, `-darwin-arm64`, etc.).
+Install the one matching the host OS — npm/bun install will pull them automatically when flagged in
+`optionalDependencies`. `bun build` may warn about missing *other* platforms; that is expected.
+
+## Notes for the Coding Agent
+- Always use `bun run src/tui-open.tsx` to drive the UI; never edit the old `tui.js` (gone)
+- When adding a new slash command:
+  1. Register in `src/tui/store.ts` (`SLASH_LIST`)
+  2. Add a `case "cmdname":` block in `src/tui/App.tsx` (`processSlash`)
+  3. If it opens a picker, add a modal handler in `src/tui/components/Modals.tsx`
+- To add a provider: drop a file in `src/providers/`, register in `providers/index.js` (`PROVIDERS`, `PROVIDER_ORDER`, `PROVIDER_LABELS`), add its base URL default to `config/settings.js`
+- Run deterministic checks with `bun -e "..."` or `bun build` before pushing UI changes
+- **Critical**: All signal reads MUST be inside JSX expressions (`{signal()}`) or `<Show when={signal()}>` — top-level `const s = signal()` captures once and never updates
+
+## SolidJS Reactivity Pattern (MUST FOLLOW)
+```tsx
+// WRONG — captures once, never updates
+const s = suggestions();
+
+// CORRECT — read inside JSX
+<Show when={suggestions().length > 0 && autoKind() === "slash"}>
+  {suggestions().slice(0, 4).map(...)}
+</Show>
+```
+
+This pattern applies to ALL components: InputBar, Companion, Sidebar, BreadcrumbBar, ChatArea, Modals.
+
+### Passing props to children
+Pass **accessor functions**, not resolved values, for reactive props. Component bodies
+run once (untracked), so `const msgs = props.messages` in a child body captures a stale value.
+
+```tsx
+// WRONG — child body reads props.messages once, never updates
+<ChatArea messages={messages()} />
+
+// CORRECT — child calls the accessor inside JSX
+<ChatArea messages={messages} />
+// in ChatArea: const visible = () => (props.messages?.() || []).slice(-40); ... {visible().map(...)}
+```
+
+Boolean/static props may stay as values (`show={sidebarVisible()}` is fine when read inside
+`<Show when={...}>` or another JSX expression).

package/README.md

@@ -0,0 +1,433 @@
+# Loom Code
+
+[![npm version](https://img.shields.io/npm/v/loom-code?style=flat&color=blue)](https://npmjs.com/loom-code)
+[![License: MIT](https://img.shields.io/npm/l/loom-code?style=flat&color=green)](LICENSE)
+[![Platform: Win/Mac/Linux](https://img.shields.io/badge/terminal-Win%20%7C%20Mac%20%7C%20Linux-orange)](#)
+
+An AI-powered coding agent for the terminal with multi-provider support and a full terminal UI.
+
+## Features
+
+- Full OpenTUI interface with slash commands, autocomplete, and ESC-to-interrupt
+- Build / Plan / Chat modes 
+- OpenCode-style agents — primary agents (`build`/`plan`/`chat`) plus delegating subagents (`explore`, `scout`, `general`) invoked automatically via the `task` tool or manually via `@agent` mentions
+- LOOM.md project memory file 
+- Multi-provider: Anthropic, OpenAI, NVIDIA, Google Gemini, OpenRouter, Local (Ollama)
+- Built-in tools: read, write, edit, bash, grep, glob, webfetch, todowrite
+- Agentic tool loop (multiple tool calls per turn)
+- MCP (Model Context Protocol) server integration
+- Drag-to-copy selections, paste support
+- Session memory, /undo, /redo, /compact, /reset, /fork
+- One-shot print mode: `loom -p "query"`
+- Editor integration via the Agent Client Protocol (ACP): `loom acp` (JSON-RPC over stdio) so Zed, JetBrains, and Neovim plugins can drive Loom as their coding agent
+- Browser interface via `loom web` — a zero-dependency Node HTTP server (chat in the browser, password auth, CORS) plus `loom attach` to share the same server from the terminal; optional mDNS advertising as `loom.local` via [bonjour-service](https://www.npmjs.com/package/bonjour-service)
+- Usage & billing tracking per session + lifetime
+
+## Prerequisites
+
+- **[bun](https://bun.sh) >= 1.0** (required for the full TUI). Without bun, only the line-mode REPL runs.
+- **Node.js >= 18** (for non-TUI mode and package scripts)
+- **An API key** from at least one provider:
+
+| Provider | Sign-up | Key type |
+|----------|---------|----------|
+| Anthropic | [console.anthropic.com](https://console.anthropic.com) | Claude API key |
+| OpenAI | [platform.openai.com](https://platform.openai.com) | API key |
+| NVIDIA | [build.nvidia.com](https://build.nvidia.com) | NIM API key (free tier available) |
+| Google | [aistudio.google.com](https://aistudio.google.com) | Gemini API key (free tier available) |
+| OpenRouter | [openrouter.ai](https://openrouter.ai) | OpenRouter API key |
+| Local | Install [Ollama](https://ollama.com) | No key needed (runs locally) |
+
+Install from npm (global — installs the `loom` command):
+```bash
+npm install -g loom-code
+```
+
+Or run from source:
+```bash
+npm install -g .
+# or
+npm link
+```
+
+## Setup
+
+1. **Install bun** (for the full TUI):
+   ```bash
+   # macOS / Linux
+   curl -fsSL https://bun.sh/install | bash
+
+   # Windows
+   powershell -c "irm bun.sh/install.ps1 | iex"
+   ```
+
+2. **Configure API keys** — pick one method:
+   ```bash
+   # a) Environment variables (.env)
+   cp .env.example .env
+   # Edit .env with your key:
+   # ANTHROPIC_API_KEY=sk-ant-...
+   # NVIDIA_API_KEY=nvapi-...
+   # OPENAI_API_KEY=sk-...
+
+   # b) Interactive setup in the TUI
+   loom
+   > /connect nvidia
+   ```
+
+3. **Initialize project memory** (optional):
+   ```bash
+   loom
+   > /init
+   ```
+   Creates `LOOM.md` with a project-specific template.
+
+## Usage
+
+```bash
+loom                              # interactive TUI session
+loom "explain this project"       # start with initial prompt
+loom -p "list files in src/"      # one-shot, print result, exit
+cat logs.txt | loom -p "explain"  # analyze piped content
+loom --version
+loom --help
+loom --basic                      # skip TUI, use line-mode REPL
+loom acp                          # ACP subprocess mode for editor integrations
+loom web                          # browser interface (HTTP server, opens browser)
+loom attach http://localhost:4096 # attach the terminal to a running loom web
+```
+
+## Web
+
+Loom runs in your browser with `loom web` — a zero-dependency HTTP server that
+serves a single-page UI and drives the same core session loop as the TUI. Same
+providers/models, tools, MCP servers, and saved sessions; chat streams live in
+the browser, and a shared terminal client can attach to the same server.
+
+```bash
+loom web                           # 127.0.0.1, random port, opens the browser
+loom web --port 4096               # fixed port
+loom web --hostname 0.0.0.0        # reachable on the LAN
+loom web --mdns                    # advertise as loom.local (implies 0.0.0.0)
+loom web --mdns-domain proj.local  # custom mDNS domain
+loom web --cors https://example.com
+LOOM_SERVER_PASSWORD=secret loom web   # password-protect (user: LOOM_SERVER_USERNAME, default "loom")
+
+# Attach the terminal (shares the server's sessions/state):
+loom attach http://localhost:4096
+```
+
+Config-file equivalent (`~/.loom/config.json`): `{ "server": { "port": 4096,
+"hostname": "0.0.0.0", "mdns": true, "cors": ["https://example.com"] } }` — CLI
+flags take precedence. Full flags, the JSON API, and `loom attach` options are
+documented in **[docs/web.md](docs/web.md)**.
+
+## Editor integration (ACP)
+
+Loom implements the [Agent Client Protocol (ACP)](https://agentclientprotocol.com)
+as `loom acp` — a JSON-RPC-over-stdio subprocess server that any ACP-compatible
+editor can launch, the same mechanism opencode uses with Zed. Zed, JetBrains,
+and Neovim (Avante.nvim / CodeCompanion.nvim) all support ACP agents; you only
+configure the agent command `loom acp`, then chat from the editor while Loom
+runs real tools in your repo.
+
+Zed (add to `~/.config/zed/settings.json`, then Command Palette → `agent: new thread`):
+
+```json
+{
+  "agent_servers": {
+    "Loom Code": { "type": "custom", "command": "loom", "args": ["acp"], "env": {} }
+  }
+}
+```
+
+Full transport spec, JetBrains/Neovim configs, the protocol walkthrough, and a
+self-test client (`node scripts/acp-smoke.js`) live in **[docs/acp.md](docs/acp.md)**.
+
+## Slash Commands (35 total)
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `/help` | — | Show all commands |
+| `/build` | — | Build mode — all tools |
+| `/plan` | — | Plan mode — read-only analysis |
+| `/chat` | — | Chat mode — no tools |
+| `/agents` | — | List primary agents and subagents |
+| `/connect` | `[provider]` | Add/connect a provider |
+| `/key` | — | Edit API key for current provider |
+| `/baseurl` | `[provider] [url]` | Set provider base URL |
+| `/model` | `[model-id]` | Pick active model |
+| `/models` | — | List available models |
+| `/providers` | — | List supported providers |
+| `/status` | — | Show connection status |
+| `/usage` | — | Show token usage and billing |
+| `/new` | — | Start a new session |
+| `/clear` | — | Clear the chat |
+| `/compact` | — | Compact conversation |
+| `/undo` | — | Undo last exchange |
+| `/redo` | — | Redo last undone exchange |
+| `/reset` | — | Reset the session |
+| `/settings` | — | Toggle details/sidebar/etc. |
+| `/sessions` | — | Browse saved sessions |
+| `/share` | — | Export current session to JSON |
+| `/export` | — | Export to markdown |
+| `/thinking` | — | Toggle thinking visibility |
+| `/details` | — | Toggle tool detail visibility |
+| `/init` | — | Create LOOM.md |
+| `/memory` | — | Show memory files |
+| `/doctor` | — | Run diagnostics |
+| `/skills` | `install\|remove` | Manage skills |
+| `/mcp` | `add\|remove\|toggle` | Manage MCP servers |
+| `/debug` | — | Show debug info |
+| `/fork` | — | Fork conversation |
+| `/exit` | — | Quit Loom Code |
+
+## Keybindings
+
+Every key is configurable from `~/.loom/tui.json` (`keybinds`, `leader`,
+`leader_timeout`) — see [docs/keybinds.md](docs/keybinds.md) for the full
+action list, syntax, and opencode-compatible aliases. The defaults:
+
+| Key | Action |
+|-----|--------|
+| **ESC** | Interrupt current operation (aborts API requests) / close dialogs / clear the draft |
+| **Ctrl+C** | Exit (copies a text selection first) |
+| **Ctrl+B** | Toggle sidebar (file browser) |
+| **Ctrl+P** | Open command palette |
+| **Ctrl+X** | Leader key — the next key runs a leader binding |
+| **Ctrl+X** then **b / p** | Build mode / Plan mode |
+| **Ctrl+X** then **n / l / x / c** | New session / sessions list / export / compact |
+| **Ctrl+X** then **m / a / h / e** | Model picker / agents / help / editor |
+| **Ctrl+X** then **q** | Quit |
+| **Tab** | Next suggestion, or cycle mode (Build → Plan → Chat) |
+| **Ctrl+A** | Select the whole draft (readline-style) |
+| **Shift+Enter** | Insert a newline in the draft |
+
+## Agents
+
+Loom Code agent architecture: the user talks to a
+**primary agent** (picked by the active mode), and that primary can delegate
+focused work to **subagents** — either **automatically**, by calling the `task`
+tool when a subtask warrants it, or **manually**, when you prefix a message with
+`@agent`.
+
+### Primaries (matched to your mode)
+
+| Agent | Mode | Tools | Role |
+|-------|------|-------|------|
+| `build` | Build | all tools (`*`) | Full development work — editing, shell, anything. |
+| `plan`  | Plan  | read-only + `task` | Analyze and produce an ordered plan. Never edits files or runs shell commands; delegates heavy investigation to subagents. |
+| `chat`  | Chat  | none              | Conversation only. |
+
+### Subagents (delegated to via the `task` tool or `@agent` mentions)
+
+| Agent | Tools | Role |
+|-------|-------|------|
+| `explore` | read-only, minus `task` | Fast read-only codebase exploration: search symbols, read files, list files. Never modifies anything and never delegates (no recursion). |
+| `scout`   | `read`, `glob`, `grep`, `webfetch` | External research: fetch docs, check APIs and dependencies. Read-only. |
+| `general` | all tools, minus `task` | General-purpose autonomous subagent for self-contained implementation tasks, bug fixes, and multi-step work. |
+
+Every subagent is **read-only or sandboxed** and **cannot delegate further**
+(subagents never get the `task` tool), so delegation always terminates.
+
+### Two ways to invoke a subagent
+
+1. **Automatic — the main agent calls `task` itself.** When a turn would
+   benefit from a focused subagent (e.g. a fast read-only sweep before editing),
+   the primary calls the `task` tool with an agent id and a prompt. Progress
+   streams into a dedicated panel in the chat:
+
+   ```
+   ┌ @explore  finished · done ─────────────┐
+   │ │ grep · read                          │
+   │ child findings…                        │
+   └────────────────────────────────────────┘
+   ```
+
+2. **Manual — `@agent` mentions.** Prefix your message with `@agent` to force
+   the whole turn onto that subagent:
+
+   ```
+   @explore find the bug
+   @scout what's the latest Stripe API for refunds?
+   ```
+
+   The `@agent` prefix is stripped from the user bubble shown in chat, so only
+   your query renders. Type `@` to open an autocomplete of available subagents.
+
+### Listing, configuring, and extending agents
+
+- **`/agents`** — prints the active registry (id, mode, tool set, model).
+- **Custom subagents** — add to `~/.loom/config.json`:
+
+  ```json
+  {
+    "agents": {
+      "reviewer": {
+        "mode": "subagent",
+        "description": "Reads diffs and flags risky changes before commit.",
+        "tools": ["read", "glob", "grep", "diff"],
+        "prompt": "You are a cautious code reviewer. Read the diff and list risk points.",
+        "model": "anthropic/claude-sonnet-4-20250514"
+      },
+      "explore": { "disable": true }
+    }
+  }
+  ```
+
+  Custom `mode: "subagent"` entries need a `description`; built-ins can be
+  disabled with `"disable": true`. Tool patterns use last-match-wins semantics:
+  `["*"]` (all), `["read","glob"]` (only those), `["*","!task"]` (all except
+  delegation), `["mcp__*"]` (wildcards).
+
+## Troubleshooting
+
+### "bun not found — full TUI requires bun"
+Install bun from [bun.sh](https://bun.sh). If bun is already installed but not found, add `~/.bun/bin` to your `PATH`.
+
+### "API key is invalid or expired"
+Run `/connect <provider>` in the TUI and paste a new key. For environment variables, check your `.env` file.
+
+### "403 Forbidden: the API key is not authorized"
+Your key doesn't have access to the selected model. Some providers (especially NVIDIA NIM and OpenRouter) require accepting model terms on their website first.
+
+### "402 quota exceeded"
+Your API billing tier or rate limit has been reached. Upgrade your plan or switch to a different provider.
+
+### TUI is slow or flickering
+Try launching with `--basic` to use the line-mode REPL instead, which is lighter.
+
+## Project Structure
+
+```
+LoomCode/
+├── bin/
+│   ├── loom.js              # CLI entry point
+│   ├── loomcode.js          # Alternative binary name
+│   └── loom-tui.js          # TUI launcher
+├── src/
+│   ├── index.js             # Bootstraps CLI
+│   ├── core/
+│   │   ├── cli.js           # Interactive REPL + slash commands
+│   │   ├── session.js       # Conversation + agent tool loop
+│   │   ├── agents.js        # agent registry + subagent runner
+│   │   ├── permissions.js   # Command permission checks
+│   │   ├── platform.js      # OS/platform detection
+│   │   ├── session-store.js # Persisted sessions
+│   │   ├── restore.js       # Snapshot/restore project file tree
+│   │   ├── usage.js         # Token/cost tracking
+│   │   └── plugin-cmd.js    # Subcommand backend
+│   ├── providers/
+│   │   ├── index.js         # ProviderRouter dispatch
+│   │   ├── openai-compat.js # OpenAI-compatible provider base
+│   │   ├── anthropic.js     # Anthropic Claude connector
+│   │   ├── openai.js        # OpenAI GPT connector
+│   │   ├── nvidia.js        # NVIDIA NIM connector
+│   │   ├── google.js        # Google Gemini connector
+│   │   ├── openrouter.js    # OpenRouter connector
+│   │   ├── local.js         # Local (Ollama) connector
+│   │   └── custom.js        # Custom provider host
+│   ├── tools/
+│   │   └── index.js         # read/write/edit/bash/grep/glob/webfetch/todowrite/task
+│   ├── config/
+│   │   ├── settings.js      # ~/.loom/config.json persistence
+│   │   └── provider-cmd.js  # /connect command logic
+│   └── tui/
+│       ├── App.tsx           # OpenTUI root component
+│       ├── store.ts          # SolidJS reactive store
+│       ├── theme.ts          # Theme / palette
+│       ├── components/
+│       │   ├── InputBar.tsx  # Chat input + autocomplete
+│       │   ├── ChatArea.tsx  # Message list
+│       │   ├── BreadcrumbBar.tsx  # Mode + provider bar
+│       │   ├── Modals.tsx    # Settings pickers
+│       │   └── Sidebar.tsx   # File sidebar
+├── package.json
+├── LOOM.md                    # Developer reference
+└── .gitignore
+```
+
+## Configuration
+
+Config is stored at `~/.loom/config.json` (permissions: 0600). Includes:
+- `provider` — default LLM provider
+- `model` — per-provider model IDs (editable in source or via `/model`)
+- `apiKeys` — API keys from `/connect` or manual edit
+- `baseUrls` — custom provider endpoints
+- `maxTokens`, `temperature` — model settings
+- `permission` — OpenCode-style permission tree (see below)
+- `permissionRules` — rules saved from the permission popup ("Always allow"/"Never")
+
+API keys can also be set via environment variables: `.env` or `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `NVIDIA_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY` etc.
+
+## Permissions
+
+Every tool call resolves through an OpenCode-style permission tree, so you can
+allow or block specific tools, commands, and file patterns without retyping a
+prompt each time. The last matching rule wins; `*` matches any run of
+characters and `?` a single one, and `~`/`$HOME` are expanded in paths.
+
+```jsonc
+{
+  "permission": {
+    "bash": {
+      "*": "allow",                    // allow shell commands...
+      "git push --force": "deny"       // ...except destructive ones
+    },
+    "edit": { "*": "ask", "src/**": "allow" },
+    "read": {
+      "*": "allow",
+      "*.env": "deny",                 // secrets stay off-limits by default
+      "*.env.example": "allow"
+    },
+    "external_directory": "ask"        // reads/writes outside the project dir
+  }
+}
+```
+
+Available permission keys: `read`, `edit` (covers edit/write), `glob`, `grep`,
+`bash`, `task`, `skill`, `lsp`, `question`, `webfetch`, `websearch`,
+`external_directory` (paths outside the working directory), and `doom_loop`
+(three identical tool calls in a row). Most tools default to `allow`;
+`edit`/`bash`/`task`/`skill`/`external_directory`/`doom_loop` default to `ask`,
+and `read` denies `*.env`/`*.env.*` files (except `*.env.example`).
+
+When the model asks for permission, the TUI popup offers Allow, Always allow,
+Deny, or a typed answer. "Always allow"/"Never" persist a rule to
+`permissionRules`. Run `loom --auto` (or `/permissions auto` in the TUI, or
+Ctrl+P → the palette) to auto-approve `ask` results — explicit `deny` rules
+still block. A muted `auto` indicator appears in the status row while enabled.
+
+Per-agent overrides live in the agent's own config
+(`agent.<id>.permission`, same shape, applied on top of the global tree):
+
+```jsonc
+{
+  "agent": {
+    "explore": { "mode": "subagent", "permission": { "edit": "deny" } }
+  }
+}
+```
+
+## Adding a New Provider
+
+Register in `src/providers/<name>.js` exporting `{ chat, stream, models }`:
+
+```js
+async function chat(messages, options) {
+  // call API, return { content: '...', toolCalls: [{...}], usage: {{...}} }
+}
+async function stream(messages, options, onDelta) {
+  // stream response, return { content, toolCalls, usage }
+}
+const models = [
+  { id: 'my-model', name: 'My Model', provider: 'myname', context: 128000, priceIn: 0.50, priceOut: 2.00 }
+];
+module.exports = { chat, stream, models };
+```
+
+Then add it in `src/providers/index.js` under `PROVIDERS`.
+
+## License
+
+MIT