hammoc 1.3.0 → 1.5.0

package/packages/server/dist/utils/structuredEditor.js

@@ -0,0 +1,111 @@
+/**
+ * Story 28.0.5: YAML / JSONC round-trip editor.
+ *
+ * The goal is to mutate a single key inside a structured config file while
+ * preserving the author's comments, blank lines, key order, and quoting style.
+ *
+ * - YAML  → `yaml` (eemeli) `parseDocument` + `doc.setIn/deleteIn` + `doc.toString()`.
+ *           The Document AST keeps comment & blank-line metadata attached to
+ *           each node, and `toString()` re-emits them.
+ *   NOTE: `js-yaml@4` remains a coexisting dependency for session-meta parsing
+ *   elsewhere in the codebase, but has no comment-preservation path and must
+ *   not be used for harness edits.
+ *
+ * - JSONC → `jsonc-parser` `modify` + `applyEdits`. This is the same path VS
+ *           Code uses when it edits user `settings.json` — comments and
+ *           formatting are preserved.
+ *
+ * Both entry points throw `HARNESS_PARSE_ERROR` on unparseable input so the
+ * harness controller can surface the envelope and the client can fall back to
+ * raw editing.
+ */
+import { parseDocument } from 'yaml';
+import { modify, applyEdits, parse, parseTree, findNodeAtLocation, printParseErrorCode, } from 'jsonc-parser';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+function parseError(format, cause) {
+    const err = new Error(`failed to parse ${format}: ${cause?.message ?? String(cause)}`);
+    err.code = HARNESS_ERRORS.HARNESS_PARSE_ERROR.code;
+    return err;
+}
+/**
+ * Apply structured patches to a YAML source string while preserving comments,
+ * blank lines, and key order.
+ */
+export function applyYamlPatch(source, ops) {
+    let doc;
+    try {
+        doc = parseDocument(source, { keepSourceTokens: true });
+        if (doc.errors.length > 0) {
+            throw doc.errors[0];
+        }
+    }
+    catch (cause) {
+        throw parseError('yaml', cause);
+    }
+    // A freshly-created empty document has `contents: null`; we need a map so
+    // setIn can plant new keys at the top level.
+    if (doc.contents == null) {
+        doc.contents = doc.createNode({});
+    }
+    for (const op of ops) {
+        if (!op.path || op.path.length === 0) {
+            throw parseError('yaml', new Error('patch op requires a non-empty path'));
+        }
+        if (op.value === undefined) {
+            // Idempotent delete: if any segment (including intermediates) is already
+            // absent, the target is effectively deleted — skip. `doc.deleteIn`
+            // itself only no-ops on a missing leaf; a missing intermediate throws.
+            if (!doc.hasIn(op.path))
+                continue;
+            doc.deleteIn(op.path);
+        }
+        else {
+            doc.setIn(op.path, op.value);
+        }
+    }
+    // toString() preserves original comments/blank lines/quote style for any
+    // node that was not explicitly replaced.
+    return doc.toString();
+}
+/**
+ * Apply structured patches to a JSONC source string while preserving comments
+ * and formatting. Inserts missing intermediate objects as needed (matches
+ * `jsonc-parser` `modify` default behavior).
+ */
+export function applyJsoncPatch(source, ops) {
+    // Validate the source up front — `modify` silently starts from `{}` on
+    // garbage input, which would quietly erase the user's file. Feed the
+    // official errors array to catch unterminated strings, missing values, etc.
+    if (source.trim().length > 0) {
+        const errors = [];
+        parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+        if (errors.length > 0) {
+            const first = errors[0];
+            throw parseError('jsonc', new Error(`${printParseErrorCode(first.error)} at offset ${first.offset}`));
+        }
+    }
+    const formattingOptions = {
+        insertSpaces: true,
+        tabSize: 2,
+        eol: source.includes('\r\n') ? '\r\n' : '\n',
+    };
+    let current = source;
+    for (const op of ops) {
+        if (!op.path || op.path.length === 0) {
+            throw parseError('jsonc', new Error('patch op requires a non-empty path'));
+        }
+        // Idempotent delete: `modify(undefined)` throws "Can not delete…" when the
+        // target (or any intermediate) does not exist; treat that as a no-op so
+        // callers can apply delete patches without first probing state.
+        if (op.value === undefined) {
+            const tree = parseTree(current, [], { allowTrailingComma: true, disallowComments: false });
+            if (!tree || !findNodeAtLocation(tree, op.path))
+                continue;
+        }
+        // `modify` takes `undefined` to mean "remove", matching HarnessStructuredPatchOp.value semantics.
+        const edits = modify(current, op.path, op.value, { formattingOptions });
+        current = applyEdits(current, edits);
+    }
+    return current;
+}
+//# sourceMappingURL=structuredEditor.js.map

package/packages/server/dist/utils/structuredEditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredEditor.js","sourceRoot":"","sources":["../../src/utils/structuredEditor.ts"],"names":[],"mappings":"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"}

package/packages/server/package.json

@@ -15,22 +15,26 @@
     "test:all": "vitest run"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.34",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.114",
     "@hammoc/shared": "*",
     "bcrypt": "^6.0.0",
+    "chokidar": "^5.0.0",
     "cookie-session": "^2.1.1",
     "cors": "^2.8.5",
     "express": "^4.21.0",
-    "express-rate-limit": "^8.3.1",
     "helmet": "^8.1.0",
     "i18next": "^24.2.3",
+    "ignore": "^5.3.2",
     "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
+    "jszip": "^3.10.1",
     "multer": "^2.1.1",
     "node-pty": "^1.0.0",
     "sharp": "^0.34.5",
     "simple-git": "^3.27.0",
     "socket.io": "^4.8.0",
     "web-push": "^3.6.7",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/packages/server/resources/internals/INDEX.md

@@ -0,0 +1,23 @@
+# Hammoc Internals (Agent-Only Reference)
+
+This folder documents Hammoc's internal mechanisms that an in-IDE agent may need to read or correlate, but that are deliberately omitted from the user-facing manual. The user does not need to know any of this; the agent does.
+
+## How to use
+
+Read individual entries **on demand** when the user's request involves the underlying mechanism (for example: correlating an attached image with a file on disk, understanding how a session ID maps to a JSONL file). Do not pre-load this folder.
+
+## Entries
+
+- [Image Storage](./image-storage.md) — On-disk path and filename scheme for chat-attached images
+- [Harness File Layout](./harness-files.md) — Where `.claude/` items (skills, commands, agents, hooks, MCP servers, `CLAUDE.md`) live on disk, when changes take effect, and how the Secret-on-Shared guard relates to direct file writes
+
+## Maintenance
+
+Add a new file here whenever there is internal behavior the agent needs to act on but the user does not need to see. Likely future entries:
+
+- Session ID and project-path slug encoding under `~/.claude/projects/`
+- JSONL message tree structure (parent/child UUIDs, branching)
+- Permission-mode internal effects on the SDK call
+- Snippet resolution order and substitution rules
+
+Each new file should describe the on-disk reality (paths, formats, lifecycle), not the user-facing UI behavior — that belongs in the user manual.

package/packages/server/resources/internals/harness-files.md

@@ -0,0 +1,63 @@
+# Harness File Layout
+
+The Harness Workbench (user-facing, see manual §12) edits Claude Code's `.claude/` configuration trees in place. An agent can reach the same files directly with Read / Write / Edit and skip the UI when that's faster.
+
+## On-disk roots
+
+Two trees, walked in this priority order:
+
+```
+<projectRoot>/.claude/        # project scope (highest)
+<homeDir>/.claude/            # global scope (user scope)
+```
+
+When the same name (skill, command, agent, hook, MCP server, snippet) exists in both, the project copy is **active** and the global copy is **shadowed** but kept on disk.
+
+`<homeDir>` must be resolved before use — Read / Write / Edit do not expand `~`. On Windows that is `C:\Users\<user>\`.
+
+## Per-item layout
+
+| Item | Path (under either `.claude/` root) | Format |
+|------|--------------------------------------|--------|
+| Skill | `skills/<name>/SKILL.md` + bundle assets in the same directory | Markdown body + YAML frontmatter (`name`, `description`, `version`) |
+| Slash command | `commands/<name>.md` | Markdown body + YAML frontmatter |
+| Sub-agent | `agents/<name>.md` | Markdown body + YAML frontmatter (`name`, `description`, `tools`) |
+| Hook | `settings.json` → `hooks.<EventName>[]` entries | JSON; one event name per array key (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreCompact`, `Notification`) |
+| MCP server | `.mcp.json` at the project root, or `<homeDir>/.claude/.mcp.json` | JSON; entries under `mcpServers.<name>` |
+| `CLAUDE.md` | `<projectRoot>/.claude/CLAUDE.md`, `<homeDir>/.claude/CLAUDE.md` | Plain Markdown; both files load into every session, project wins on conflict |
+| Plugin | `plugins/<vendor>__<name>/` | Plugin bundle directory; treated read-only by Hammoc — copy items out to project/global to customize |
+
+Hammoc-native `%snippets` are a separate layer (see manual §4.6); they live under `<projectRoot>/.hammoc/snippets/` and `<homeDir>/.hammoc/snippets/`, **not** the `.claude/` tree.
+
+## Sharing scope
+
+Each file's "share" status is computed from the project's `.gitignore`:
+
+- **Shared** — File path is tracked by git
+- **Local** — File path is untracked but `.claude/` is not ignored
+- **Ignored** — A `.gitignore` rule excludes `.claude/` (or an ancestor)
+
+The workbench shows a badge for each file. When an agent writes a file under `.claude/`, the resulting share scope is whatever the `.gitignore` already says — Hammoc does not rewrite `.gitignore` on the agent's behalf.
+
+## Secret-on-Shared guard
+
+When the user saves a `Shared`-scope file through the UI, Hammoc scans for plaintext secrets (entropy + pattern heuristic) and blocks the save with a dialog. **An agent writing the file directly via Write / Edit bypasses that dialog.** If the agent is editing a `Shared` file under `.claude/`, it must avoid committing plaintext API keys, bearer tokens, etc. Use a sibling `*.local.<ext>` file (gitignored) and reference it from the shared file, or use `${ENV_VAR}` references that the hook / MCP runtime expands.
+
+## When changes take effect
+
+- **Skills, commands, agents, CLAUDE.md, snippets** — Picked up on the next message in a chat turn (the system prompt and tool list re-resolve on each turn).
+- **Hooks** — Same: next message in a chat turn.
+- **MCP servers** — Picked up only on a **fresh session spawn**, not mid-session. The workbench UI shows a "Takes effect on your next user message" banner with a "Start new session" button after the user edits an MCP entry; an agent making MCP edits should remind the user to start a new session, or do so on their behalf.
+- **Plugin enable/disable** — Same as MCP: fresh spawn required.
+
+## Static lint (informational)
+
+The workbench runs seven static-lint rules over the trees (see manual §12.12). Agents writing harness files should keep these rules in mind even though writes are not blocked:
+
+- duplicate names across scopes
+- invalid hook matcher regex
+- frontmatter / JSON parse errors
+- MCP `stdio` command not on `PATH`
+- malformed MCP URLs
+- non-standard agent tool names
+- hook bodies referencing undefined env vars

package/packages/server/resources/internals/image-storage.md

@@ -0,0 +1,43 @@
+# Image Storage
+
+When the user attaches an image to a chat message, Hammoc saves it under **Claude Code's per-project session data**, not inside the project being worked on. The user does not see this — they just attach and send. This document is for an agent that needs to read or correlate the file directly.
+
+## On-disk location
+
+```
+<homeDir>/.claude/projects/<encoded-project-path>/images/<sessionId>/<filename>
+```
+
+- `<homeDir>` — User home directory (Read/Edit tools do not expand `~`, so resolve to the absolute path first).
+- `<encoded-project-path>` — Claude Code's project slug. Path separators (`/`, `\`) and colons (`:`) in the original project path are replaced with hyphens. Example: `D:\repo\hammoc` → `D--repo-hammoc`.
+- `<sessionId>` — UUID of the chat session containing the message.
+- `<filename>` — `<sha256-prefix-16chars>.<ext>` for the original. Thumbnails use `<sha256-prefix-16chars>_thumb.<ext>`.
+- `<ext>` — One of `.png`, `.jpg`, `.gif`, `.webp`.
+
+## Supported MIME types
+
+| MIME | Extension |
+|---|---|
+| image/png | .png |
+| image/jpeg | .jpg |
+| image/gif | .gif |
+| image/webp | .webp |
+
+Anything else is rejected at attach time.
+
+## How an agent reaches these files
+
+- The chat message references each image via the API URL `/api/projects/<projectSlug>/sessions/<sessionId>/images/<filename>`. That URL is for the **browser** to render thumbnails — it is not a file-system path and Read tools cannot use it directly.
+- To open the file from disk, build the absolute path under `<homeDir>/.claude/projects/...` using the rules above, then call Read with that path.
+
+## Lifecycle
+
+- Images are written the moment the user sends a message with attachments.
+- A session's `images/<sessionId>/` directory is removed when the session itself is deleted.
+- Filenames are content-addressed (sha256 prefix), so attaching the same image bytes twice within a session reuses the same filename — automatic deduplication.
+
+## Limits
+
+- 5 images per message
+- 10 MB per image
+- Total per-session storage is bounded only by disk; there is no automatic eviction other than session deletion.

package/packages/server/resources/manual/01-getting-started.md

@@ -0,0 +1,104 @@
+## 1. Getting Started
+
+### 1.1 Installation
+
+**Option A: Run with npx (no install)**
+
+```bash
+npx hammoc
+```
+
+**Option B: Global install**
+
+```bash
+npm install -g hammoc
+hammoc
+```
+
+**Option C: From source (development)**
+
+```bash
+git clone https://github.com/starsh2001/hammoc.git
+cd hammoc
+npm install
+npm run dev
+```
+
+### 1.2 System Requirements
+
+- **Node.js** >= 18.0.0 (v22 LTS recommended)
+- **Claude Code CLI** installed and authenticated
+- Modern browser (Chrome, Firefox, Safari, Edge)
+
+### 1.3 First Launch
+
+1. Open http://localhost:3000 in your browser
+2. **Password Setup**: Set an admin password on first visit. This protects your instance from unauthorized access.
+3. **Login**: Enter your password to sign in. **"Stay signed in"** keeps you logged in for 30 days (checked by default). After too many failed attempts, login is temporarily locked with a countdown timer.
+4. **CLI Verification**: The onboarding wizard checks that Claude Code CLI is installed and authenticated. Follow the prompts if any step fails.
+5. **Project Selection**: Choose an existing Claude Code project or create a new one.
+
+### 1.4 Mobile Access
+
+Hammoc is fully responsive. From any device on the same network:
+
+```
+http://<your-computer-ip>:3000
+```
+
+- Desktop: Enter sends message, Shift+Enter for new line
+- Mobile (touch devices): Enter adds new line, tap the send button to send
+- **Pull-to-refresh**: Swipe down on the session list to refresh
+
+### 1.5 CLI Options
+
+```bash
+hammoc --port 8080          # Custom port
+hammoc --host localhost     # Bind to localhost only
+hammoc --trust-proxy        # Enable reverse proxy support
+hammoc --cors-origin <url>  # Restrict CORS to specific origin
+hammoc --reset-password     # Reset admin password
+hammoc --version            # Show version
+hammoc --help               # Show help
+```
+
+All options are also available as environment variables (see [Environment Variables](#14-environment-variables)).
+
+### 1.6 Remote Access (Reverse Proxy)
+
+If you need to expose Hammoc through a reverse proxy (Cloudflare Tunnel, nginx, etc.), use `--trust-proxy` and `--cors-origin`:
+
+```bash
+npx hammoc --trust-proxy --cors-origin https://hammoc.yourdomain.com
+```
+
+**What `--trust-proxy` enables:**
+- Reads real client IP from proxy headers for access control (e.g. localhost-only endpoints)
+- Sets session cookies with `Secure` flag (HTTPS-only)
+
+**What `--cors-origin` does:**
+- Restricts cross-origin requests to the specified URL only
+- Without it, any website can make authenticated requests to your Hammoc instance
+
+**Security features (always active, no configuration needed):**
+- Security headers (CSP, X-Frame-Options, HSTS, etc.)
+- Server management APIs (restart, update) restricted to localhost only
+- Terminal access restricted to local network IPs
+- Login brute-force protection (5 failed attempts → 30s lockout per IP)
+
+> **Note:** Hammoc does not apply request-level rate limiting itself — traffic shaping is an infrastructure concern. Configure it at your reverse proxy / WAF / API gateway (nginx `limit_req`, Cloudflare WAF rules, etc.).
+
+### 1.7 HTTPS / TLS
+
+Hammoc automatically enables HTTPS when TLS certificates are found:
+
+1. Place your certificate files in the `~/.hammoc/` directory:
+   - `~/.hammoc/key.pem` — Private key
+   - `~/.hammoc/cert.pem` — Certificate (or full chain)
+2. Restart Hammoc — it will detect the files and start an HTTPS server
+3. The startup log will show `TLS: enabled (certs from ~/.hammoc/)`
+
+If no certificates are found, the server runs over HTTP as usual.
+
+> **Tip:** For local development, you can generate self-signed certificates with `mkcert` or `openssl`. For production, use certificates from Let's Encrypt or your domain provider.
+

package/packages/server/resources/manual/02-chat.md

@@ -0,0 +1,285 @@
+## 2. Chat
+
+The chat interface is the core of Hammoc. It provides a rich, real-time conversation experience with Claude.
+
+### 2.1 Sending Messages
+
+- Type your message in the input area at the bottom
+- **Desktop**: Press `Enter` to send, `Shift+Enter` for a new line
+- **Mobile**: Press `Enter` for a new line, tap the send button to send
+- The input area auto-expands as you type
+
+### 2.2 Streaming Responses
+
+Claude's responses stream in real-time, character by character. You'll see:
+
+- **Text content** — Rendered as markdown as it arrives
+- **Tool calls** — Shown as expandable cards with tool name, inputs, and results
+- **Thinking blocks** — Claude's extended reasoning displayed in collapsible sections
+- **Timestamps** — Each message shows a relative timestamp (e.g., "2 hours ago")
+- **Copy button** — Click the copy icon on any message to copy its content to the clipboard
+- **Scroll to bottom** — When scrolled up, a down-arrow button appears to jump back to the latest message
+
+### 2.3 Markdown & Code Blocks
+
+Messages support full GitHub-flavored markdown:
+
+- Headers, bold, italic, strikethrough
+- Ordered and unordered lists
+- Tables
+- Blockquotes
+- Links (open in new tab)
+- Inline code and fenced code blocks
+
+**HTML support:**
+- Inline HTML tags are rendered alongside markdown (e.g., `<div>`, `<span>`, `<table>`)
+- Dangerous elements (`<script>`, `<iframe>`, `<style>`, event handlers) are automatically stripped for XSS protection
+
+**Relative path resolution:**
+- File links and image references in markdown resolve relative to the source file's directory
+- Parent traversal (`../`) is supported (e.g., `../../config.json` navigates up two levels)
+- Clicking resolved file links opens them in the text editor; images open in the image viewer
+
+**Code blocks** have:
+- Language-specific syntax highlighting
+- Copy button (top-right corner)
+- File reference links that open directly in the editor
+
+### 2.4 Image Attachments
+
+Attach images to your messages for Claude to analyze:
+
+- Click the attachment button (paperclip icon) in the input area
+- Drag and drop images directly onto the input area
+- Paste from clipboard (`Ctrl+V` / `Cmd+V`)
+- Supported formats: PNG, JPEG, GIF, WebP
+- Maximum: 5 images per message, 10MB per image
+- Images preview in the input area before sending
+- Sent images display as clickable thumbnails above the message text. Clicking a thumbnail opens the full image viewer with multi-image navigation (see §6.4)
+
+### 2.5 Tool Call Visualization
+
+When Claude uses tools (reading files, editing code, running commands), each tool call is shown as a card:
+
+- **Tool name** — e.g., Read, Edit, Bash, Grep
+- **Input parameters** — What was passed to the tool
+- **Status indicator** — Running (spinner), completed (checkmark), failed (X), denied (shield icon)
+- **Execution time** — How long the tool took
+- **Result** — Expandable section showing tool output
+- **File paths** — Toggle between short and full path display
+
+### 2.6 Task Notifications
+
+When Claude runs background tasks (e.g., Agent sub-tasks), a notification card appears in the message stream upon completion:
+
+- **Status indicators** — Completed (green checkmark), Failed (red alert), Stopped (bell icon)
+- **Summary text** — Brief description of the task outcome
+- **Clickable** — When linked to a tool call, clicking the card scrolls to the associated Agent tool card and highlights it briefly
+
+### 2.7 Diff Viewer
+
+When Claude modifies files, a diff viewer shows the changes:
+
+- **Side-by-side mode** — Before and after comparison (wide screens)
+- **Inline mode** — Unified diff view (narrow screens or mobile)
+- **Syntax highlighting** — Language-aware coloring
+- **Diff navigation** — `F7` next change, `Shift+F7` previous change
+- **Large file handling** — Very large files are handled with optimized rendering
+- **Responsive layout** — Automatically switches between side-by-side and inline modes based on screen width (768px breakpoint)
+- **Manual layout toggle** — A toggle button in the viewer header (Columns2 / Rows2 icon) lets you force side-by-side or inline. The choice is persisted per user and overrides the responsive default until reset
+
+### 2.8 Permission Requests
+
+Depending on your permission mode, Claude may ask for approval before modifying files:
+
+- **Approve** — Allow the change
+- **Reject** — Block the change
+- View the diff before deciding
+- See the list of requested permissions
+
+### 2.9 Prompt Chaining
+
+Queue multiple prompts for sequential execution. Chain state is managed server-side, enabling multi-browser sync and background execution.
+
+1. Toggle **chain mode** ON via the chain button (link icon next to send) or hold `Ctrl`
+2. Type your first prompt and send it — the send button label changes to **"Add to chain"**
+3. While Claude is responding, type the next prompt and send — it enters the chain
+4. Up to **10** prompts can be queued
+5. A **violet banner** shows the chain status:
+   - **Collapsed mode** — First prompt preview + "+N" count indicator
+   - **Expanded mode** — Full list with individual **Remove** buttons (click to expand when 2+ items)
+   - **Drag-and-drop reorder** — In the expanded list, grab the grip handle (GripVertical icon) on the left of any pending item to drag it up or down. Items that are actively sending show a spinner instead of a grip and cannot be moved
+   - **Cancel all** — Clear the entire chain
+6. Each prompt auto-executes when the previous one completes
+
+**Server-side features:**
+- **Multi-browser sync** — Chain state is synchronized across all browser tabs/windows
+- **Background execution** — Chain continues running even if all browsers are closed
+- **Auto-retry** — Failed items are automatically retried before being marked as failed
+
+### 2.10 Context Usage
+
+Monitor token usage in real-time:
+
+- **Usage donut** — Visual indicator showing used/limit tokens and percentage
+- **Cost display** — Estimated cost for the session
+- **Cache tokens** — Cache creation and read token counts
+- **Rate limit dots** — 5h/7d utilization indicators in the input area
+- **Color thresholds** — Green (normal), Yellow (moderate), Red (high usage)
+- **Context compaction** — Click the usage donut to trigger compaction, which summarizes the conversation to free up context space. At critical usage levels, clicking instead creates a new session
+- **Auto-compact on overflow** — When message history hits the context window limit, Hammoc automatically compacts the context and retries the message instead of losing the session
+
+### 2.11 Aborting Responses
+
+Stop Claude mid-response:
+
+- Click the **Stop** button (appears during streaming)
+- Press `ESC` key
+- Press `Ctrl+C` (when no text is selected in the input)
+
+### 2.12 Prompt History
+
+Navigate through your previous inputs:
+
+- Press `↑` (Up arrow) to recall the previous prompt
+- Press `↓` (Down arrow) to go forward
+- History is per-session
+
+### 2.13 Voice Input (Speech Recognition)
+
+Dictate messages using your browser's built-in speech recognition:
+
+- **Microphone button** — Located inside the chat input area (right side). Only shown when the browser supports the Web Speech API (Chrome, Edge, Safari)
+- **Toggle** — Click the mic button to start/stop listening
+- **Visual indicator** — Green indicator while actively listening
+- **Language-aware** — Automatically matches the app's language setting (English, Korean, Chinese, Japanese, Spanish, Portuguese)
+- Recognized text is added to the current input without replacing existing text
+- **Auto-stop** — Voice recognition stops automatically when sending a message or when the session becomes locked
+- **Error handling** — Toast notification shown if microphone access is denied or recognition fails
+
+### 2.14 Extended Thinking
+
+When Claude uses extended thinking, the reasoning is shown in a collapsible block:
+
+- Click to expand/collapse
+- Thinking content is visually distinct from the main response
+- Useful for understanding Claude's decision-making process
+
+### 2.15 Model Selector
+
+The model selector button is located in the chat input toolbar. It displays the current model family name (e.g., "Opus", "Sonnet", "Haiku") directly on the button. When using the default model, it shows "Default". Click to open a dropdown for choosing a different model and adjusting thinking effort.
+
+### 2.16 Thinking Effort
+
+Control how much Claude "thinks" before responding. The intensity bar appears inside the model selector dropdown. The number of bars depends on the selected model:
+
+- **Low / Medium / High** — 3 levels, available for all models
+- **Max** — 4th level, added for Opus 4.6 / Sonnet 4.6
+- **XHigh** — 5th level, added only for **Opus 4.7** (the default effort for this model is XHigh)
+
+Behavior:
+
+- Click the currently active level again to reset to default
+- Cannot be changed while Claude is responding
+- If you switch to a model that doesn't support the current level (e.g., XHigh → non-Opus-4.7, or Max → model without Max), the effort automatically resets to the highest supported level
+- When the active model is temporarily unknown (e.g., right after switching projects before the resolved model arrives), the dropdown keeps your saved choice instead of resetting it. As soon as the model is known, the effort is reclamped if necessary
+
+The default thinking effort for new sessions can be configured in Settings > Global.
+
+### 2.17 Message Actions
+
+Each message has an action bar that appears at its bottom-right corner. Available actions depend on the message type:
+
+**On all messages:**
+- **Copy** — Copy the message text to clipboard
+
+**On user messages:**
+- **Edit** — Open an inline editor to modify the message (see §2.18)
+- **Summarize & Continue** — Generate an AI summary of the conversation up to that point (see §2.19)
+- **Rewind Code** — Restore the codebase to the state it was in when this message was sent (see §2.20)
+
+**On assistant messages:**
+- **Fork** — Create a new session branching from this response (see §2.21)
+
+All action buttons are disabled during streaming, and while another action (edit, rewind, summarize) is in progress. Actions are also disabled when viewing an old branch or in branch viewer mode (see §2.23).
+
+### 2.18 Message Edit
+
+Edit a previously sent user message to explore a different conversation path:
+
+1. Click the **Edit** button (pencil icon) on a user message
+2. The message transforms into an editable textarea with the original text
+3. Modify the text, then:
+   - **Accept** (checkmark button or `Ctrl+Enter`) — Send the edited message. Claude responds to the new version, creating a new conversation branch
+   - **Cancel** (X button or `Escape`) — Discard changes
+4. Empty messages cannot be submitted
+
+After editing, you can navigate between the original and edited branches using branch pagination (see §2.22).
+
+### 2.19 Summarize & Continue
+
+Compress a long conversation into a summary to free up context space while continuing the session:
+
+1. Click the **Summarize & Continue** button (sparkles icon) on a user message
+2. AI generates a summary of the conversation up to that point (spinner shown during generation)
+3. To cancel mid-generation, click the button again (shows X on hover)
+4. When complete, the inline edit form opens with the generated summary pre-filled
+5. Review, edit if needed, then **Accept** to continue with the summary or **Cancel** to discard
+
+### 2.20 Code Rewind
+
+Revert project files to a previous state in the conversation:
+
+1. Click the **Rewind Code** button (undo icon) on a user message
+2. A dry-run preview shows how many files will change (insertions/deletions count)
+3. Review the file list and click **Rewind** to confirm, or **Cancel** to abort
+4. On success, a toast confirms the number of files restored
+
+If no checkpoint is available for that message, or the code is already at that state, an error message is shown.
+
+### 2.21 Session Fork
+
+Branch into a completely new session from any assistant response:
+
+1. Click the **Fork** button (git-fork icon) on an assistant message
+2. A dialog appears with an optional message field (defaults to "Continue from here")
+3. Click **Fork** to create the new session
+4. The new session starts with the full conversation history up to that point, plus your fork message
+5. You are automatically navigated to the new session
+
+The original session remains unchanged.
+
+### 2.22 Conversation Branching
+
+When you edit a message, the conversation splits into branches. Branch pagination controls appear at the bottom-left of user messages that have multiple branches:
+
+- **← / →** arrows to navigate between branches
+- **"X / Y"** indicator showing current branch number and total count
+- Keyboard: **Left/Right arrow keys** to navigate (when the pagination is focused)
+- Navigation is disabled during streaming
+
+Switching branches replaces all messages from that point forward with the selected branch's history.
+
+### 2.23 Branch Viewer
+
+Browse all conversation branches in a read-only mode:
+
+1. Click the **branch history button** (git-branch icon) in the chat header — only visible when the session has branches
+2. The chat enters read-only mode:
+   - Branch pagination controls become active at every branch point
+   - Navigate freely between branches using ← / → arrows
+   - The input area shows "Branch viewer mode (read-only)"
+   - All message actions (edit, rewind, summarize, fork) are disabled
+3. Click **"Exit branch viewer"** in the header to return to the active conversation
+
+### 2.24 Max Budget Warning Banner
+
+When the **Max Budget (USD)** advanced setting (see §13.16) is configured, a sticky banner appears at the top of the chat area once the session cost approaches the limit:
+
+- **Yellow warning** (80% threshold) — "Budget warning: $X.XXXX / $Y.YYYY used (ZZ%) — approaching Max Budget limit."
+- **Red critical warning** (95% threshold) — "Budget critical: $X.XXXX / $Y.YYYY used (ZZ%) — stream will auto-stop when limit is exceeded."
+- Cost is shown to 4 decimal places
+- The banner is informational; the SDK auto-stops the stream once the limit is actually crossed
+
+The banner disappears automatically once the running cost falls back below the warning threshold (for example, after starting a new session).
+