@greppleai/grip 0.0.0-stage → 0.1.3

package/docs/usage.md

@@ -0,0 +1,304 @@
+# Using Grip
+
+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="Historical upstream Pi interactive mode screenshot; Grip paths and branding differ" 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 |
+| Copy response | Ctrl+X copies the last assistant message; in `/tree`, it copies the selected entry |
+| 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, hooks, extensions, skills, rules, prompts, and context files |
+| `/hooks <enable|disable>` | Enable or disable subsequent hooks for the current session |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit Grip |
+
+`/hooks disable` immediately prevents subsequent hook events in the current session; a hook execution already in progress is allowed to finish. `/hooks enable` resumes dispatch. Skipped events are not replayed, and a newly created or resumed session starts with hooks enabled. `/reload` preserves this enabled/disabled state while refreshing file-backed hook configuration.
+
+`/hooks` and `/sandbox` are user-only interactive commands hidden from model-visible command catalogs. `/sandbox` shows or clears the current backend, attaches a sandbox daemon, and manages local Docker sandbox containers; see [Workspace Sandbox](sandbox.md).
+
+## 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 Grip to receive the shortcut.
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.grip/agent/sessions/`, organized by working directory.
+
+```bash
+grip -c                  # Continue most recent session
+grip -r                  # Browse and select a session
+grip --no-session        # Ephemeral mode; do not save
+grip --session <path|id> # Use a specific session file or session ID
+grip --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
+
+Grip loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.grip/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+If a directory contains `AGENTS.override.md`, Grip loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
+
+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:
+
+- `.grip/SYSTEM.md` for a project
+- `~/.grip/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+## 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. Its current viewer URL defaults to the upstream `https://pi.dev/session/`; a Grip viewer has not been verified. Set `GRIP_SHARE_VIEWER_URL` to a trusted viewer endpoint before relying on a branded sharing flow.
+
+For third-party session publishing workflows, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf), an upstream Pi integration that publishes sessions to Hugging Face datasets. Verify its compatibility with Grip before using it.
+
+## CLI Reference
+
+```bash
+grip [options] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+grip install <source> [-l]       # Install package, -l for project-local
+grip remove <source> [-l]        # Remove package
+grip uninstall <source> [-l]     # Alias for remove
+grip update [source|self|grip]   # Update Grip and packages; reconcile pinned git refs
+grip update --extensions        # Update packages only; reconcile pinned git refs
+grip update --self              # npm-managed installs only; for binary installs rerun the verified installer
+grip update --extension <src>   # Update one package
+grip list                       # List installed packages
+grip config                     # Enable/disable package resources
+```
+
+These commands manage Grip packages; the compiled binary itself updates by rerunning the [verified installer](quickstart.md#install), not `grip update --self`. To uninstall Grip itself, see [Quickstart](quickstart.md#uninstall).
+
+See [Grip 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, Grip also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | grip -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 |
+| `--lsp-config <file>` | Load an external LSP layer; the file argument is startup-cwd-relative, while paths declared inside use the file's directory |
+| `--no-lsp` | Disable the LSP runtime and tools for this invocation, including recovery from malformed lower-precedence LSP sources |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist 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 |
+| `--remote <url>` | Run built-in tools through a `grip --daemon` backend (`ws://` or `wss://`) |
+
+Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `session_search`, `session_entry_get`, `subagent`, `subagent_runs`, `create_subagent`, and—when configured—`lsp_diagnostics`, `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_rename`, and `lsp_code_actions`.
+
+The three subagent tools are inactive by default. Enable them through `/settings` or `"enableSubagents": true` in `settings.json`. An explicit `--tools` allowlist can opt in to any subset regardless of that setting; `--no-tools` and `--no-builtin-tools` still suppress them.
+LSP servers are external and disabled when no configuration is present. See [Language Server Protocol](lsp.md) for CLI files, settings precedence, server setup, remote path mapping, and troubleshooting.
+
+The `subagent` tool runs fresh in-memory agent sessions in single, parallel, or chained mode. Each session has an isolated conversation while sharing parent authentication and model services, avoiding separate process startup. Each task can provide an optional named preset, persona (`systemPrompt`), output contract (`responseFormat`), model, tool allowlist, and working directory. Without a model it inherits the parent model; the parent receives authenticated same-family model metadata including context and token costs. Bundled presets are `explore`, `worker`, and `reviewer`. User definitions in `~/.grip/agent/agents/*.md` override bundled presets; project definitions in `.grip/agents/*.md` are opt-in through `agentScope` and require interactive confirmation by default.
+
+Use `--remote-deferred --remote-cwd <path>` to start without a connected tool backend, then connect from interactive mode with `/sandbox --attach <ws://url>`. Connecting reloads project instruction resources from the selected daemon backend.
+
+### 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 |
+| `--rule <path>` | Load a rule; repeatable |
+| `--no-rules` | Disable rule 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.override.md`, `AGENTS.md`, and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+grip --no-extensions -e ./my-extension.ts
+```
+
+With `--remote`, project instruction resources are loaded from the daemon workspace cwd: `.grip/skills`, `.grip/rules`, `.grip/prompts`, ancestor `.agents/skills` and `.agents/rules`, and per-directory `AGENTS.override.md`/`AGENTS.md`/`CLAUDE.md` context. `AGENTS.override.md` replaces the other context candidates only in its own directory. Extension loading, themes, user resources, and package resources remain local.
+
+### 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 |
+| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--verbose` | Force verbose startup |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, status, extension widgets, editor, and footer remain fixed at the bottom. In `regular` mode, Grip uses the terminal main screen and terminal-owned scrollback. Set **TUI mode** in `/settings` to switch immediately and choose the default for future sessions; `--tui-mode` overrides it for one startup. **Fullscreen exit output** controls whether shutdown replays the complete transcript or restores the previous main screen without replaying transcript content, leaving any shell or launcher resume affordance visible.
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+grip @prompt.md "Answer this"
+grip -p @screenshot.png "What's in this image?"
+grip @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+grip "List all .ts files in src/"
+
+# Non-interactive
+grip -p "Summarize this codebase"
+
+# Non-interactive with piped stdin
+cat README.md | grip -p "Summarize this text"
+
+# Different model
+grip --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+grip --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+grip --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+grip --models "claude-*,gpt-4o"
+
+# Read-only mode
+grip --tools read,grep,find,ls -p "Review the code"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GRIP_CODING_AGENT_DIR` | Override config directory; default is `~/.grip/agent` |
+| `GRIP_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
+| `GRIP_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
+| `GRIP_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
+| `GRIP_SKIP_VERSION_CHECK` | Skip the Grip version update check at startup. This prevents the npm metadata request |
+| `GRIP_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
+| `GRIP_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
+| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
+
+## Design Principles
+
+Grip keeps the core small and pushes workflow-specific behavior into extensions, skills, rules, prompt templates, and packages.
+
+Grip includes a focused subagent delegation tool but keeps broader workflow-specific behavior in extensions, skills, rules, prompt templates, and packages. It intentionally does not include built-in MCP, 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 original upstream rationale, read the [Pi blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/docs/windows.md

@@ -0,0 +1,17 @@
+# Windows Setup
+
+Grip requires a bash shell on Windows. Checked locations (in order):
+
+1. Custom path from `~/.grip/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,29 @@
+# Examples
+
+Example code for grip-coding-agent SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `GripAgent`. 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)
+
+
+### [remote-session-server/](remote-session-server/)
+Hono-based remote session storage server. It uses static bearer auth and stores sessions as JSONL files for debugging the remote session protocol end-to-end.
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/daemon-docker/Dockerfile

@@ -0,0 +1,43 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		bash \
+		ca-certificates \
+		fd-find \
+		file \
+		git \
+		ripgrep \
+	&& ln -s /usr/bin/fdfind /usr/local/bin/fd \
+	&& rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY package.json package-lock.json tsconfig.base.json ./
+COPY packages ./packages
+COPY scripts ./scripts
+
+RUN npm ci --ignore-scripts \
+	&& npm run build \
+	&& npm pack --workspace @greppleai/grip --pack-destination /tmp/grip-pack \
+	&& npm install -g --ignore-scripts /tmp/grip-pack/greppleai-grip-*.tgz \
+	&& rm -rf /tmp/grip-pack
+
+RUN mkdir -p /workspace/src /workspace/.grip/skills /workspace/.grip/skills/remote-container \
+	&& printf '# Remote grip daemon test project\n\nThis project is inside the grip --daemon Docker container.\n' > /workspace/README.md \
+	&& printf '# Project Instructions\n\nYou are working inside the grip --daemon Docker test container. Use tools normally; file and shell operations run in /workspace.\n' > /workspace/AGENTS.md \
+	&& printf 'export function hello(name: string): string {\n\treturn `hello ${name}`;\n}\n' > /workspace/src/hello.ts \
+	&& printf '%s\n' '---' 'description: This intentionally malformed skill is missing name frontmatter.' '---' '' '# Malformed container skill' '' 'This file should appear as a skill loading diagnostic, not as a loaded skill.' > /workspace/.grip/skills/container.md \
+	&& printf '%s\n' '---' 'name: remote-container' 'description: Mention that the skill came from the remote container.' '---' '' '# Remote container skill' '' 'When this skill is loaded, mention that it came from the remote container.' > /workspace/.grip/skills/remote-container/SKILL.md
+
+ENV GRIP_DAEMON_HOST=0.0.0.0
+ENV GRIP_DAEMON_PORT=8787
+ENV GRIP_DAEMON_CWD=/workspace
+ENV GRIP_DAEMON_TOKEN=dev-token-dev-token-dev-token-dev-token
+ENV GRIP_DAEMON_ALLOW_INSECURE_TRANSPORT=1
+ENV GRIP_DAEMON_ALLOW_PROCESS_EXEC=1
+
+WORKDIR /workspace
+EXPOSE 8787
+
+CMD ["grip", "--daemon"]

package/examples/daemon-docker/README.md

@@ -0,0 +1,45 @@
+# grip --daemon Docker test target
+
+Build and run a local container that exposes the integrated Grip remote workspace daemon on port 8787.
+
+From the repo root:
+
+```bash
+docker build -f packages/coding-agent/examples/daemon-docker/Dockerfile -t grip-remote-daemon-test .
+docker run --rm -p 8787:8787 --name grip-remote-daemon-test grip-remote-daemon-test
+```
+
+The image installs the packaged `@greppleai/grip` tarball and starts `grip --daemon`. It uses a fixed development token, enables process execution for shell-tool testing, and binds to `0.0.0.0` inside the container.
+
+In another terminal, start Grip directly against the container:
+
+```bash
+GRIP_REMOTE_TOKEN=dev-token-dev-token-dev-token-dev-token ./grip-test.sh --remote ws://127.0.0.1:8787/grip/workspace
+```
+
+Or start with a deferred backend and connect from inside Grip:
+
+```bash
+./grip-test.sh --remote-deferred --remote-cwd /workspace
+```
+
+Then run:
+
+```text
+/sandbox --attach ws://127.0.0.1:8787/grip/workspace
+```
+
+Useful prompts:
+
+```text
+List the files in this project and read AGENTS.md
+Run pwd and uname -a
+Use /skill:remote-container and tell me where the skill came from
+Edit src/hello.ts to add an exclamation mark
+```
+
+Stop the container with Ctrl-C, or from another terminal:
+
+```bash
+docker stop grip-remote-daemon-test
+```

package/examples/extensions/README.md

@@ -0,0 +1,208 @@
+# Extension Examples
+
+Example extensions for grip-coding-agent.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+grip --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.grip/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension | Description |
+|-----------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `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 |
+
+### 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) |
+| `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 `ExtensionAPI.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 Grip theme with macOS dark/light mode |
+
+### Resources
+
+| Extension | Description |
+|-----------|-------------|
+| `dynamic-resources/` | Loads skills, rules, 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 `ExtensionAPI.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 grip-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 "@greppleai/grip";
+import { Type } from "typebox";
+
+export default function (grip: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  grip.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
+  grip.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
+  grip.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 "@greppleai/grip-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
+grip.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.session.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "my_tool") {
+      const details = entry.message.details;
+      // Reconstruct state from details
+    }
+  }
+});
+```