@skaft/hamr 0.4.1

package/docs/usage.md

@@ -0,0 +1,305 @@
+# Using Pi
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model
+
+The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
+
+### Editor Features
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
+
+See [Keybindings](keybindings.md) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| `/model` | Switch models |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Thinking level, theme, message delivery, transport |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session file, ID, messages, tokens, and cost |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit hamr |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **Alt+Up** retrieves queued messages back to the editor.
+
+On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want hamr to receive the shortcut.
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.hamr/agent/sessions/`, organized by working directory.
+
+```bash
+hamr -c                  # Continue most recent session
+hamr -r                  # Browse and select a session
+hamr --no-session        # Ephemeral mode; do not save
+hamr --name "my task"    # Set session display name at startup
+hamr --session <path|id> # Use a specific session file or session ID
+hamr --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `/session` shows the current session file and ID.
+- `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/fork` creates a new session from an earlier user message.
+- `/clone` duplicates the current active branch into a new session file.
+- `/compact` summarizes older messages to free context.
+
+See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+
+## Context Files
+
+Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.hamr/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.hamr/SYSTEM.md` for a project
+- `~/.hamr/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+### Project Trust
+
+On interactive startup, hamr asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.hamr/agent/trust.json`. Trusting a project allows hamr to load `.hamr/settings.json` and `.hamr` resources, install missing project packages, and execute project extensions.
+
+Before the trust decision, hamr loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.hamr/agent/settings.json`, or change it with `/settings`.
+
+`hamr config` and package commands use the same project trust flow, except `hamr update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+
+Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.hamr/agent/trust.json` only; the current session is not reloaded, so restart hamr for changes to take effect.
+
+
+## Exporting and Sharing Sessions
+
+Use `/export [file]` to write a session to HTML.
+
+Use `/share` to upload a private GitHub gist with a shareable HTML link.
+
+If you use hamr for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
+
+## CLI Reference
+
+```bash
+hamr [options] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+hamr install <source> [-l]     # Install package, -l for project-local
+hamr remove <source> [-l]      # Remove package
+hamr uninstall <source> [-l]   # Alias for remove
+hamr update [source|self|hamr]   # Update hamr and packages; reconcile pinned git refs
+hamr update --extensions       # Update packages only; reconcile pinned git refs
+hamr update --self             # Update hamr only
+hamr update --extension <src>  # Update one package
+hamr list                      # List installed packages
+hamr config                    # Enable/disable package resources
+```
+
+These commands manage hamr packages, not the hamr CLI installation. To uninstall hamr itself, see [Quickstart](quickstart.md#uninstall). `hamr config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `hamr update` never prompts for project trust.
+
+See [Pi Packages](packages.md) for package sources and security notes.
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| default | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, hamr also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | hamr -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path\|id>` | Use a specific session file or partial UUID |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, extension, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
+| `--no-extensions` | Disable extension discovery |
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+hamr --no-extensions -e ./my-extension.ts
+```
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--verbose` | Force verbose startup |
+| `-a`, `--approve` | Trust project-local files for this run |
+| `-na`, `--no-approve` | Ignore project-local files for this run |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+hamr @prompt.md "Answer this"
+hamr -p @screenshot.png "What's in this image?"
+hamr @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+hamr "List all .ts files in src/"
+
+# Non-interactive
+hamr -p "Summarize this codebase"
+
+# Non-interactive with piped stdin
+cat README.md | hamr -p "Summarize this text"
+
+# Named one-shot session
+hamr --name "release audit" -p "Audit this repository"
+
+# Different model
+hamr --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+hamr --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+hamr --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+hamr --models "claude-*,gpt-4o"
+
+# Read-only mode
+hamr --tools read,grep,find,ls -p "Review the code"
+
+# Disable one extension or built-in tool while keeping the rest available
+hamr --exclude-tools ask_question
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.hamr/agent` |
+| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
+| `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
+| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
+| `PI_SKIP_VERSION_CHECK` | Skip the Hamr version update check at startup. This prevents npm latest-version requests and Hamr fallback metadata requests |
+| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
+| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
+| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
+
+## Design Principles
+
+Hamr keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+
+It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+
+For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/docs/visual-parity-handoff.md

@@ -0,0 +1,110 @@
+# Visual Parity Handoff — hamr vs synax
+
+**Date:** 2026-06-17
+**Branch:** `feat/finish-hamr-restructure`
+**Goal:** Make hamr's default TUI indistinguishable from synax `@skaft/hamr`
+
+---
+
+## ✅ Completed (this session)
+
+### Bug B — Splash refreshes on model change
+- **File:** `src/modes/interactive/interactive-mode.ts`
+- Added `splashRendered: boolean` and `splashRenderedModelKey: string` tracking fields (lines 272-273)
+- `renderSplashScreen()` (line ~1688) sets these after rendering
+- Added `refreshSplashIfLive()` method (~line 1770): compares current model key to cached key; if different, clears `chatContainer` and re-renders splash
+- Hooked into `updateEditorBorderColor()` (line ~3656) so every model switch or thinking-level change refreshes the splash
+
+### Bug C — PROMPT cards with per-model glyph + brand color
+- **File:** `src/modes/interactive/components/user-message.ts`
+- Rewrote `UserMessageComponent`: now accepts `modelAccent?` (hex) and `modelGlyph?` (string)
+- Renders `{glyph} PROMPT` heading in model brand color when `modelAccent && theme.modelAdaptive`, theme accent otherwise
+- Always shows the heading when `modelGlyph` is available — user can see which model was prompted even after model switches
+- `interactive-mode.ts`: `addMessageToChat()` captures `modelAccent` + `modelGlyph` from session model at call time, passes to both UserMessageComponent and AssistantMessageComponent
+
+### Bug D — Emoji glyph auto-detection
+- **File:** `src/modes/interactive/theme/theme.ts`
+- Added `detectGlyphTier()` (line ~270): auto-detects terminal capability
+  - Emoji: iTerm2, Apple Terminal, Kitty, Ghostty, WezTerm, Warp, Tabby, Hyper, VS Code, Cursor, Windsurf, xterm-kitty
+  - Nerd: Alacritty, Rio, truecolor/24bit COLORTERM
+  - Unicode: fallback for everything else
+  - Ascii: dumb TERM or NO_COLOR=1
+- `HAMR_EMOJI_MODEL_GLYPHS` / `HAMR_NERD_FONT` env vars act as overrides (opt-up)
+- `modelGlyph()` now uses `getGlyphTier()` instead of hardcoded env-var precedence
+
+### Bug G — Dashboard model-adaptive color
+- **File:** `src/hamr/dashboard.ts`
+- Header "⚒ Hamr Dashboard" and "Commands" section title now use model brand color when `theme.modelAdaptive` is on
+- Falls back to theme accent when modelAdaptive is off
+
+### Bug E — (prior session) Removed duplicate Working indicator
+- Removed in-feed loader creation from two sites in interactive-mode.ts
+- Footer's independent `animationTimer` for rainbow "Working..." was verified safe
+
+### Bug A — (prior session) Extension shortcut conflicts
+- Removed cosmetic `[Extension issues]` warning for `restrictOverride: false` built-in overrides in `runner.ts`
+- These are intentional context-scoped key reuse (e.g. ctrl+d = session.delete AND tree.filter)
+
+---
+
+## 🔧 In Progress
+
+### Bug F — Scroll-while-typing transcript
+- **Status:** Investigated, NOT implemented
+- **Complexity:** 200-400 line architectural change in `@hamr/tui`
+
+**Root cause:** The current TUI rendering engine (`packages/tui/src/tui.ts`) has no scrollable container concept. The viewport is always bottom-anchored (`doRender()`, line ~1214). All children (chat + editor + footer) are rendered as one flat buffer by `Container.render()`. There's no way to "pin" the editor at the bottom while scrolling the chat history independently.
+
+**What's needed:**
+1. Add a `TUI.scrollOffset` field that shifts which content rows are visible in the viewport
+2. Introduce a concept of "fixed" vs "scrollable" children in Container (or a new `ScrollableContainer`)
+3. Render the scrollable region from `viewportTop - scrollOffset` while fixed children render at the bottom of the terminal
+4. Keyboard handlers: PgUp/PgDown/Ctrl+Up/Ctrl+Down adjust scrollOffset; auto-reset to 0 when new content arrives or user scrolls to bottom
+5. Mouse wheel support (if terminal supports SGR mouse)
+
+**Files to touch:**
+- `packages/tui/src/tui.ts` — viewport calculation in `doRender()`, new scroll state, input dispatch
+- `packages/tui/src/container.ts` — OR a new `ScrollableView` component
+- `packages/coding-agent/src/modes/interactive/interactive-mode.ts` — keybinding setup for scroll
+
+**Synax reference:** `src/tui/components/event-feed.ts` has its own `_scrollOffset` + `_userScrolled` + `scrollUp()`/`scrollDown()`/`scrollToBottom()` — but synax's event-feed is a single component that manages its own scroll within a fixed-height viewport. Synax's TUI layout keeps the editor pinned separately.
+
+---
+
+## 📋 Remaining
+
+### Low-hanging fruit
+- **Help text rebrand:** `package-manager-cli.ts` still says "Update pi" / "pi update" — should say "hamr update"
+- **README claims "9 color themes":** Only `default`, `kawaii`, `pinkOut` ship in `src/modes/interactive/theme/`. Either ship more themes or fix the claim.
+- **GitHub URLs in migrations.ts:** Still point to `earendil-works/pi-mono` repo
+
+### Medium effort
+- **Version string:** Currently `0.79.6` (inherited from Pi). Consider bumping to a Hamr-specific version (e.g. `1.0.0`).
+- **Pi→Hamr in CHANGELOG.md:** Historical entries reference Pi packages. These are archival and can stay, but new entries should use `@hamr/*` naming.
+- **npm-shrinkwrap.json:** References `pi-tui` in resolved URLs — auto-generated, updates on next `npm install`
+- **P0 Checklists:** Write comprehensive Demo Gates + Brand Gate docs (user provided detailed checklist)
+
+### Large effort (deferred)
+- **Architecture simplification:** Toward `hamr theme + sexy-tui-rs + pi fork agent` — needs design doc
+- **Full `@skaft/hamr` rebrand:** Package naming, exports, SDK docs
+- **Scroll-while-typing:** See "In Progress" above
+
+---
+
+## Architecture Context
+
+```
+hamr monorepo
+├── packages/tui/         → @hamr/tui     (fork of pi-tui, shared terminal UI components)
+├── packages/ai/          → @hamr/ai      (model providers, API clients)
+├── packages/agent/       → @hamr/agent   (agent loop, tools, sessions)
+└── packages/coding-agent → @hamr/coding-agent  (CLI, TUI mode, extensions)
+
+synax (reference)
+└── src/tui/              → HamrTheme, EventFeed, StatusBar, AgentDashboard
+```
+
+- **Theme default:** `APP_NAME === "hamr"` → `getDefaultTheme()` returns `"hamr"` → loads `hamr.json`
+- **Startup flow:** `InteraciveMode.run()` → `rebindCurrentSession()` → `renderInitialMessages()` → splash OR restored messages
+- **Model change flow:** `cycleModel()` / `cycleThinkingLevel()` → `updateEditorBorderColor()` → now also calls `refreshSplashIfLive()`
+- **Message rendering:** Live events + session restore both go through `addMessageToChat()` which now captures model accent/glyph at call time

package/docs/windows.md

@@ -0,0 +1,17 @@
+# Windows Setup
+
+Pi requires a bash shell on Windows. Checked locations (in order):
+
+1. Custom path from `~/.hamr/agent/settings.json`
+2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
+3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+
+For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+## Custom Shell Path
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```

package/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+Example code for hamr SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, questions, subagents, output truncation)
+- Commands and keyboard shortcuts
+- Custom UI (footers, headers, editors, overlays)
+- Git integration (checkpoints, auto-commit)
+- System prompt modifications and custom compaction
+- External integrations (SSH, file watchers, system theme sync)
+- Custom providers (Anthropic with custom streaming, GitLab Duo)
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -0,0 +1,211 @@
+# Extension Examples
+
+Example extensions for hamr.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+hamr --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.hamr/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension | Description |
+|-----------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `project-trust.ts` | Demonstrates the `project_trust` event for user/global and CLI extensions |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, fork) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+| `sandbox/` | OS-level sandboxing using `@anthropic-ai/sandbox-runtime` with per-project config |
+| `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM |
+
+### Custom Tools
+
+| Extension | Description |
+|-----------|-------------|
+| `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
+| `hello.ts` | Minimal custom tool example |
+| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions with custom UI |
+| `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
+| `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
+| `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
+| `structured-output.ts` | Final structured-output tool that returns `terminate: true` so the agent can end on the tool call |
+| `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
+| `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
+| `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
+| `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
+
+### Commands & UI
+
+| Extension | Description |
+|-----------|-------------|
+| `preset.ts` | Named presets for model, thinking level, tools, and instructions via `--preset` flag and `/preset` command |
+| `plan-mode/` | Claude Code-style plan mode for read-only exploration with `/plan` command and step tracking |
+| `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `github-issue-autocomplete.ts` | Adds `#1234` issue completions by stacking a custom autocomplete provider that preloads open issues from `gh issue list` |
+| `widget-placement.ts` | Shows widgets above and below the editor via `ctx.ui.setWidget()` placement |
+| `hidden-thinking-label.ts` | Customizes the collapsed thinking label via `ctx.ui.setHiddenThinkingLabel()` |
+| `working-indicator.ts` | Customizes the streaming working indicator via `ctx.ui.setWorkingIndicator()` |
+| `model-status.ts` | Shows model changes in status bar via `model_select` hook |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+| `tic-tac-toe.ts` | Tic-tac-toe vs the agent with `executionMode: "sequential"` tools to prevent race conditions on shared cursor state |
+| `send-user-message.ts` | Demonstrates `pi.sendUserMessage()` for sending user messages from extensions |
+| `timed-confirm.ts` | Demonstrates AbortSignal for auto-dismissing `ctx.ui.confirm()` and `ctx.ui.select()` dialogs |
+| `rpc-demo.ts` | Exercises all RPC-supported extension UI methods; pair with [`examples/rpc-extension-ui.ts`](../rpc-extension-ui.ts) |
+| `modal-editor.ts` | Custom vim-like modal editor via `ctx.ui.setEditorComponent()` |
+| `rainbow-editor.ts` | Animated rainbow text effect via custom editor |
+| `notify.ts` | Desktop notifications via OSC 777 when agent finishes (Ghostty, iTerm2, WezTerm) |
+| `titlebar-spinner.ts` | Braille spinner animation in terminal title while the agent is working |
+| `summarize.ts` | Summarize conversation with GPT-5.2 and show in transient UI |
+| `custom-footer.ts` | Custom footer with git branch and token stats via `ctx.ui.setFooter()` |
+| `custom-header.ts` | Custom header via `ctx.ui.setHeader()` |
+| `overlay-test.ts` | Test overlay compositing with inline text inputs and edge cases |
+| `overlay-qa-tests.ts` | Comprehensive overlay QA tests: anchors, margins, stacking, overflow, animation |
+| `doom-overlay/` | DOOM game running as an overlay at 35 FPS (demonstrates real-time game rendering) |
+| `shutdown-command.ts` | Adds `/quit` command demonstrating `ctx.shutdown()` |
+| `reload-runtime.ts` | Adds `/reload-runtime` and `reload_runtime` tool showing safe reload flow |
+| `interactive-shell.ts` | Run interactive commands (vim, htop) with full terminal via `user_bash` hook |
+| `inline-bash.ts` | Expands `!{command}` patterns in prompts via `input` event transformation |
+| `input-transform-streaming.ts` | Skips expensive input preprocessing for mid-stream steering via `streamingBehavior` |
+
+### Git Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on fork |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+
+### System Prompt & Compaction
+
+| Extension | Description |
+|-----------|-------------|
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
+| `claude-rules.ts` | Scans `.claude/rules/` folder and lists rules in system prompt |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+| `trigger-compact.ts` | Triggers compaction when context usage exceeds 100k tokens and adds `/trigger-compact` command |
+
+### System Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `mac-system-theme.ts` | Syncs hamr theme with macOS dark/light mode |
+
+### Resources
+
+| Extension | Description |
+|-----------|-------------|
+| `dynamic-resources/` | Loads skills, prompts, and themes using `resources_discover` |
+
+### Messages & Communication
+
+| Extension | Description |
+|-----------|-------------|
+| `message-renderer.ts` | Custom message rendering with colors and expandable details via `registerMessageRenderer` |
+| `event-bus.ts` | Inter-extension communication via `pi.events` |
+
+### Session Metadata
+
+| Extension | Description |
+|-----------|-------------|
+| `session-name.ts` | Name sessions for the session selector via `setSessionName` |
+| `bookmark.ts` | Bookmark entries with labels for `/tree` navigation via `setLabel` |
+
+### Custom Providers
+
+| Extension | Description |
+|-----------|-------------|
+| `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
+| `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
+
+### External Dependencies
+
+| Extension | Description |
+|-----------|-------------|
+| `with-deps/` | Extension with its own package.json and dependencies (demonstrates jiti module resolution) |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+
+## Writing Extensions
+
+See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+
+```typescript
+import type { ExtensionAPI } from "@hamr/coding-agent";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+      if (!ok) return { block: true, reason: "Blocked by user" };
+    }
+  });
+
+  // Register custom tools
+  pi.registerTool({
+    name: "greet",
+    label: "Greeting",
+    description: "Generate a greeting",
+    parameters: Type.Object({
+      name: Type.String({ description: "Name to greet" }),
+    }),
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      return {
+        content: [{ type: "text", text: `Hello, ${params.name}!` }],
+        details: {},
+      };
+    },
+  });
+
+  // Register commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
+  });
+}
+```
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+```typescript
+import { StringEnum } from "@hamr/ai";
+
+// Good
+action: StringEnum(["list", "add"] as const)
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+
+**State persistence via details:**
+```typescript
+// Store state in tool result details for proper forking support
+return {
+  content: [{ type: "text", text: "Done" }],
+  details: { todos: [...todos], nextId },  // Persisted in session
+};
+
+// Reconstruct on session events
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "my_tool") {
+      const details = entry.message.details;
+      // Reconstruct state from details
+    }
+  }
+});
+```