diff --git a/tool-catalog/hidden-tools/README.md b/tool-catalog/hidden-tools/README.md new file mode 100644 index 0000000..85fe558 --- /dev/null +++ b/tool-catalog/hidden-tools/README.md @@ -0,0 +1,62 @@ +# Hidden / Unlisted Tools + +Tools found in the Claude.app binary that are not listed in the deferred tools system-reminder. These tools are gated by platform, feature flags, or session type. Many are visible to users in the UI but are not exposed to the AI assistant via `tool_search` or MCP tool registration. + +**Discovery method:** Extracted `app.asar`, searched `index.js` for tool registration patterns not in the deferred tools list. + +**Last updated:** 2026-03-19 + +**Verified across:** Dispatch, Cowork task, code task, Claude Code CLI, Claude Desktop main chat, claude.ai web chat + +--- + +## Verification Matrix + +| Category | Count | Desktop chat | Web chat | Dispatch | Cowork | Code task | CLI | +|----------|-------|--------------|----------|----------|--------|-----------|-----| +| Widget Tools | 2 | CONFIRMED | CONFIRMED | NOT FOUND | NOT FOUND | NOT FOUND | NOT FOUND | +| Preview Tools | 13 | — | — | — | — | CONFIRMED | — | +| Computer Use | 1 (13 actions) | — | — | via Chrome MCP | — | — | — | +| Terminal/Roots | 2 | NOT FOUND | NOT FOUND | NOT FOUND | NOT FOUND | NOT FOUND | NOT FOUND | +| Office Add-in | 5 | untested | — | — | — | — | — | +| Conversation | 1 | internal only | internal | internal | internal | internal | internal | + +**Total: 24 tools.** 14 verified working, 5 untested (require Office), 5 not callable in any tested context. + +--- + +## Tool Categories + +1. **[Widget Tools](widget-tools.md)** (2) — Inline SVG/HTML rendering. + CONFIRMED in Claude Desktop main chat and claude.ai web chat. + Not exposed via `tool_search` in any agentic context (Cowork, Dispatch, code task, CLI). + Injected by `@ant/imagine-server` at the Electron renderer layer. + +2. **[Preview Tools](preview-tools.md)** (13) — Dev server and browser preview. + CONFIRMED in code tasks only, under `mcp__Claude_Preview__*` namespace. + +3. **[Computer Use Tools](computer-use-tools.md)** (1, 13 actions) — Desktop automation. + Verified via Chrome MCP (`mcp__Claude_in_Chrome__computer`) in Dispatch sessions. + +4. **[Terminal & Roots Tools](terminal-and-roots.md)** (2) — Terminal reader and MCP roots inspector. + NOT FOUND in any tested context. Likely IDE-plugin-only (VS Code extension, JetBrains plugin). + +5. **[Office Add-in Tools](office-addin-tools.md)** (5) — Excel/Word/PowerPoint integration. + UNTESTED — requires Microsoft Office with the Claude add-in connected. + +6. **[Conversation Tools](conversation-tools.md)** (1) — Context compaction. + Internal only. Not user-callable. Correct behavior. + +7. **[Feature Flags & Codenames](feature-flags-and-codenames.md)** — Feature flags, internal codenames, Swift APIs, and config keys found in the binary. + +--- + +## Screenshots + +See `screenshots/` directory: + +| File | Contents | +|------|---------| +| widget-demo-desktop-live.png | Live Claude Desktop — widget tools active (2026-03-19) | +| widget-screenshot.png | First widget render from Cowork session | +| screenshot-1773960*.jpg | Session tool-call verification captures | diff --git a/tool-catalog/hidden-tools/computer-use-tools.md b/tool-catalog/hidden-tools/computer-use-tools.md new file mode 100644 index 0000000..7019a5d --- /dev/null +++ b/tool-catalog/hidden-tools/computer-use-tools.md @@ -0,0 +1,130 @@ +# Computer Use Tools (`mcp__computer-use__*`) + +**Status:** The `computer` tool exists under `mcp__Claude_in_Chrome__computer` in Dispatch sessions (verified via ToolSearch and Chrome tab context). The standalone `mcp__computer-use__*` namespace was not found in deferred tools — it requires an explicit computer-use MCP connection. The Chrome-based `computer` tool includes all 13 actions documented below. + +**Verified:** 2026-03-19. `mcp__Claude_in_Chrome__computer` screenshot action tested and working in Dispatch. + +Full desktop automation via screenshot-then-act loop. Registered as a dynamic MCP server — tools appear as `mcp__computer-use__*` in the deferred tools list only when the computer-use MCP is connected. + +**Priority order (from system prompt):** +1. Dedicated MCP for the app (Slack, Gmail, etc.) — fastest, most precise +2. Chrome MCP (`mcp__Claude in Chrome__*`) — DOM-aware, faster than pixels +3. Computer use — only when neither above fits (native desktop apps, cross-app workflows) + +--- + +## computer + +The single tool that handles all desktop interactions through an `action` parameter. + +### Parameters + +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `action` | string (enum) | **yes** | One of 13 actions (see below) | +| `coordinate` | [number, number] | varies | (x, y) pixel coordinates from top-left. Required for click/scroll actions. For `left_click_drag`, this is the **end** position. | +| `text` | string | varies | Text to type (for `type`) or key(s) to press (for `key`). For `key`: space-separated, supports modifier combos like "cmd+a" or "ctrl+a". | +| `duration` | number | for `wait` | Seconds to wait. Max 5 seconds. | +| `scroll_direction` | string (enum) | for `scroll` | "up", "down", "left", "right" | +| `scroll_amount` | number | no | Scroll wheel ticks (1-10). Default: 3. | +| `start_coordinate` | [number, number] | for `left_click_drag` | Starting position for drag. | +| `region` | [number, number, number, number] | for `zoom` | (x0, y0, x1, y1) rectangle to capture. | +| `repeat` | number | no | Times to repeat key sequence (1-100). Default: 1. Only for `key` action. | +| `ref` | string | for `scroll_to` | Element reference ID from `read_page` or `find` tools (e.g., "ref_1"). Can substitute for `coordinate` in click actions. | +| `modifiers` | string | no | Modifier keys for clicks: "ctrl", "shift", "alt", "cmd"/"meta", "win"/"windows". Combine with "+" (e.g., "ctrl+shift"). | +| `tabId` | number | **yes** | Tab ID — must be in current group. Use `tabs_context_mcp` first. | +| `save_to_disk` | boolean | no | For screenshot/zoom: save image to disk so it can be attached to a message. Returns saved path. | + +### Actions + +| Action | Description | Required Params | +|--------|-------------|-----------------| +| `left_click` | Left mouse click | coordinate or ref, tabId | +| `right_click` | Right mouse click (context menus) | coordinate or ref, tabId | +| `double_click` | Double left click | coordinate or ref, tabId | +| `triple_click` | Triple left click | coordinate or ref, tabId | +| `type` | Type text string | text, tabId | +| `screenshot` | Take screenshot of the screen | tabId | +| `wait` | Wait N seconds | duration, tabId | +| `scroll` | Scroll at coordinates | coordinate, scroll_direction, tabId | +| `key` | Press keyboard key(s) | text, tabId | +| `left_click_drag` | Drag from start to end | start_coordinate, coordinate, tabId | +| `zoom` | Capture region for close inspection | region, tabId | +| `scroll_to` | Scroll element into view by ref ID | ref, tabId | +| `hover` | Move cursor without clicking (tooltips, dropdowns, hover states) | coordinate or ref, tabId | + +### Notes +- Every action requires `tabId` — call `tabs_context_mcp` first +- Key combos use platform modifier: "cmd" on Mac, "ctrl" on Windows/Linux +- `save_to_disk` returns a file path — only use when sharing the screenshot with the user +- Click positioning tip from system prompt: "cursor tip in the center of the element, don't click edges" + +--- + +## Access Flow: request_access + +Before any computer-use action, `request_access` must be called with the list of applications needed. This is a permission handler invoked as `computer:request_access` — it functions like a tool call but goes through the permission system. + +### Input + +| Param | Type | Description | +|-------|------|-------------| +| `apps` | array | List of applications to request access to | + +### Tiered App Access + +| App Category | Tier | What's Allowed | +|-------------|------|----------------| +| **Browsers** (Safari, Chrome, Firefox, Edge, Arc, etc.) | `read` | Visible in screenshots, but clicks and typing blocked. Use Chrome MCP instead. | +| **Terminals & IDEs** (Terminal, iTerm, VS Code, JetBrains, etc.) | `click` | Visible and left-clickable, but typing/key presses/right-click restricted. | +| **All other apps** | `full` | Full access — screenshots, clicks, typing, all interactions. | + +### Returns + +| Field | Type | Description | +|-------|------|-------------| +| `granted` | array | Apps that were approved with their bundleId and tier | +| `denied` | array | Apps that were denied with bundleId and reason ("user_denied") | +| `flags` | object | Permission flags | + +### Notes +- User approves each application explicitly via a dialog +- May need to call again mid-task if another app is needed +- Browser tier (`read`) is a hard restriction — use Chrome MCP for browser interaction +- Terminal tier (`click`) blocks typing — use bash tools for terminal interaction + +--- + +## Teach Mode: request_teach_access + teach_step + +An interactive walkthrough system for showing users how to do something on their screen. This is the system behind the `chicago` codename (see [feature-flags-and-codenames.md](feature-flags-and-codenames.md)). + +**Trigger:** When a user wants to be "walked through" or "shown how" to do something, the model offers a choice between (1) interactive walkthrough and (2) text explanation. + +### Flow +1. Call `request_teach_access` — activates teach mode for the session +2. Call `teach_step` repeatedly — each step shows the user what to do +3. The user follows along; teach mode tracks their progress +4. Session ends when user exits or all steps complete + +### Internal state +- `teachModeActive` (boolean) — whether teach mode is running +- `teachModeEnteredAt` (timestamp) — when teach mode started +- `cuLockAcquiredAt` (timestamp) — when computer use lock was acquired + +### Notes +- These are not standard tool registrations — they're handled by the teach mode subsystem +- `teach_step` returns a Promise that resolves when the user takes action (`{action: "exit"}` etc.) +- Only one pending teach step at a time — a new one auto-resolves the previous as "exit" +- The `isChicagoEnabled` feature flag forces teach mode enabled regardless of GrowthBook config +- `chicagoAutoUnhide` (default: true) and `chicagoUserDeniedBundleIds` (default: []) control teach mode UX + +--- + +## Computer Use Lock System + +Computer use has a session-level lock to prevent multiple CU sessions from conflicting: + +- Only one session can hold the CU lock at a time +- Lock tracks duration held and whether teach mode was active +- Release triggers include: session end, explicit release, teach mode exit diff --git a/tool-catalog/hidden-tools/conversation-tools.md b/tool-catalog/hidden-tools/conversation-tools.md new file mode 100644 index 0000000..9fdc08a --- /dev/null +++ b/tool-catalog/hidden-tools/conversation-tools.md @@ -0,0 +1,45 @@ +# Conversation Tools (1 tool) + +**Status:** Internal only — not callable by users or the assistant. This tool is constructed dynamically by the compaction service and sent to the Anthropic API as part of a separate API call. It is never registered as an MCP tool or deferred tool. This is correct behavior — it is not intended to be user-callable. + +**Verified:** 2026-03-19. Not callable from Dispatch, Cowork tasks, code tasks, or Claude Code CLI. + +--- + +## summarize_conversation + +Used by the compaction service to create structured summaries when a conversation exceeds context limits. + +### Parameters + +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `summary` | string | **yes** | The conversation summary text | +| `entities` | array of strings | no | Key entities mentioned in the conversation | +| `next_action` | string | no | Description of the next action to take | + +### How it works + +This tool is not called by the user or the assistant directly. It is used internally: + +1. The compaction service detects when messages exceed a threshold +2. It calls the Anthropic API with the conversation history +3. The API uses this tool to return a structured summary +4. The summary replaces the old messages, preserving context + +### Configuration + +The tool's descriptions are configured server-side via a config object with fields: +- `toolDescription` — the tool's own description +- `summaryDescription` / `summary_description` +- `entitiesDescription` / `entities_description` +- `nextActionDescription` / `next_action_description` +- `userPromptTemplate` / `user_prompt_template` + +### Notes +- Uses `anthropic-beta` header when calling the API +- Requires an active API token (from OAuth flow) +- The tool definition is constructed dynamically from server config, not hardcoded +- There is an internal counter `WV` (starts at 0) that may track compaction count +- Will silently return null if: messages are empty/too few, no API token, or config is missing +- Uses `maxRetries: 2` for the API call diff --git a/tool-catalog/hidden-tools/feature-flags-and-codenames.md b/tool-catalog/hidden-tools/feature-flags-and-codenames.md new file mode 100644 index 0000000..0d602a8 --- /dev/null +++ b/tool-catalog/hidden-tools/feature-flags-and-codenames.md @@ -0,0 +1,203 @@ +# Feature Flags & Internal Codenames + +Feature flags, internal codenames, Swift native APIs, configuration keys, and other internals found in the Claude.app binary. + +**Source:** Static analysis of `index.js` extracted from `app.asar` +**Last updated:** 2026-03-19 + +--- + +## Table of Contents + +1. [Feature Flags](#feature-flags) +2. [Internal Codenames](#internal-codenames) +3. [Swift Native APIs](#swift-native-apis) +4. [Configuration Keys](#configuration-keys) +5. [The Clod Avatar](#the-clod-avatar) +6. [Apple App References](#apple-app-references) + +--- + +## Feature Flags + +Boolean switches (default `false`) that gate unreleased or experimental functionality. + +### Extensions & Developer Tools + +| Flag | Default | Description | +|------|---------|-------------| +| `isDxtEnabled` | `false` | Load browser extensions in app. DXT = Desktop Extension, Anthropic's extension format for the desktop client. | +| `isDxtDirectoryEnabled` | `false` | Enables a browsable extensions directory UI. Separate from `isDxtEnabled`, suggesting a phased rollout (sideloading first, then directory). | +| `isLocalDevMcpEnabled` | `false` | Allows local development MCP servers to connect to the app. For developers building custom integrations. | +| `isUvSystemPythonEnabled` | `false` | Use the system-installed Python for UV runtime extensions instead of a managed installation. | + +### Prototypes & Experiments + +| Flag | Default | Description | +|------|---------|-------------| +| `isSparkleHedgehogEnabled` | `false` | Activates the sparkleHedgehog prototype. See [codenames](#sparklehedgehog) below. | +| `isMidnightOwlEnabled` | `false` | Activates the midnightOwl prototype. Has a corresponding `setEnabled()` Swift native API method, indicating macOS system-level integration beyond the web layer. | +| `isPhoenixRisingAgainEnabled` | `false` | Debug override for a new auto-updater system. The "Again" suffix indicates this replaces a previous updater. | +| `isChicagoEnabled` | `false` | Forces `chicago_config.enabled` and `teachModeEnabled` to `true` regardless of GrowthBook remote config. Requires restart. | + +--- + +## Internal Codenames + +Anthropic uses an adjective+animal naming convention for internal prototypes (with one geographic exception). Each codename has its own configuration keys in the app's settings store. + +### sparkleHedgehog + +| Key | Default | Type | +|-----|---------|------| +| `sparkleHedgehogAppearance` | `"default"` | string | +| `sparkleHedgehogScale` | `1` | number | + +Has an `appearance` setting (implying multiple appearances) and a `scale` factor. The keys are consistent with a UI appearance/theme system or a visual element with configurable size and style. + +### plushRaccoon + +| Key | Default | Type | +|-----|---------|------| +| `plushRaccoonEnabled` | — | bool | +| `plushRaccoonOption1` | `"off"` | string | +| `plushRaccoonOption2` | `"off"` | string | +| `plushRaccoonOption3` | `"off"` | string | + +Three independently togglable sub-options, all defaulting to `"off"` as strings (not booleans), suggesting they may have more states than just on/off. Purpose not determined from binary analysis alone. + +### quietPenguin + +| Key | Default | Type | +|-----|---------|------| +| `quietPenguinEnabled` | — | bool | + +Single on/off toggle. Name suggests notification suppression or a do-not-disturb mode. + +### louderPenguin + +| Key | Default | Type | +|-----|---------|------| +| `louderPenguinEnabled` | — | bool | + +Counterpart to quietPenguin. Same structure. Name suggests enhanced notifications or more aggressive alerting. These two form a notification spectrum: quiet ← normal → louder. + +### chillingSloth + +| Key | Default | Type | +|-----|---------|------| +| `chillingSlothLocation` | `"default"` | string | + +A `location` setting with a `"default"` value. Consistent with an idle-state behavior or ambient UI element that can appear in different positions (toolbar, menu bar, floating overlay, system tray, etc.). + +### midnightOwl + +| Key | Type | +|-----|------| +| Feature flag: `isMidnightOwlEnabled` | bool | +| Swift API: `midnightOwl.setEnabled()` | method | + +Has both a feature flag and a Swift native API `setEnabled()` method through `@ant/claude-swift`, meaning it hooks into macOS at the system level. The "midnight" prefix and native integration are consistent with scheduled background tasks or time-based automation. The existence of `coworkScheduledTasksEnabled` and `ccdScheduledTasksEnabled` config keys (both `false`) suggests scheduled task infrastructure exists in the app. + +### floatingAtoll + +| Key | Default | Type | +|-----|---------|------| +| `floatingAtollActive` | — | bool | +| *(dimensions)* | 320 × 54 px | hardcoded | +| *(offset)* | 12 px | hardcoded | + +A floating UI element with hardcoded pixel dimensions: 320px wide, 54px tall, with a 12px offset. This is the quick-access floating bar — visible to users in Cowork sessions. The naming parallels Apple's Dynamic Island ("atoll" = ring-shaped island). At 320×54px it fits a slim toolbar or single-line input. Corresponds to the `quickAccess` Swift native API. + +### chicago + +| Key | Default | Type | +|-----|---------|------| +| `chicagoEnabled` | — | bool | +| `chicagoAutoUnhide` | — | bool | +| `chicagoUserDeniedBundleIds` | — | string[] | +| Feature flag: `isChicagoEnabled` | `false` | bool (overrides GrowthBook) | +| Related: `teachModeEnabled` | — | bool | + +The most well-documented codename and the only one that breaks the animal naming convention. This is the interactive teach mode / guided walkthrough system (see [computer-use-tools.md](computer-use-tools.md#teach-mode-request_teach_access--teach_step) for the teach mode tools). `chicagoUserDeniedBundleIds` tracks which macOS applications the user has declined to grant Claude access to during walkthroughs. + +--- + +## Swift Native APIs (`@ant/claude-swift`) + +The `@ant/claude-swift` module is a native addon bridging Claude's Electron UI with macOS system capabilities. + +| API Namespace | Purpose | +|---------------|---------| +| `quickAccess` | Floating quick-access panel. System-level window management for the always-available Claude input (floatingAtoll). | +| `notifications` | macOS native notification delivery via Notification Center. | +| `desktop` | Desktop environment integration — window positioning, display detection. | +| `api` | Direct API communication layer for authenticated requests to Anthropic's backend. | +| `midnightOwl` | Native hook for the midnightOwl prototype. Exposes `setEnabled()`. | +| `vm` | Virtual machine management — `isRunning`, `isGuestConnected`. Handles lifecycle for Cowork's Linux VMs. | +| `hotkey` | Global keyboard shortcut registration. Works even when the app isn't focused. | +| `permissionFixer` | macOS permission remediation. Guides users through granting accessibility, screen recording, or automation permissions. | +| `computerUse` | Computer use capability bindings — screen reading, mouse/keyboard control, GUI automation. Separate SPM product, `computer_use.node`, nest builds only. | + +--- + +## Configuration Keys + +Additional configuration keys found in the app's settings store. + +### Security & Permissions + +| Key | Default | Notes | +|-----|---------|-------| +| `secureVmFeaturesEnabled` | `true` | VM sandboxing — Claude's compute runs in isolation | +| `bypassPermissionsModeEnabled` | `false` | Skip permission checks. Dev-only. | +| `autoPermissionsModeEnabled` | `false` | Auto-grant permissions without user confirmation. Dev-only. | +| `allowAllBrowserActions` | `false` | Unrestricted browser automation | +| `dispatchTrustedCodeWorkspaces` | `[]` | Folders where code execution is trusted without confirmation | +| `localAgentModeTrustedFolders` | `[]` | Folders trusted for local agent operations | + +### Launch & Session + +| Key | Default | Notes | +|-----|---------|-------| +| `launchEnabled` | `true` | Whether the app is allowed to launch | +| `launchPreviewPersistSession` | `false` | Persist preview sessions across app restarts | + +### Capabilities + +| Key | Default | Notes | +|-----|---------|-------| +| `coworkWebSearchEnabled` | `true` | Web search in Cowork mode | +| `coworkScheduledTasksEnabled` | `false` | Scheduled/recurring tasks in Cowork | +| `ccdScheduledTasksEnabled` | `false` | Scheduled tasks in Claude Code Desktop | +| `keepAwakeEnabled` | `false` | Prevent system sleep while Claude is working | +| `dockBounceEnabled` | `false` | Bounce Claude's dock icon for attention | + +--- + +## The Clod Avatar + +`default.clod` is a zip archive found in the app binary containing assets for an alternative AI persona: + +| File | Contents | +|------|---------| +| `personality.txt` | Persona definition ("You are Clod, a minimalist AI assistant...") | +| `cursor.png` | Custom mouse cursor graphic | +| `idling_0.png`, `idling_1.png`, `idling_2.png` | Idle animation frames | +| `working_0.png`, `working_1.png`, `working_2.png`, `working_3.png` | Working animation frames | +| `celebrating_0.png`, `celebrating_1.png` | Success animation frames | +| `error_0.png` | Error state | + +"Clod" is a play on "Claude." The `.clod` format is a self-contained avatar package: personality definition plus sprite sheets for different states (idle, working, celebrating, error). The working animation has multiple frames for a looping animation during processing. + +This may connect to sparkleHedgehog — the `appearance` and `scale` settings could control which `.clod` avatar is active and how large it renders. The `.clod` format being a zip archive means custom avatar packs could be created and distributed. + +--- + +## Apple App References + +String references found in `index.js` suggesting planned or gated native integrations: + +Calendar, Reminders, Notes, Contacts, Photos, Health, Maps, Safari, Shortcuts, Music, Freeform, Focus + +No tool registration patterns (`name` + `inputSchema`) were found for any of these in the current binary. These are string references only — they may represent planned integrations, configuration labels, or permission identifiers rather than functional tool implementations. diff --git a/tool-catalog/hidden-tools/office-addin-tools.md b/tool-catalog/hidden-tools/office-addin-tools.md new file mode 100644 index 0000000..945a162 --- /dev/null +++ b/tool-catalog/hidden-tools/office-addin-tools.md @@ -0,0 +1,154 @@ +# Office Add-in Tools (5 tools) + +**Status:** UNTESTED — requires Microsoft Office (Excel/Word/PowerPoint) with the Claude add-in connected. `tool_search` returns nothing for "office", "workbook", or "addin" in any session type, indicating these tools are only registered when the Office add-in WebSocket bridge is active. + +**Verified:** 2026-03-19. Could not test (no Office installed). Schemas documented from binary extraction only. + +Tools for direct Excel/Word/PowerPoint integration via the Claude add-in panel. Requires the Office add-in to be installed and connected to Claude Desktop. + +**Manifest URL:** `https://pivot.claude.ai/manifest.xml` +**Add-in UUID:** `29673e3c-d826-4f00-92ee-162334a52b1a` +**Module ID:** `office-addin` +**OAuth scope (when enabled):** `user:inference user:office` + +--- + +## open_office_file + +Opens an Office file in the default application and automatically opens the Claude add-in panel. + +On macOS, the add-in is opened using the Accessibility API (requires Accessibility permissions). On Windows, the add-in auto-opens via manifest configuration. + +After opening, use `office_addin_run` or `office_addin_get_context` to interact with the file. + +### Parameters + +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `path` | string | **yes** | Absolute path to the Office file to open | + +### Supported file types +- `.xlsx` → Microsoft Excel +- `.docx` → Microsoft Word +- `.pptx` → Microsoft PowerPoint + +### Notes +- macOS requires Accessibility permissions for the add-in panel auto-open +- The app-to-application mapping is hardcoded +- Throws `Unknown Office extension` for any other file type +- The tool description mentions `office_addin_task` as an alternative to `office_addin_run` — this name appears in the description text but has no separate tool registration + +--- + +## close_office_file + +Closes an Office file that is currently open. + +### Parameters + +| Param | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `path` | string | **yes** | — | Absolute path to the Office file to close | +| `save_changes` | boolean | no | `true` | If true, saves changes before closing. If false, discards changes. | + +### Notes +- Only works with `.xlsx`, `.docx`, `.pptx` +- The file must actually be open in the corresponding Office application +- Default is to save + +--- + +## office_addin_run + +Execute Office.js code directly in Excel. Changes appear instantly in the document. + +The code runs inside `Excel.run()` with `context` available. + +### Parameters + +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `code` | string | **yes** | Office.js code to execute. Has `context` object available. Must call `await context.sync()` to apply changes. | +| `display_message` | string | no | Brief user-friendly action label shown in the add-in UI (e.g., "Calculate sum", "Create chart") | +| `workbook` | string | no | Target workbook ID (addinId). If not specified, uses the currently selected workbook. Use `list_connected_workbooks` to see available workbooks. | + +### Code examples from description + +Write to cell: +```javascript +context.workbook.worksheets.getActiveWorksheet().getRange("A1").values = [["Hello"]]; +await context.sync(); +``` + +Read data: +```javascript +const range = context.workbook.worksheets.getActiveWorksheet().getRange("A1:B10"); +range.load("values"); +await context.sync(); +range.values; // Returns the data +``` + +### Notes +- **Must call `await context.sync()`** after making changes +- User must have the Excel add-in open and connected to Claude Desktop +- Currently only described for Excel, even though `open_office_file` supports Word and PowerPoint +- The `display_message` shows in the add-in UI as a status indicator + +--- + +## office_addin_get_context + +Fetch current spreadsheet context: selection, sheets, recent changes, and add-in conversation history. + +### Parameters + +| Param | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `include_changes` | boolean | no | `true` | Include user change events (edits, inserts, deletes, etc.) | +| `include_conversation` | boolean | no | `true` | Include the add-in conversation history | +| `include_selection` | boolean | no | `true` | Include current cursor/selection and its values | +| `include_sheets` | boolean | no | `true` | Include sheet metadata (names, dimensions, frozen rows/cols) | +| `max_changes` | number | no | `100` | Maximum number of change events to return | +| `max_messages` | number | no | `50` | Maximum number of conversation messages to return | +| `workbook` | string | no | — | Target workbook ID (addinId). If not specified, uses currently selected workbook. | + +### Returns +- Current selection address and values +- All sheet names and metadata +- Recent user edits, inserts, deletes +- Prior conversation with the add-in Claude + +### Notes +- The "add-in conversation" is a separate conversation the user may have had with the Claude embedded in Excel — this provides context on what was discussed +- All includes default to `true` — pass `false` to reduce response size + +--- + +## list_connected_workbooks + +List all Excel workbooks currently connected via the Claude add-in. + +### Parameters + +None. + +### Returns + +Connected workbooks with their IDs, document names, and connection details. Use the returned workbook IDs to target specific workbooks in `office_addin_run` and `office_addin_get_context`. + +### Notes +- Returns `addinId` values used as the `workbook` parameter in other tools +- Multiple workbooks can be connected simultaneously +- Connection is via WebSocket (`wss://localhost:8766` or configured `OFFICE_ADDIN_BRIDGE_URL`) +- If no workbooks are connected, the other tools default to "currently selected" which may fail + +--- + +## Architecture + +The Office add-in system uses: +1. **WebSocket bridge** — connects Claude Desktop to the Excel add-in running inside Office +2. **OAuth authentication** — uses the user's Claude token with `user:office` scope +3. **Office.js API** — code runs in Excel's JavaScript runtime via `Excel.run()` +4. **Accessibility API** (macOS) — used to auto-open the add-in panel when opening files +5. **Profile API** — fetches user's account UUID from `{apiHost}/api/oauth/profile` diff --git a/tool-catalog/hidden-tools/preview-tools.md b/tool-catalog/hidden-tools/preview-tools.md new file mode 100644 index 0000000..c31cc43 --- /dev/null +++ b/tool-catalog/hidden-tools/preview-tools.md @@ -0,0 +1,165 @@ +# Preview Tools + +**Status:** CONFIRMED in Claude Desktop **code task sessions** (via `start_code_task` from Dispatch). Registered under `mcp__Claude_Preview__` namespace. Not available in Cowork task sessions, Dispatch orchestrator, or Claude Code CLI. + +**Total:** 13 tools + +**Verified:** 2026-03-19. `preview_start` successfully launched a Vite dev server (port 9322). `preview_list` returned `[]` when no servers running, then showed the running server. `preview_screenshot`, `preview_snapshot`, `preview_eval`, `preview_console_logs` all returned valid responses. Screenshot showed blank page due to misconfigured `launch.json` (not a tool issue). + +--- + +## preview_start + +Start a dev server by name from `.claude/launch.json`. Reuses the server if already running. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | yes | Server name from .claude/launch.json | + +**Notes:** Tool description says "ALWAYS use this instead of Bash for running servers." Requires a `.claude/launch.json` config file in the project. + +--- + +## preview_stop + +Stop a server started with `preview_start`. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID to stop | + +--- + +## preview_list + +List servers started with `preview_start`. Returns `serverId` values for use with other `preview_*` tools. + +No parameters. + +--- + +## preview_logs + +Get server stdout/stderr output. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| level | enum | no | "all" (default) or "error" (lines containing error/exception/failed/fatal) | +| lines | number | no | Max lines to return (default 50) | +| search | string | no | Filter for specific text | + +--- + +## preview_console_logs + +Get browser console output (log, info, warn, error, debug). + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| level | enum | no | "all" (default), "error" (errors only), "warn" (warnings + errors) | +| lines | number | no | Max lines to return (default 50, max 200) | + +--- + +## preview_screenshot + +Take a screenshot of the page. Returns compressed JPEG. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | + +**Notes:** Tool description warns: "DO NOT rely on it for verifying colors, font sizes, or precise styles — use `preview_inspect` with specific CSS properties instead." + +--- + +## preview_snapshot + +Get an accessibility tree snapshot of the page. Returns text content, roles, and element UIDs. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | + +**Notes:** "PREFERRED over screenshot for verifying text, element presence, and page structure." UIDs can be used with `preview_click` / `preview_fill`. + +--- + +## preview_inspect + +Inspect a DOM element by CSS selector. Returns text content, className, tagName, id, computed styles, and bounding box. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| selector | string | yes | CSS selector (e.g. '.button', '#header') | +| styles | string[] | no | CSS properties to return (e.g. ['padding', 'color']). Defaults to common properties. | + +**Notes:** "BEST tool for verifying visual properties like colors, fonts, spacing, and dimensions — more accurate than screenshots." + +--- + +## preview_click + +Click an element by CSS selector. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| selector | string | yes | CSS selector (e.g. 'button.primary', '#submit', '[data-testid="btn"]') | +| doubleClick | boolean | no | Perform a double-click | + +--- + +## preview_fill + +Fill an input, textarea, or select element with a value. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| selector | string | yes | CSS selector for the input element | +| value | string | yes | Value to fill. For select elements, matches by value or text. | + +--- + +## preview_eval + +Execute JavaScript in the preview page. For debugging and inspection only. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| expression | string | yes | JavaScript expression to evaluate in page context. Return value is sent back. | + +**Notes:** "Do NOT use this to implement UI changes the user requests — edit the source code instead. Any DOM modifications via eval are temporary and lost on reload. Wrap multi-step logic in an IIFE." + +--- + +## preview_network + +List network requests or inspect a specific response body. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| filter | enum | no | "all" (default) or "failed" (4xx/5xx and network errors). Ignored when `requestId` provided. | +| requestId | string | no | If provided, returns full response body for that request. | + +**Notes:** Without `requestId`, lists all requests with URL, method, status, and `requestId`. With `requestId`, returns the full response body. + +--- + +## preview_resize + +Resize the preview viewport for responsive layout testing. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| serverId | string | yes | Server ID | +| preset | enum | no | "mobile" (375x812), "tablet" (768x1024), "desktop" (1280x800). Overrides width/height. | +| width | number | no | Viewport width in pixels | +| height | number | no | Viewport height in pixels | +| colorScheme | string | no | Color scheme emulation for dark mode testing | diff --git a/tool-catalog/hidden-tools/terminal-and-roots.md b/tool-catalog/hidden-tools/terminal-and-roots.md new file mode 100644 index 0000000..b16e359 --- /dev/null +++ b/tool-catalog/hidden-tools/terminal-and-roots.md @@ -0,0 +1,48 @@ +# Terminal & Roots Tools + +**Status:** NOT FOUND in any tested session type. `tool_search` returns nothing for "read_terminal", "get_roots", "roots", or "terminal" in Dispatch, Cowork tasks, code tasks, or Claude Code CLI. These are likely injected only in IDE integration contexts (VS Code extension, JetBrains plugin). + +**Total:** 2 tools + +**Verified:** 2026-03-19. Tested in Dispatch orchestrator, Cowork task session, code task session, and Claude Code CLI — not found in any. + +--- + +## read_terminal + +Read the contents of the user's integrated terminal panel. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| lines | number | no | How many trailing lines to return. Default 200, max 1000. | +| wait_for_output_ms | number | no | Block up to this many ms for new output to arrive before reading. | + +**Returns:** The last ~200 lines with ANSI codes stripped. + +**When to use (from tool description):** "Use when the user references test output, errors, or 'this' in a way that implies terminal content." + +**`wait_for_output_ms` behavior:** Blocks up to the specified duration for new output to arrive before reading. Designed for test watchers (Jest, Vitest, etc.) — edit a file, then `read_terminal` with a wait to get the watcher's response. If no new output arrives, returns the current buffer with a note. + +**Notes:** +- ANSI codes are stripped from output +- Only reads the integrated terminal panel — not arbitrary shell sessions +- Max 1000 lines; for longer outputs you only get the tail + +--- + +## get_roots + +Returns the file roots advertised to MCP servers in this session. + +No parameters. + +**Returns:** List of root URIs with optional names: +``` +Available file roots (N): +• file:///path/to/root (name) +• file:///path/to/another +``` + +**Notes:** +- Returns "No roots available. No folders have been selected for this session." if no folders are mounted +- Diagnostic/introspection tool — useful for debugging MCP server access issues diff --git a/tool-catalog/hidden-tools/widget-tools.md b/tool-catalog/hidden-tools/widget-tools.md new file mode 100644 index 0000000..124f6e4 --- /dev/null +++ b/tool-catalog/hidden-tools/widget-tools.md @@ -0,0 +1,92 @@ +# Widget Tools + +**Status:** CONFIRMED in Claude Desktop main chat and claude.ai web chat. Not exposed via `tool_search` in any agentic context — these are Electron renderer-only tools injected into the chat UI layer by `@ant/imagine-server`, not registered through the MCP tool system. + +**Total:** 2 tools + +**Verified:** 2026-03-19. Tested in Dispatch orchestrator, Cowork task session, code task session, Claude Code CLI (not found), and claude.ai web chat (confirmed working). + +![Widget rendering in claude.ai web chat](./widget-screenshot.png) +*Screenshot: Interactive architecture diagram rendered inline via `show_widget`. Captured 2026-03-19 in claude.ai web chat.* + +--- + +## read_me + +Returns required context for `show_widget` (CSS variables, colors, typography, layout rules, examples). Must be called before the first `show_widget` call. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| modules | string[] | no | Which module(s) to load. Options: "diagram", "mockup", "interactive", "data_viz", "art", "chart" | + +**Notes:** The tool description instructs the model: "Call before your first show_widget call. Do NOT mention or narrate this call to the user — it is an internal setup step. Call it silently and proceed directly to the visualization." + +**Returns:** CSS variables, color palettes, typography rules, layout rules, and examples for the requested modules. The `diagram` module alone returns ~300 lines of design system docs including SVG setup rules, color palette tables, font calibration, and full worked examples. + +**Behavior notes:** +- Must be called before any `show_widget` call — `show_widget` depends on the context this provides +- Can be called again later to load a different module set + +--- + +## show_widget (registered as "visualize widget") + +Renders SVG or HTML content progressively as it streams, displayed inline in the chat. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| title | string | yes | Snake_case identifier for the widget. Used as download filename. | +| loading_messages | string[] | yes | 1-4 loading messages shown while rendering. ~5 words each. Match user's language. Use 1 for simple, more for complex. | +| widget_code | string | yes | Raw SVG or HTML fragment to render. | + +**Behavior:** +- Auto-detects content type: starts with ``, ``, or `` tags in HTML mode — content fragments only +- External resources restricted to `cdnjs.cloudflare.com`, `esm.sh`, `cdn.jsdelivr.net`, `unpkg.com` (CSP-enforced) +- `localStorage` / `sessionStorage` not available — all state must live in React/JS memory +- For serious topics (illness, death, grief, war, etc.) loading messages should be subdued + +**Use cases:** Flowcharts, architecture diagrams, dashboards, forms, calculators, data tables, games, illustrations, or any visual content that benefits from inline rendering. + +--- + +## Rendering Modes + +Two rendering modes are referenced in the system prompt documentation: + +### `imagine_html` +For interactive content: sliders, buttons, live state displays, charts. The system prompt instructs keeping prose explanations in the normal response text, not embedded in HTML. No card wrapper — whitespace is the container. + +### `imagine_svg` +For diagrams. The widget automatically wraps SVG output in a card. The system prompt includes guidance on choosing diagram type based on intent (reference diagram vs. conceptual illustration). + +These are NOT separate tools — they are conceptual rendering modes within `show_widget`. Content type is detected automatically based on whether the content starts with `