mr0xb/dotfiles
Watch
1
0
Fork
You've already forked dotfiles
 0
mirror of https://github.com/mr0xb/dotfiles.git synced 2026-08-28 03:44:57 -04:00
Code Issues Projects Releases Packages Wiki Activity
dotfiles/.claude/projects/-Users-steve-briggs/2f266a34-3639-442a-bf64-5c2a9eee6fcf/subagents/agent-a6e013aa57a31cae7.jsonl
mr0xb a89c144cd9
 updates
2026-05-22 15:54:54 -04:00

22 lines
121 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{"parentUuid":null,"isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":"I need a definitive answer about Claude Code's theme customization, current as of late 2025 / early 2026 (Claude Code 2.1.126).\n\nSpecifically:\n\n1. What are the built-in themes accessible via `/theme` or settings.json's `theme` field? List them all.\n\n2. Does Claude Code support **user-defined custom color themes** — i.e., can a user supply a JSON file or inline definition that maps Claude Code's UI elements (prompt, syntax highlighting in code blocks, tool-use indicators, diff colors, status line, etc.) to arbitrary hex colors? If yes, give me the schema/file location/exact mechanism.\n\n3. If custom themes aren't supported, what's the closest workaround? I'm thinking the answer is \"Claude Code uses ANSI colors that follow the user's terminal scheme\" — confirm or correct that.\n\n4. Is there any way to override individual colors (not a full theme) — e.g., just the prompt color, just the diff colors? Hooks? Settings? Env vars?\n\nI'm asking because a user wants me to \"create a Claude Code theme\" with a specific color palette, and I want to give them an honest answer about what's actually possible rather than fabricating a non-existent feature. Please report under 250 words."},"uuid":"53668389-526c-443a-aeeb-ecd46a98fbd8","timestamp":"2026-05-04T17:51:45.162Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"53668389-526c-443a-aeeb-ecd46a98fbd8","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01AKyCmhVzdyMa2xbgQJkEzo","type":"message","role":"assistant","content":[{"type":"text","text":"I'll fetch the official Claude Code documentation to give you a definitive answer."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":10654,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":10654,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxGzRJLA7g1APxa1s7x","attributionAgent":"claude-code-guide","type":"assistant","uuid":"27f9dd2c-c934-4bb0-bf7f-41d70dc091e6","timestamp":"2026-05-04T17:51:46.445Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"27f9dd2c-c934-4bb0-bf7f-41d70dc091e6","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01AKyCmhVzdyMa2xbgQJkEzo","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01Auu2Qn2y4qqauie27bjryw","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/claude_code_docs_map.md","prompt":"theme customization color settings built-in themes"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":10654,"cache_read_input_tokens":0,"output_tokens":115,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":10654},"inference_geo":"","iterations":[{"input_tokens":3,"output_tokens":115,"cache_read_input_tokens":0,"cache_creation_input_tokens":10654,"cache_creation":{"ephemeral_5m_input_tokens":10654,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011CahxGzRJLA7g1APxa1s7x","attributionAgent":"claude-code-guide","type":"assistant","uuid":"afaac9dc-7b2a-45ac-9123-10033e8e1549","timestamp":"2026-05-04T17:51:46.984Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"afaac9dc-7b2a-45ac-9123-10033e8e1549","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01Auu2Qn2y4qqauie27bjryw","type":"tool_result","content":"<persisted-output>\nOutput too large (76.9KB). Full output saved to: /Users/steve.briggs/.claude/projects/-Users-steve-briggs/2f266a34-3639-442a-bf64-5c2a9eee6fcf/tool-results/toolu_01Auu2Qn2y4qqauie27bjryw.txt\n\nPreview (first 2KB):\n> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Claude code docs map\n\n# Claude Code Documentation Map\n\nThis is a comprehensive map of all Claude Code documentation pages with their headings, designed for easy navigation by LLMs.\n\n> **Note:** This file is auto-generated by GitHub Actions. Do not edit manually.\n> Last updated: 2026-05-04 14:18:49 UTC\n\n## Document Structure\n\nThis map uses a hierarchical structure:\n\n* **##** marks documentation groups (e.g., 'Getting started')\n* **###** marks individual documentation pages\n* **Nested bullets** show the heading structure within each page\n* Each page title links to the full documentation\n\n## Getting started\n\n### [overview](https://code.claude.com/docs/en/overview.md)\n\n* Get started\n* What you can do\n* Use Claude Code everywhere\n* Next steps\n\n### [quickstart](https://code.claude.com/docs/en/quickstart.md)\n\n* Before you begin\n* Step 1: Install Claude Code\n* Step 2: Log in to your account\n* Step 3: Start your first session\n* Step 4: Ask your first question\n* Step 5: Make your first code change\n* Step 6: Use Git with Claude Code\n* Step 7: Fix a bug or add a feature\n* Step 8: Test out other common workflows\n* Essential commands\n* Pro tips for beginners\n* What's next?\n* Getting help\n\n### [changelog](https://code.claude.com/docs/en/changelog.md)\n\n* (No headings found)\n\n## Core concepts\n\n### [how-claude-code-works](https://code.claude.com/docs/en/how-claude-code-works.md)\n\n* The agentic loop\n * Models\n * Tools\n* What Claude can access\n* Environments and interfaces\n * Execution environments\n * Interfaces\n* Work with sessions\n * Work across branches\n * Resume or fork sessions\n * The context window\n * When context fills up\n * Manage context with skills and subagents\n* Stay safe with checkpoints and permissions\n * Undo changes with checkpoints\n * Control what Claude can do\n...\n</persisted-output>"}]},"uuid":"a9fd4678-b625-4a2f-b624-cf3749aa362d","timestamp":"2026-05-04T17:51:48.099Z","sourceToolAssistantUUID":"afaac9dc-7b2a-45ac-9123-10033e8e1549","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"a9fd4678-b625-4a2f-b624-cf3749aa362d","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01LywC5gG31jwwPh9CDYkXAx","type":"message","role":"assistant","content":[{"type":"text","text":"Let me fetch the settings and customization documentation."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":5,"cache_creation_input_tokens":952,"cache_read_input_tokens":10654,"cache_creation":{"ephemeral_5m_input_tokens":952,"ephemeral_1h_input_tokens":0},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxHD7Hpndj5dNTCi6ee","attributionAgent":"claude-code-guide","type":"assistant","uuid":"52593986-e3f0-4ed9-b240-50d16b2d03ca","timestamp":"2026-05-04T17:51:49.062Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"52593986-e3f0-4ed9-b240-50d16b2d03ca","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01LywC5gG31jwwPh9CDYkXAx","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01Tpy6paWaf1QTrRVjmUB52u","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/settings.md","prompt":"theme color customization built-in themes"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":5,"cache_creation_input_tokens":952,"cache_read_input_tokens":10654,"cache_creation":{"ephemeral_5m_input_tokens":952,"ephemeral_1h_input_tokens":0},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxHD7Hpndj5dNTCi6ee","attributionAgent":"claude-code-guide","type":"assistant","uuid":"179db0fb-4265-4e2d-a6ca-e43cb55ad351","timestamp":"2026-05-04T17:51:49.529Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"179db0fb-4265-4e2d-a6ca-e43cb55ad351","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01LywC5gG31jwwPh9CDYkXAx","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_011Esjs5KiaWtuH9r6xmvmi1","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/configuration.md","prompt":"theme color settings customization"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":5,"cache_creation_input_tokens":952,"cache_read_input_tokens":10654,"output_tokens":173,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":952},"inference_geo":"","iterations":[{"input_tokens":5,"output_tokens":173,"cache_read_input_tokens":10654,"cache_creation_input_tokens":952,"cache_creation":{"ephemeral_5m_input_tokens":952,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011CahxHD7Hpndj5dNTCi6ee","attributionAgent":"claude-code-guide","type":"assistant","uuid":"15656daa-6294-477d-9168-406200879e7c","timestamp":"2026-05-04T17:51:49.683Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"15656daa-6294-477d-9168-406200879e7c","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_011Esjs5KiaWtuH9r6xmvmi1","type":"tool_result","content":"# Claude Code Settings Documentation\n\nClaude Code provides comprehensive configuration options through a **scope system** that determines where settings apply and who they affect.\n\n## Configuration Scopes\n\n| Scope | Location | Who it affects | Shared with team? |\n|-------|----------|---|---|\n| **Managed** | Server/MDM/system-level | All users on machine | Yes (IT-deployed) |\n| **User** | `~/.claude/` | You, all projects | No |\n| **Project** | `.claude/` in repo | All collaborators | Yes (git-committed) |\n| **Local** | `.claude/settings.local.json` | You, this repo only | No (gitignored) |\n\n## Scope Precedence\n\nWhen the same setting appears in multiple scopes, this hierarchy applies (highest to lowest):\n\n1. **Managed** - cannot be overridden\n2. **Command line arguments** - temporary session overrides\n3. **Local** - personal project overrides\n4. **Project** - team-shared settings\n5. **User** - personal global settings\n\n## Key Settings Files\n\n```json\n{\n \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n \"permissions\": {\n \"allow\": [\"Bash(npm run lint)\", \"Read(~/.zshrc)\"],\n \"deny\": [\"Bash(curl *)\", \"Read(./.env)\"]\n },\n \"env\": {\n \"CLAUDE_CODE_ENABLE_TELEMETRY\": \"1\"\n },\n \"model\": \"claude-sonnet-4-6\",\n \"sandbox\": {\n \"enabled\": true,\n \"filesystem\": {\n \"allowWrite\": [\"/tmp/build\"]\n }\n }\n}\n```\n\n## Important Features\n\n- **Array settings merge** across scopes (they concatenate, not replace)\n- **Managed settings** are the highest priority and cannot be overridden\n- **Automatic backups** - timestamped backups of config files (5 most recent retained)\n- **Run `/status`** to verify which settings sources are active\n\nFor detailed settings reference, see the complete [available settings table](https://code.claude.com/docs/settings) in the documentation."}]},"uuid":"75af261c-6dc0-4775-a662-b91727340a9c","timestamp":"2026-05-04T17:51:57.025Z","sourceToolAssistantUUID":"15656daa-6294-477d-9168-406200879e7c","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"179db0fb-4265-4e2d-a6ca-e43cb55ad351","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01Tpy6paWaf1QTrRVjmUB52u","type":"tool_result","content":"# Claude Code Settings Documentation\n\nClaude Code offers comprehensive configuration through a **scope system** with four levels of settings management:\n\n## Configuration Scopes\n\n| Scope | Location | Who it affects | Shared? |\n|-------|----------|---|---|\n| **Managed** | Server/MDM/system files | All machine users | Yes (IT-deployed) |\n| **User** | `~/.claude/` | You, all projects | No |\n| **Project** | `.claude/` in repo | Team collaborators | Yes (git-committed) |\n| **Local** | `.claude/settings.local.json` | You, this repo only | No (gitignored) |\n\n**Precedence** (highest to lowest):\n1. Managed settings (cannot be overridden)\n2. Command line arguments\n3. Local project settings\n4. Shared project settings\n5. User settings\n\n## Settings Files\n\n### Main Configuration (`settings.json`)\n\nLocations:\n- **User**: `~/.claude/settings.json`\n- **Project**: `.claude/settings.json`\n- **Local**: `.claude/settings.local.json`\n\n**Example**:\n```json\n{\n \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n \"permissions\": {\n \"allow\": [\"Bash(npm run lint)\", \"Read(~/.zshrc)\"],\n \"deny\": [\"Bash(curl *)\", \"Read(./.env)\"]\n },\n \"env\": {\n \"CLAUDE_CODE_ENABLE_TELEMETRY\": \"1\"\n }\n}\n```\n\n### Managed Settings\n\nDeployed through multiple mechanisms:\n- **Server-managed**: Via Claude.ai admin console\n- **macOS**: `com.anthropic.claudecode` plist or `/Library/Application Support/ClaudeCode/`\n- **Windows**: `HKLM\\SOFTWARE\\Policies\\ClaudeCode` or `C:\\Program Files\\ClaudeCode\\`\n- **Linux/WSL**: `/etc/claude-code/`\n\nFile-based managed settings support drop-in directories (`managed-settings.d/`) for modular policy fragments merged in alphabetical order.\n\n## Key Configuration Settings\n\n| Setting | Purpose | Example |\n|---------|---------|---------|\n| `permissions` | Allow/deny/ask tool usage | `{\"deny\": [\"Read(./.env)\"]}` |\n| `env` | Environment variables | `{\"MY_VAR\": \"value\"}` |\n| `model` | Default LLM model | `\"claude-sonnet-4-6\"` |\n| `autoMode` | Auto-mode classifier rules | `{\"soft_deny\": [\"$defaults\"]}` |\n| `sandbox` | Bash sandboxing config | `{\"enabled\": true}` |\n| `hooks` | Lifecycle event handlers | Custom commands |\n| `plugins` | Plugin marketplace config | `enabledPlugins`, `extraKnownMarketplaces` |\n| `agent` | Run as named subagent | `\"code-reviewer\"` |\n\n## Permission Rules\n\nFormat: `Tool` or `Tool(specifier)`\n\n**Examples**:\n```json\n{\n \"allow\": [\n \"Bash(npm run *)\",\n \"Read(./src/**)\"\n ],\n \"deny\": [\n \"Bash(curl *)\",\n \"Read(./.env)\",\n \"WebFetch(domain:sensitive.com)\"\n ]\n}\n```\n\n## Sandboxing Configuration\n\nEnable bash command isolation:\n```json\n{\n \"sandbox\": {\n \"enabled\": true,\n \"autoAllowBashIfSandboxed\": true,\n \"filesystem\": {\n \"allowWrite\": [\"/tmp/build\"],\n \"denyRead\": [\"~/.aws/credentials\"]\n },\n \"network\": {\n \"allowedDomains\": [\"github.com\", \"*.npmjs.org\"],\n \"deniedDomains\": [\"sensitive.cloud.example.com\"]\n }\n }\n}\n```\n\n## Verify Configuration\n\nRun `/status` in Claude Code to see:\n- Active settings sources\n- Origin (remote, plist, registry, file)\n- Configuration errors\n\n## Subagents and Plugins\n\n- **Subagents**: `~/.claude/agents/` (user) or `.claude/agents/` (project)\n- **Plugins**: Configured via `enabledPlugins` and `extraKnownMarketplaces`\n- **MCP servers**: `~/.claude.json` (user) or `.mcp.json` (project)\n\nFor complete settings reference and advanced configurations, visit the [documentation index](https://code.claude.com/docs/llms.txt)."}]},"uuid":"222dd8eb-7afb-439c-b314-fe62d891e7fe","timestamp":"2026-05-04T17:52:03.900Z","sourceToolAssistantUUID":"179db0fb-4265-4e2d-a6ca-e43cb55ad351","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"222dd8eb-7afb-439c-b314-fe62d891e7fe","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01SJj5PVRvbbQLxic5VopGhf","type":"message","role":"assistant","content":[{"type":"text","text":"I notice neither result mentions theme customization. Let me search the full documentation index more directly."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":550,"cache_creation_input_tokens":1315,"cache_read_input_tokens":11606,"cache_creation":{"ephemeral_5m_input_tokens":1315,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxJNdJoBgTMirAaXSup","attributionAgent":"claude-code-guide","type":"assistant","uuid":"d3826c56-d4b7-4a6c-9aaa-97dc2b54af53","timestamp":"2026-05-04T17:52:04.913Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"d3826c56-d4b7-4a6c-9aaa-97dc2b54af53","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01SJj5PVRvbbQLxic5VopGhf","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01HqYxmc8tTfeCvvnVv6dA33","name":"WebFetch","input":{"url":"https://code.claude.com/docs/llms.txt","prompt":"theme color customization UI appearance visual"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":550,"cache_creation_input_tokens":1315,"cache_read_input_tokens":11606,"cache_creation":{"ephemeral_5m_input_tokens":1315,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxJNdJoBgTMirAaXSup","attributionAgent":"claude-code-guide","type":"assistant","uuid":"1e0f5ae1-73f7-450b-a446-95aebb0bbd88","timestamp":"2026-05-04T17:52:05.707Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"1e0f5ae1-73f7-450b-a446-95aebb0bbd88","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01HqYxmc8tTfeCvvnVv6dA33","type":"tool_result","content":"# Theme Color Customization in Claude Code\n\nBased on the Claude Code documentation, theme color customization is available through **custom color themes that you can build and ship in plugins**.\n\n## Key Resources\n\n1. **Custom Color Themes in Plugins**\n - As mentioned in [Week 17 · April 20–24, 2026](https://code.claude.com/docs/en/whats-new/2026-w17.md): \"custom color themes you can build and ship in plugins\"\n - Themes can be created as part of Claude Code plugins for distribution\n\n2. **Related Documentation**\n - [Create plugins](https://code.claude.com/docs/en/plugins.md) - Create custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers\n - [Plugins reference](https://code.claude.com/docs/en/plugins-reference.md) - Complete technical reference for the plugin system, including schemas and component specifications\n - [Discover and install prebuilt plugins through marketplaces](https://code.claude.com/docs/en/discover-plugins.md) - Find and install plugins with themes from marketplaces\n\n3. **Terminal Configuration**\n - [Configure your terminal for Claude Code](https://code.claude.com/docs/en/terminal-config.md) - Match the color theme and configure terminal appearance\n\n4. **Status Line Customization**\n - [Customize your status line](https://code.claude.com/docs/en/statusline.md) - Configure a custom status bar for visual customization\n\n## Implementation\n\nTo create custom color themes, refer to the plugin development documentation and the plugins reference guide for the complete schema and component specifications needed to build and distribute your theme."}]},"uuid":"75ad7cc2-a230-46de-bf83-88fefad7a02b","timestamp":"2026-05-04T17:52:11.092Z","sourceToolAssistantUUID":"1e0f5ae1-73f7-450b-a446-95aebb0bbd88","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"75ad7cc2-a230-46de-bf83-88fefad7a02b","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01YLEifAXRxB58SvuDw2Y57R","type":"message","role":"assistant","content":[{"type":"text","text":"Good lead. Let me get the plugin reference documentation to understand the actual schema."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":4,"cache_creation_input_tokens":1056,"cache_read_input_tokens":12921,"cache_creation":{"ephemeral_5m_input_tokens":1056,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxJuJn73ZLt1nyWjpjx","attributionAgent":"claude-code-guide","type":"assistant","uuid":"5b55dc4d-23f0-49ca-92c8-002b16c00e5f","timestamp":"2026-05-04T17:52:12.146Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"5b55dc4d-23f0-49ca-92c8-002b16c00e5f","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01YLEifAXRxB58SvuDw2Y57R","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01F5RCux9tqUaN2a9JEsC8Vh","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/plugins-reference.md","prompt":"color theme schema UI elements colors"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":4,"cache_creation_input_tokens":1056,"cache_read_input_tokens":12921,"output_tokens":108,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":1056},"inference_geo":"","iterations":[{"input_tokens":4,"output_tokens":108,"cache_read_input_tokens":12921,"cache_creation_input_tokens":1056,"cache_creation":{"ephemeral_5m_input_tokens":1056,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011CahxJuJn73ZLt1nyWjpjx","attributionAgent":"claude-code-guide","type":"assistant","uuid":"75a636f9-988a-4d2b-8de8-aaf750cd1384","timestamp":"2026-05-04T17:52:12.365Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"75a636f9-988a-4d2b-8de8-aaf750cd1384","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01F5RCux9tqUaN2a9JEsC8Vh","type":"tool_result","content":"<persisted-output>\nOutput too large (58.3KB). Full output saved to: /Users/steve.briggs/.claude/projects/-Users-steve-briggs/2f266a34-3639-442a-bf64-5c2a9eee6fcf/tool-results/toolu_01F5RCux9tqUaN2a9JEsC8Vh.txt\n\nPreview (first 2KB):\n> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Plugins reference\n\n> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.\n\n<Tip>\n Looking to install plugins? See [Discover and install plugins](/en/discover-plugins). For creating plugins, see [Plugins](/en/plugins). For distributing plugins, see [Plugin marketplaces](/en/plugin-marketplaces).\n</Tip>\n\nThis reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.\n\nA **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, LSP servers, and monitors.\n\n## Plugin components reference\n\n### Skills\n\nPlugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke.\n\n**Location**: `skills/` or `commands/` directory in plugin root\n\n**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files\n\n**Skill structure**:\n\n```text theme={null}\nskills/\n├── pdf-processor/\n│ ├── SKILL.md\n│ ├── reference.md (optional)\n│ └── scripts/ (optional)\n└── code-reviewer/\n └── SKILL.md\n```\n\n**Integration behavior**:\n\n* Skills and commands are automatically discovered when the plugin is installed\n* Claude can invoke them automatically based on task context\n* Skills can include supporting files alongside SKILL.md\n\nFor complete details, see [Skills](/en/skills).\n\n### Agents\n\nPlugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.\n\n**Location**: `agents/` directory in plugin root\n\n**File format**: Markdown files describing agent capabilities\n\n**Agent structure**:\n\n```markdown theme={null}\n---\nname: agent-name\n...\n</persisted-output>"}]},"uuid":"212f8183-b78a-4b20-8e6f-a8538b0d4e1d","timestamp":"2026-05-04T17:52:13.126Z","sourceToolAssistantUUID":"75a636f9-988a-4d2b-8de8-aaf750cd1384","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"212f8183-b78a-4b20-8e6f-a8538b0d4e1d","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01UAAAfn5XDwABHhajawSkJe","type":"message","role":"assistant","content":[{"type":"text","text":"Let me search more specifically for the theme component schema in the plugins reference."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":694,"cache_read_input_tokens":13977,"cache_creation":{"ephemeral_5m_input_tokens":694,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxK41QBvkRtVKxwJ2iW","attributionAgent":"claude-code-guide","type":"assistant","uuid":"72c9e905-d6ce-44e0-bfec-2b07f2e42479","timestamp":"2026-05-04T17:52:14.174Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"72c9e905-d6ce-44e0-bfec-2b07f2e42479","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01UAAAfn5XDwABHhajawSkJe","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01NkyWKkYnqjEQ3efmrTXjnB","name":"Read","input":{"file_path":"/Users/steve.briggs/.claude/projects/-Users-steve-briggs/2f266a34-3639-442a-bf64-5c2a9eee6fcf/tool-results/toolu_01F5RCux9tqUaN2a9JEsC8Vh.txt"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":694,"cache_read_input_tokens":13977,"output_tokens":143,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":694},"inference_geo":"","iterations":[{"input_tokens":3,"output_tokens":143,"cache_read_input_tokens":13977,"cache_creation_input_tokens":694,"cache_creation":{"ephemeral_5m_input_tokens":694,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011CahxK41QBvkRtVKxwJ2iW","attributionAgent":"claude-code-guide","type":"assistant","uuid":"45060797-8678-4d6a-8c8c-711cd1a8629c","timestamp":"2026-05-04T17:52:14.446Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"45060797-8678-4d6a-8c8c-711cd1a8629c","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01NkyWKkYnqjEQ3efmrTXjnB","type":"tool_result","content":"1\t> ## Documentation Index\n2\t> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n3\t> Use this file to discover all available pages before exploring further.\n4\t\n5\t# Plugins reference\n6\t\n7\t> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.\n8\t\n9\t<Tip>\n10\t Looking to install plugins? See [Discover and install plugins](/en/discover-plugins). For creating plugins, see [Plugins](/en/plugins). For distributing plugins, see [Plugin marketplaces](/en/plugin-marketplaces).\n11\t</Tip>\n12\t\n13\tThis reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.\n14\t\n15\tA **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, LSP servers, and monitors.\n16\t\n17\t## Plugin components reference\n18\t\n19\t### Skills\n20\t\n21\tPlugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke.\n22\t\n23\t**Location**: `skills/` or `commands/` directory in plugin root\n24\t\n25\t**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files\n26\t\n27\t**Skill structure**:\n28\t\n29\t```text theme={null}\n30\tskills/\n31\t├── pdf-processor/\n32\t│ ├── SKILL.md\n33\t│ ├── reference.md (optional)\n34\t│ └── scripts/ (optional)\n35\t└── code-reviewer/\n36\t └── SKILL.md\n37\t```\n38\t\n39\t**Integration behavior**:\n40\t\n41\t* Skills and commands are automatically discovered when the plugin is installed\n42\t* Claude can invoke them automatically based on task context\n43\t* Skills can include supporting files alongside SKILL.md\n44\t\n45\tFor complete details, see [Skills](/en/skills).\n46\t\n47\t### Agents\n48\t\n49\tPlugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.\n50\t\n51\t**Location**: `agents/` directory in plugin root\n52\t\n53\t**File format**: Markdown files describing agent capabilities\n54\t\n55\t**Agent structure**:\n56\t\n57\t```markdown theme={null}\n58\t---\n59\tname: agent-name\n60\tdescription: What this agent specializes in and when Claude should invoke it\n61\tmodel: sonnet\n62\teffort: medium\n63\tmaxTurns: 20\n64\tdisallowedTools: Write, Edit\n65\t---\n66\t\n67\tDetailed system prompt for the agent describing its role, expertise, and behavior.\n68\t```\n69\t\n70\tPlugin agents support `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, and `isolation` frontmatter fields. The only valid `isolation` value is `\"worktree\"`. For security reasons, `hooks`, `mcpServers`, and `permissionMode` are not supported for plugin-shipped agents.\n71\t\n72\t**Integration points**:\n73\t\n74\t* Agents appear in the `/agents` interface\n75\t* Claude can invoke agents automatically based on task context\n76\t* Agents can be invoked manually by users\n77\t* Plugin agents work alongside built-in Claude agents\n78\t\n79\tFor complete details, see [Subagents](/en/sub-agents).\n80\t\n81\t### Hooks\n82\t\n83\tPlugins can provide event handlers that respond to Claude Code events automatically.\n84\t\n85\t**Location**: `hooks/hooks.json` in plugin root, or inline in plugin.json\n86\t\n87\t**Format**: JSON configuration with event matchers and actions\n88\t\n89\t**Hook configuration**:\n90\t\n91\t```json theme={null}\n92\t{\n93\t \"hooks\": {\n94\t \"PostToolUse\": [\n95\t {\n96\t \"matcher\": \"Write|Edit\",\n97\t \"hooks\": [\n98\t {\n99\t \"type\": \"command\",\n100\t \"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh\"\n101\t }\n102\t ]\n103\t }\n104\t ]\n105\t }\n106\t}\n107\t```\n108\t\n109\tPlugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):\n110\t\n111\t| Event | When it fires |\n112\t| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |\n113\t| `SessionStart` | When a session begins or resumes |\n114\t| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |\n115\t| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |\n116\t| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |\n117\t| `PreToolUse` | Before a tool call executes. Can block it |\n118\t| `PermissionRequest` | When a permission dialog appears |\n119\t| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |\n120\t| `PostToolUse` | After a tool call succeeds |\n121\t| `PostToolUseFailure` | After a tool call fails |\n122\t| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call |\n123\t| `Notification` | When Claude Code sends a notification |\n124\t| `SubagentStart` | When a subagent is spawned |\n125\t| `SubagentStop` | When a subagent finishes |\n126\t| `TaskCreated` | When a task is being created via `TaskCreate` |\n127\t| `TaskCompleted` | When a task is being marked as completed |\n128\t| `Stop` | When Claude finishes responding |\n129\t| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |\n130\t| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |\n131\t| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |\n132\t| `ConfigChange` | When a configuration file changes during a session |\n133\t| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |\n134\t| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |\n135\t| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: \"worktree\"`. Replaces default git behavior |\n136\t| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |\n137\t| `PreCompact` | Before context compaction |\n138\t| `PostCompact` | After context compaction completes |\n139\t| `Elicitation` | When an MCP server requests user input during a tool call |\n140\t| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |\n141\t| `SessionEnd` | When a session terminates |\n142\t\n143\t**Hook types**:\n144\t\n145\t* `command`: execute shell commands or scripts\n146\t* `http`: send the event JSON as a POST request to a URL\n147\t* `mcp_tool`: call a tool on a configured [MCP server](/en/mcp)\n148\t* `prompt`: evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)\n149\t* `agent`: run an agentic verifier with tools for complex verification tasks\n150\t\n151\t### MCP servers\n152\t\n153\tPlugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools and services.\n154\t\n155\t**Location**: `.mcp.json` in plugin root, or inline in plugin.json\n156\t\n157\t**Format**: Standard MCP server configuration\n158\t\n159\t**MCP server configuration**:\n160\t\n161\t```json theme={null}\n162\t{\n163\t \"mcpServers\": {\n164\t \"plugin-database\": {\n165\t \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server\",\n166\t \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config.json\"],\n167\t \"env\": {\n168\t \"DB_PATH\": \"${CLAUDE_PLUGIN_ROOT}/data\"\n169\t }\n170\t },\n171\t \"plugin-api-client\": {\n172\t \"command\": \"npx\",\n173\t \"args\": [\"@company/mcp-server\", \"--plugin-mode\"],\n174\t \"cwd\": \"${CLAUDE_PLUGIN_ROOT}\"\n175\t }\n176\t }\n177\t}\n178\t```\n179\t\n180\t**Integration behavior**:\n181\t\n182\t* Plugin MCP servers start automatically when the plugin is enabled\n183\t* Servers appear as standard MCP tools in Claude's toolkit\n184\t* Server capabilities integrate seamlessly with Claude's existing tools\n185\t* Plugin servers can be configured independently of user MCP servers\n186\t\n187\t### LSP servers\n188\t\n189\t<Tip>\n190\t Looking to use LSP plugins? Install them from the official marketplace: search for \"lsp\" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace.\n191\t</Tip>\n192\t\n193\tPlugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase.\n194\t\n195\tLSP integration provides:\n196\t\n197\t* **Instant diagnostics**: Claude sees errors and warnings immediately after each edit\n198\t* **Code navigation**: go to definition, find references, and hover information\n199\t* **Language awareness**: type information and documentation for code symbols\n200\t\n201\t**Location**: `.lsp.json` in plugin root, or inline in `plugin.json`\n202\t\n203\t**Format**: JSON configuration mapping language server names to their configurations\n204\t\n205\t**`.lsp.json` file format**:\n206\t\n207\t```json theme={null}\n208\t{\n209\t \"go\": {\n210\t \"command\": \"gopls\",\n211\t \"args\": [\"serve\"],\n212\t \"extensionToLanguage\": {\n213\t \".go\": \"go\"\n214\t }\n215\t }\n216\t}\n217\t```\n218\t\n219\t**Inline in `plugin.json`**:\n220\t\n221\t```json theme={null}\n222\t{\n223\t \"name\": \"my-plugin\",\n224\t \"lspServers\": {\n225\t \"go\": {\n226\t \"command\": \"gopls\",\n227\t \"args\": [\"serve\"],\n228\t \"extensionToLanguage\": {\n229\t \".go\": \"go\"\n230\t }\n231\t }\n232\t }\n233\t}\n234\t```\n235\t\n236\t**Required fields:**\n237\t\n238\t| Field | Description |\n239\t| :-------------------- | :------------------------------------------- |\n240\t| `command` | The LSP binary to execute (must be in PATH) |\n241\t| `extensionToLanguage` | Maps file extensions to language identifiers |\n242\t\n243\t**Optional fields:**\n244\t\n245\t| Field | Description |\n246\t| :---------------------- | :-------------------------------------------------------- |\n247\t| `args` | Command-line arguments for the LSP server |\n248\t| `transport` | Communication transport: `stdio` (default) or `socket` |\n249\t| `env` | Environment variables to set when starting the server |\n250\t| `initializationOptions` | Options passed to the server during initialization |\n251\t| `settings` | Settings passed via `workspace/didChangeConfiguration` |\n252\t| `workspaceFolder` | Workspace folder path for the server |\n253\t| `startupTimeout` | Max time to wait for server startup (milliseconds) |\n254\t| `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds) |\n255\t| `restartOnCrash` | Whether to automatically restart the server if it crashes |\n256\t| `maxRestarts` | Maximum number of restart attempts before giving up |\n257\t\n258\t<Warning>\n259\t **You must install the language server binary separately.** LSP plugins configure how Claude Code connects to a language server, but they don't include the server itself. If you see `Executable not found in $PATH` in the `/plugin` Errors tab, install the required binary for your language.\n260\t</Warning>\n261\t\n262\t**Available LSP plugins:**\n263\t\n264\t| Plugin | Language server | Install command |\n265\t| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- |\n266\t| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |\n267\t| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |\n268\t| `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |\n269\t\n270\tInstall the language server first, then install the plugin from the marketplace.\n271\t\n272\t### Monitors\n273\t\n274\tPlugins can declare background monitors that Claude Code starts automatically when the plugin is active. Each monitor runs a shell command for the lifetime of the session and delivers every stdout line to Claude as a notification, so Claude can react to log entries, status changes, or polled events without being asked to start the watch itself.\n275\t\n276\tPlugin monitors use the same mechanism as the [Monitor tool](/en/tools-reference#monitor-tool) and share its availability constraints. They run only in interactive CLI sessions, run unsandboxed at the same trust level as [hooks](#hooks), and are skipped on hosts where the Monitor tool is unavailable.\n277\t\n278\t<Note>\n279\t Plugin monitors require Claude Code v2.1.105 or later.\n280\t</Note>\n281\t\n282\t**Location**: `monitors/monitors.json` in the plugin root, or inline in `plugin.json`\n283\t\n284\t**Format**: JSON array of monitor entries\n285\t\n286\tThe following `monitors/monitors.json` watches a deployment status endpoint and a local error log:\n287\t\n288\t```json theme={null}\n289\t[\n290\t {\n291\t \"name\": \"deploy-status\",\n292\t \"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}\",\n293\t \"description\": \"Deployment status changes\"\n294\t },\n295\t {\n296\t \"name\": \"error-log\",\n297\t \"command\": \"tail -F ./logs/error.log\",\n298\t \"description\": \"Application error log\",\n299\t \"when\": \"on-skill-invoke:debug\"\n300\t }\n301\t]\n302\t```\n303\t\n304\tTo declare monitors inline, set the `monitors` key in `plugin.json` to the same array. To load from a non-default path, set `monitors` to a relative path string such as `\"./config/monitors.json\"`.\n305\t\n306\t**Required fields:**\n307\t\n308\t| Field | Description |\n309\t| :------------ | :-------------------------------------------------------------------------------------------------------------------- |\n310\t| `name` | Identifier unique within the plugin. Prevents duplicate processes when the plugin reloads or a skill is invoked again |\n311\t| `command` | Shell command run as a persistent background process in the session working directory |\n312\t| `description` | Short summary of what is being watched. Shown in the task panel and in notification summaries |\n313\t\n314\t**Optional fields:**\n315\t\n316\t| Field | Description |\n317\t| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n318\t| `when` | Controls when the monitor starts. `\"always\"` starts it at session start and on plugin reload, and is the default. `\"on-skill-invoke:<skill-name>\"` starts it the first time the named skill in this plugin is dispatched |\n319\t\n320\tThe `command` value supports the same [variable substitutions](#environment-variables) as MCP and LSP server configs: `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${user_config.*}`, and any `${ENV_VAR}` from the environment. Prefix the command with `cd \"${CLAUDE_PLUGIN_ROOT}\" && ` if the script needs to run from the plugin's own directory.\n321\t\n322\tDisabling a plugin mid-session does not stop monitors that are already running. They stop when the session ends.\n323\t\n324\t### Themes\n325\t\n326\tPlugins can ship color themes that appear in `/theme` alongside the built-in presets and the user's local themes. A theme is a JSON file in `themes/` with a `base` preset and a sparse `overrides` map of color tokens.\n327\t\n328\t```json theme={null}\n329\t{\n330\t \"name\": \"Dracula\",\n331\t \"base\": \"dark\",\n332\t \"overrides\": {\n333\t \"claude\": \"#bd93f9\",\n334\t \"error\": \"#ff5555\",\n335\t \"success\": \"#50fa7b\"\n336\t }\n337\t}\n338\t```\n339\t\n340\tSelecting a plugin theme persists `custom:<plugin-name>:<slug>` in the user's config. Plugin themes are read-only; pressing `Ctrl+E` on one in `/theme` copies it into `~/.claude/themes/` so the user can edit the copy.\n341\t\n342\t***\n343\t\n344\t## Plugin installation scopes\n345\t\n346\tWhen you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:\n347\t\n348\t| Scope | Settings file | Use case |\n349\t| :-------- | :---------------------------------------------- | :------------------------------------------------------- |\n350\t| `user` | `~/.claude/settings.json` | Personal plugins available across all projects (default) |\n351\t| `project` | `.claude/settings.json` | Team plugins shared via version control |\n352\t| `local` | `.claude/settings.local.json` | Project-specific plugins, gitignored |\n353\t| `managed` | [Managed settings](/en/settings#settings-files) | Managed plugins (read-only, update only) |\n354\t\n355\tPlugins use the same scope system as other Claude Code configurations. For installation instructions and scope flags, see [Install plugins](/en/discover-plugins#install-plugins). For a complete explanation of scopes, see [Configuration scopes](/en/settings#configuration-scopes).\n356\t\n357\t***\n358\t\n359\t## Plugin manifest schema\n360\t\n361\tThe `.claude-plugin/plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options.\n362\t\n363\tThe manifest is optional. If omitted, Claude Code auto-discovers components in [default locations](#file-locations-reference) and derives the plugin name from the directory name. Use a manifest when you need to provide metadata or custom component paths.\n364\t\n365\t### Complete schema\n366\t\n367\t```json theme={null}\n368\t{\n369\t \"name\": \"plugin-name\",\n370\t \"version\": \"1.2.0\",\n371\t \"description\": \"Brief plugin description\",\n372\t \"author\": {\n373\t \"name\": \"Author Name\",\n374\t \"email\": \"author@example.com\",\n375\t \"url\": \"https://github.com/author\"\n376\t },\n377\t \"homepage\": \"https://docs.example.com/plugin\",\n378\t \"repository\": \"https://github.com/author/plugin\",\n379\t \"license\": \"MIT\",\n380\t \"keywords\": [\"keyword1\", \"keyword2\"],\n381\t \"skills\": \"./custom/skills/\",\n382\t \"commands\": [\"./custom/commands/special.md\"],\n383\t \"agents\": [\"./custom/agents/reviewer.md\"],\n384\t \"hooks\": \"./config/hooks.json\",\n385\t \"mcpServers\": \"./mcp-config.json\",\n386\t \"outputStyles\": \"./styles/\",\n387\t \"themes\": \"./themes/\",\n388\t \"lspServers\": \"./.lsp.json\",\n389\t \"monitors\": \"./monitors.json\",\n390\t \"dependencies\": [\n391\t \"helper-lib\",\n392\t { \"name\": \"secrets-vault\", \"version\": \"~2.1.0\" }\n393\t ]\n394\t}\n395\t```\n396\t\n397\t### Required fields\n398\t\n399\tIf you include a manifest, `name` is the only required field.\n400\t\n401\t| Field | Type | Description | Example |\n402\t| :----- | :----- | :---------------------------------------- | :------------------- |\n403\t| `name` | string | Unique identifier (kebab-case, no spaces) | `\"deployment-tools\"` |\n404\t\n405\tThis name is used for namespacing components. For example, in the UI, the\n406\tagent `agent-creator` for the plugin with name `plugin-dev` will appear as\n407\t`plugin-dev:agent-creator`.\n408\t\n409\t### Metadata fields\n410\t\n411\t| Field | Type | Description | Example |\n412\t| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |\n413\t| `$schema` | string | JSON Schema URL for editor autocomplete and validation. Claude Code ignores this field at load time. | `\"https://json.schemastore.org/claude-code-plugin-manifest.json\"` |\n414\t| `version` | string | Optional. Semantic version. Setting this pins the plugin to that version string, so users only receive updates when you bump it. If omitted, Claude Code falls back to the git commit SHA, so every commit is treated as a new version. If also set in the marketplace entry, `plugin.json` wins. See [Version management](#version-management). | `\"2.1.0\"` |\n415\t| `description` | string | Brief explanation of plugin purpose | `\"Deployment automation tools\"` |\n416\t| `author` | object | Author information | `{\"name\": \"Dev Team\", \"email\": \"dev@company.com\"}` |\n417\t| `homepage` | string | Documentation URL | `\"https://docs.example.com\"` |\n418\t| `repository` | string | Source code URL | `\"https://github.com/user/plugin\"` |\n419\t| `license` | string | License identifier | `\"MIT\"`, `\"Apache-2.0\"` |\n420\t| `keywords` | array | Discovery tags | `[\"deployment\", \"ci-cd\"]` |\n421\t\n422\t### Component path fields\n423\t\n424\t| Field | Type | Description | Example |\n425\t| :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |\n426\t| `skills` | string\\|array | Custom skill directories containing `<name>/SKILL.md` (replaces default `skills/`) | `\"./custom/skills/\"` |\n427\t| `commands` | string\\|array | Custom flat `.md` skill files or directories (replaces default `commands/`) | `\"./custom/cmd.md\"` or `[\"./cmd1.md\"]` |\n428\t| `agents` | string\\|array | Custom agent files (replaces default `agents/`) | `\"./custom/agents/reviewer.md\"` |\n429\t| `hooks` | string\\|array\\|object | Hook config paths or inline config | `\"./my-extra-hooks.json\"` |\n430\t| `mcpServers` | string\\|array\\|object | MCP config paths or inline config | `\"./my-extra-mcp-config.json\"` |\n431\t| `outputStyles` | string\\|array | Custom output style files/directories (replaces default `output-styles/`) | `\"./styles/\"` |\n432\t| `themes` | string\\|array | Color theme files/directories (replaces default `themes/`). See [Themes](#themes) | `\"./themes/\"` |\n433\t| `lspServers` | string\\|array\\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) configs for code intelligence (go to definition, find references, etc.) | `\"./.lsp.json\"` |\n434\t| `monitors` | string\\|array | Background [Monitor](/en/tools-reference#monitor-tool) configurations that start automatically when the plugin is active. See [Monitors](#monitors) | `\"./monitors.json\"` |\n435\t| `userConfig` | object | User-configurable values prompted at enable time. See [User configuration](#user-configuration) | See below |\n436\t| `channels` | array | Channel declarations for message injection (Telegram, Slack, Discord style). See [Channels](#channels) | See below |\n437\t| `dependencies` | array | Other plugins this plugin requires, optionally with semver version constraints. See [Constrain plugin dependency versions](/en/plugin-dependencies) | `[{ \"name\": \"secrets-vault\", \"version\": \"~2.1.0\" }]` |\n438\t\n439\t### User configuration\n440\t\n441\tThe `userConfig` field declares values that Claude Code prompts the user for when the plugin is enabled. Use this instead of requiring users to hand-edit `settings.json`.\n442\t\n443\t```json theme={null}\n444\t{\n445\t \"userConfig\": {\n446\t \"api_endpoint\": {\n447\t \"type\": \"string\",\n448\t \"title\": \"API endpoint\",\n449\t \"description\": \"Your team's API endpoint\"\n450\t },\n451\t \"api_token\": {\n452\t \"type\": \"string\",\n453\t \"title\": \"API token\",\n454\t \"description\": \"API authentication token\",\n455\t \"sensitive\": true\n456\t }\n457\t }\n458\t}\n459\t```\n460\t\n461\tKeys must be valid identifiers. Each option supports these fields:\n462\t\n463\t| Field | Required | Description |\n464\t| :------------ | :------- | :--------------------------------------------------------------------------------------- |\n465\t| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |\n466\t| `title` | Yes | Label shown in the configuration dialog |\n467\t| `description` | Yes | Help text shown beneath the field |\n468\t| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |\n469\t| `required` | No | If `true`, validation fails when the field is empty |\n470\t| `default` | No | Value used when the user provides nothing |\n471\t| `multiple` | No | For `string` type, allow an array of strings |\n472\t| `min` / `max` | No | Bounds for `number` type |\n473\t\n474\tEach value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs, hook commands, and monitor commands. Non-sensitive values can also be substituted in skill and agent content. All values are exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables.\n475\t\n476\tNon-sensitive values are stored in `settings.json` under `pluginConfigs[<plugin-id>].options`. Sensitive values go to the system keychain (or `~/.claude/.credentials.json` where the keychain is unavailable). Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small.\n477\t\n478\t### Channels\n479\t\n480\tThe `channels` field lets a plugin declare one or more message channels that inject content into the conversation. Each channel binds to an MCP server that the plugin provides.\n481\t\n482\t```json theme={null}\n483\t{\n484\t \"channels\": [\n485\t {\n486\t \"server\": \"telegram\",\n487\t \"userConfig\": {\n488\t \"bot_token\": {\n489\t \"type\": \"string\",\n490\t \"title\": \"Bot token\",\n491\t \"description\": \"Telegram bot token\",\n492\t \"sensitive\": true\n493\t },\n494\t \"owner_id\": {\n495\t \"type\": \"string\",\n496\t \"title\": \"Owner ID\",\n497\t \"description\": \"Your Telegram user ID\"\n498\t }\n499\t }\n500\t }\n501\t ]\n502\t}\n503\t```\n504\t\n505\tThe `server` field is required and must match a key in the plugin's `mcpServers`. The optional per-channel `userConfig` uses the same schema as the top-level field, letting the plugin prompt for bot tokens or owner IDs when the plugin is enabled.\n506\t\n507\t### Path behavior rules\n508\t\n509\tFor `skills`, `commands`, `agents`, `outputStyles`, `themes`, and `monitors`, a custom path replaces the default. If the manifest specifies `skills`, the default `skills/` directory is not scanned; if it specifies `monitors`, the default `monitors/monitors.json` is not loaded. [Hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers) have different semantics for handling multiple sources.\n510\t\n511\t* All paths must be relative to the plugin root and start with `./`\n512\t* Components from custom paths use the same naming and namespacing rules\n513\t* Multiple paths can be specified as arrays\n514\t* To keep the default directory and add more paths for skills, commands, agents, or output styles, include the default in your array: `\"skills\": [\"./skills/\", \"./extras/\"]`\n515\t* When a skill path points to a directory that contains a `SKILL.md` directly, for example `\"skills\": [\"./\"]` pointing to the plugin root, the frontmatter `name` field in `SKILL.md` determines the skill's invocation name. This gives a stable name regardless of the install directory. If `name` is not set in the frontmatter, the directory basename is used as a fallback.\n516\t\n517\t**Path examples**:\n518\t\n519\t```json theme={null}\n520\t{\n521\t \"commands\": [\n522\t \"./specialized/deploy.md\",\n523\t \"./utilities/batch-process.md\"\n524\t ],\n525\t \"agents\": [\n526\t \"./custom-agents/reviewer.md\",\n527\t \"./custom-agents/tester.md\"\n528\t ]\n529\t}\n530\t```\n531\t\n532\t### Environment variables\n533\t\n534\tClaude Code provides two variables for referencing plugin paths. Both are substituted inline anywhere they appear in skill content, agent content, hook commands, monitor commands, and MCP or LSP server configs. Both are also exported as environment variables to hook processes and MCP or LSP server subprocesses.\n535\t\n536\t**`${CLAUDE_PLUGIN_ROOT}`**: the absolute path to your plugin's installation directory. Use this to reference scripts, binaries, and config files bundled with the plugin. This path changes when the plugin updates, so files you write here do not survive an update.\n537\t\n538\t**`${CLAUDE_PLUGIN_DATA}`**: a persistent directory for plugin state that survives updates. Use this for installed dependencies such as `node_modules` or Python virtual environments, generated code, caches, and any other files that should persist across plugin versions. The directory is created automatically the first time this variable is referenced.\n539\t\n540\t```json theme={null}\n541\t{\n542\t \"hooks\": {\n543\t \"PostToolUse\": [\n544\t {\n545\t \"hooks\": [\n546\t {\n547\t \"type\": \"command\",\n548\t \"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/process.sh\"\n549\t }\n550\t ]\n551\t }\n552\t ]\n553\t }\n554\t}\n555\t```\n556\t\n557\t#### Persistent data directory\n558\t\n559\tThe `${CLAUDE_PLUGIN_DATA}` directory resolves to `~/.claude/plugins/data/{id}/`, where `{id}` is the plugin identifier with characters outside `a-z`, `A-Z`, `0-9`, `_`, and `-` replaced by `-`. For a plugin installed as `formatter@my-marketplace`, the directory is `~/.claude/plugins/data/formatter-my-marketplace/`.\n560\t\n561\tA common use is installing language dependencies once and reusing them across sessions and plugin updates. Because the data directory outlives any single plugin version, a check for directory existence alone cannot detect when an update changes the plugin's dependency manifest. The recommended pattern compares the bundled manifest against a copy in the data directory and reinstalls when they differ.\n562\t\n563\tThis `SessionStart` hook installs `node_modules` on the first run and again whenever a plugin update includes a changed `package.json`:\n564\t\n565\t```json theme={null}\n566\t{\n567\t \"hooks\": {\n568\t \"SessionStart\": [\n569\t {\n570\t \"hooks\": [\n571\t {\n572\t \"type\": \"command\",\n573\t \"command\": \"diff -q \\\"${CLAUDE_PLUGIN_ROOT}/package.json\\\" \\\"${CLAUDE_PLUGIN_DATA}/package.json\\\" >/dev/null 2>&1 || (cd \\\"${CLAUDE_PLUGIN_DATA}\\\" && cp \\\"${CLAUDE_PLUGIN_ROOT}/package.json\\\" . && npm install) || rm -f \\\"${CLAUDE_PLUGIN_DATA}/package.json\\\"\"\n574\t }\n575\t ]\n576\t }\n577\t ]\n578\t }\n579\t}\n580\t```\n581\t\n582\tThe `diff` exits nonzero when the stored copy is missing or differs from the bundled one, covering both first run and dependency-changing updates. If `npm install` fails, the trailing `rm` removes the copied manifest so the next session retries.\n583\t\n584\tScripts bundled in `${CLAUDE_PLUGIN_ROOT}` can then run against the persisted `node_modules`:\n585\t\n586\t```json theme={null}\n587\t{\n588\t \"mcpServers\": {\n589\t \"routines\": {\n590\t \"command\": \"node\",\n591\t \"args\": [\"${CLAUDE_PLUGIN_ROOT}/server.js\"],\n592\t \"env\": {\n593\t \"NODE_PATH\": \"${CLAUDE_PLUGIN_DATA}/node_modules\"\n594\t }\n595\t }\n596\t }\n597\t}\n598\t```\n599\t\n600\tThe data directory is deleted automatically when you uninstall the plugin from the last scope where it is installed. The `/plugin` interface shows the directory size and prompts before deleting. The CLI deletes by default; pass [`--keep-data`](#plugin-uninstall) to preserve it.\n601\t\n602\t***\n603\t\n604\t## Plugin caching and file resolution\n605\t\n606\tPlugins are specified in one of two ways:\n607\t\n608\t* Through `claude --plugin-dir`, for the duration of a session.\n609\t* Through a marketplace, installed for future sessions.\n610\t\n611\tFor security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.\n612\t\n613\tEach installed version is a separate directory in the cache. When you update or uninstall a plugin, the previous version directory is marked as orphaned and removed automatically 7 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors.\n614\t\n615\tClaude's Glob and Grep tools skip orphaned version directories during searches, so file results don't include outdated plugin code.\n616\t\n617\t### Path traversal limitations\n618\t\n619\tInstalled plugins cannot reference files outside their directory. Paths that traverse outside the plugin root (such as `../shared-utils`) will not work after installation because those external files are not copied to the cache.\n620\t\n621\t### Working with external dependencies\n622\t\n623\tIf your plugin needs to access files outside its directory, you can create symbolic links to external files within your plugin directory. Symlinks are preserved in the cache rather than dereferenced, and they resolve to their target at runtime. The following command creates a link from inside your plugin directory to a shared utilities location:\n624\t\n625\t```bash theme={null}\n626\tln -s /path/to/shared-utils ./shared-utils\n627\t```\n628\t\n629\tThis provides flexibility while maintaining the security benefits of the caching system.\n630\t\n631\t***\n632\t\n633\t## Plugin directory structure\n634\t\n635\t### Standard plugin layout\n636\t\n637\tA complete plugin follows this structure:\n638\t\n639\t```text theme={null}\n640\tenterprise-plugin/\n641\t├── .claude-plugin/ # Metadata directory (optional)\n642\t│ └── plugin.json # plugin manifest\n643\t├── skills/ # Skills\n644\t│ ├── code-reviewer/\n645\t│ │ └── SKILL.md\n646\t│ └── pdf-processor/\n647\t│ ├── SKILL.md\n648\t│ └── scripts/\n649\t├── commands/ # Skills as flat .md files\n650\t│ ├── status.md\n651\t│ └── logs.md\n652\t├── agents/ # Subagent definitions\n653\t│ ├── security-reviewer.md\n654\t│ ├── performance-tester.md\n655\t│ └── compliance-checker.md\n656\t├── output-styles/ # Output style definitions\n657\t│ └── terse.md\n658\t├── themes/ # Color theme definitions\n659\t│ └── dracula.json\n660\t├── monitors/ # Background monitor configurations\n661\t│ └── monitors.json\n662\t├── hooks/ # Hook configurations\n663\t│ ├── hooks.json # Main hook config\n664\t│ └── security-hooks.json # Additional hooks\n665\t├── bin/ # Plugin executables added to PATH\n666\t│ └── my-tool # Invokable as bare command in Bash tool\n667\t├── settings.json # Default settings for the plugin\n668\t├── .mcp.json # MCP server definitions\n669\t├── .lsp.json # LSP server configurations\n670\t├── scripts/ # Hook and utility scripts\n671\t│ ├── security-scan.sh\n672\t│ ├── format-code.py\n673\t│ └── deploy.js\n674\t├── LICENSE # License file\n675\t└── CHANGELOG.md # Version history\n676\t```\n677\t\n678\t<Warning>\n679\t The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.\n680\t</Warning>\n681\t\n682\t### File locations reference\n683\t\n684\t| Component | Default Location | Purpose |\n685\t| :---------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n686\t| **Manifest** | `.claude-plugin/plugin.json` | Plugin metadata and configuration (optional) |\n687\t| **Skills** | `skills/` | Skills with `<name>/SKILL.md` structure |\n688\t| **Commands** | `commands/` | Skills as flat Markdown files. Use `skills/` for new plugins |\n689\t| **Agents** | `agents/` | Subagent Markdown files |\n690\t| **Output styles** | `output-styles/` | Output style definitions |\n691\t| **Themes** | `themes/` | Color theme definitions |\n692\t| **Hooks** | `hooks/hooks.json` | Hook configuration |\n693\t| **MCP servers** | `.mcp.json` | MCP server definitions |\n694\t| **LSP servers** | `.lsp.json` | Language server configurations |\n695\t| **Monitors** | `monitors/monitors.json` | Background monitor configurations |\n696\t| **Executables** | `bin/` | Executables added to the Bash tool's `PATH`. Files here are invokable as bare commands in any Bash tool call while the plugin is enabled |\n697\t| **Settings** | `settings.json` | Default configuration applied when the plugin is enabled. Only the [`agent`](/en/sub-agents) and [`subagentStatusLine`](/en/statusline#subagent-status-lines) keys are currently supported |\n698\t\n699\t***\n700\t\n701\t## CLI commands reference\n702\t\n703\tClaude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation.\n704\t\n705\t### plugin install\n706\t\n707\tInstall a plugin from available marketplaces.\n708\t\n709\t```bash theme={null}\n710\tclaude plugin install <plugin> [options]\n711\t```\n712\t\n713\t**Arguments:**\n714\t\n715\t* `<plugin>`: Plugin name or `plugin-name@marketplace-name` for a specific marketplace\n716\t\n717\t**Options:**\n718\t\n719\t| Option | Description | Default |\n720\t| :-------------------- | :------------------------------------------------ | :------ |\n721\t| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local` | `user` |\n722\t| `-h, --help` | Display help for command | |\n723\t\n724\tScope determines which settings file the installed plugin is added to. For example, `--scope project` writes to `enabledPlugins` in .claude/settings.json, making the plugin available to everyone who clones the project repository.\n725\t\n726\t**Examples:**\n727\t\n728\t```bash theme={null}\n729\t# Install to user scope (default)\n730\tclaude plugin install formatter@my-marketplace\n731\t\n732\t# Install to project scope (shared with team)\n733\tclaude plugin install formatter@my-marketplace --scope project\n734\t\n735\t# Install to local scope (gitignored)\n736\tclaude plugin install formatter@my-marketplace --scope local\n737\t```\n738\t\n739\t### plugin uninstall\n740\t\n741\tRemove an installed plugin.\n742\t\n743\t```bash theme={null}\n744\tclaude plugin uninstall <plugin> [options]\n745\t```\n746\t\n747\t**Arguments:**\n748\t\n749\t* `<plugin>`: Plugin name or `plugin-name@marketplace-name`\n750\t\n751\t**Options:**\n752\t\n753\t| Option | Description | Default |\n754\t| :-------------------- | :------------------------------------------------------------------------------------------------------- | :------ |\n755\t| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |\n756\t| `--keep-data` | Preserve the plugin's [persistent data directory](#persistent-data-directory) | |\n757\t| `--prune` | Also remove auto-installed dependencies that no other plugin requires. See [plugin prune](#plugin-prune) | |\n758\t| `-y, --yes` | Skip the `--prune` confirmation prompt. Required when stdin is not a TTY | |\n759\t| `-h, --help` | Display help for command | |\n760\t\n761\t**Aliases:** `remove`, `rm`\n762\t\n763\tBy default, uninstalling from the last remaining scope also deletes the plugin's `${CLAUDE_PLUGIN_DATA}` directory. Use `--keep-data` to preserve it, for example when reinstalling after testing a new version.\n764\t\n765\t### plugin prune\n766\t\n767\tRemove auto-installed plugin dependencies that are no longer required by any installed plugin. Dependencies that Claude Code pulled in to satisfy another plugin's [`dependencies`](/en/plugin-dependencies) field are removed; plugins you installed directly are never touched.\n768\t\n769\t```bash theme={null}\n770\tclaude plugin prune [options]\n771\t```\n772\t\n773\t**Options:**\n774\t\n775\t| Option | Description | Default |\n776\t| :-------------------- | :------------------------------------------------------------- | :------ |\n777\t| `-s, --scope <scope>` | Prune at scope: `user`, `project`, or `local` | `user` |\n778\t| `--dry-run` | List what would be removed without removing anything | |\n779\t| `-y, --yes` | Skip the confirmation prompt. Required when stdin is not a TTY | |\n780\t| `-h, --help` | Display help for command | |\n781\t\n782\t**Aliases:** `autoremove`\n783\t\n784\tThe command lists orphaned dependencies and asks for confirmation before removing them. To remove a plugin and clean up its dependencies in one step, run `claude plugin uninstall <plugin> --prune`.\n785\t\n786\t<Note>\n787\t `claude plugin prune` requires Claude Code v2.1.121 or later.\n788\t</Note>\n789\t\n790\t### plugin enable\n791\t\n792\tEnable a disabled plugin.\n793\t\n794\t```bash theme={null}\n795\tclaude plugin enable <plugin> [options]\n796\t```\n797\t\n798\t**Arguments:**\n799\t\n800\t* `<plugin>`: Plugin name or `plugin-name@marketplace-name`\n801\t\n802\t**Options:**\n803\t\n804\t| Option | Description | Default |\n805\t| :-------------------- | :--------------------------------------------- | :------ |\n806\t| `-s, --scope <scope>` | Scope to enable: `user`, `project`, or `local` | `user` |\n807\t| `-h, --help` | Display help for command | |\n808\t\n809\t### plugin disable\n810\t\n811\tDisable a plugin without uninstalling it.\n812\t\n813\t```bash theme={null}\n814\tclaude plugin disable <plugin> [options]\n815\t```\n816\t\n817\t**Arguments:**\n818\t\n819\t* `<plugin>`: Plugin name or `plugin-name@marketplace-name`\n820\t\n821\t**Options:**\n822\t\n823\t| Option | Description | Default |\n824\t| :-------------------- | :---------------------------------------------- | :------ |\n825\t| `-s, --scope <scope>` | Scope to disable: `user`, `project`, or `local` | `user` |\n826\t| `-h, --help` | Display help for command | |\n827\t\n828\t### plugin update\n829\t\n830\tUpdate a plugin to the latest version.\n831\t\n832\t```bash theme={null}\n833\tclaude plugin update <plugin> [options]\n834\t```\n835\t\n836\t**Arguments:**\n837\t\n838\t* `<plugin>`: Plugin name or `plugin-name@marketplace-name`\n839\t\n840\t**Options:**\n841\t\n842\t| Option | Description | Default |\n843\t| :-------------------- | :-------------------------------------------------------- | :------ |\n844\t| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed` | `user` |\n845\t| `-h, --help` | Display help for command | |\n846\t\n847\t***\n848\t\n849\t### plugin list\n850\t\n851\tList installed plugins with their version, source marketplace, and enable status.\n852\t\n853\t```bash theme={null}\n854\tclaude plugin list [options]\n855\t```\n856\t\n857\t**Options:**\n858\t\n859\t| Option | Description | Default |\n860\t| :------------ | :------------------------------------------------------------- | :------ |\n861\t| `--json` | Output as JSON | |\n862\t| `--available` | Include available plugins from marketplaces. Requires `--json` | |\n863\t| `-h, --help` | Display help for command | |\n864\t\n865\t### plugin tag\n866\t\n867\tCreate a release git tag for the plugin in the current directory. Run from inside the plugin's folder. See [Tag plugin releases](/en/plugin-dependencies#tag-plugin-releases-for-version-resolution).\n868\t\n869\t```bash theme={null}\n870\tclaude plugin tag [options]\n871\t```\n872\t\n873\t**Options:**\n874\t\n875\t| Option | Description | Default |\n876\t| :------------ | :------------------------------------------------------------------------- | :------ |\n877\t| `--push` | Push the tag to the remote after creating it | |\n878\t| `--dry-run` | Print what would be tagged without creating the tag | |\n879\t| `-f, --force` | Create the tag even if the working tree is dirty or the tag already exists | |\n880\t| `-h, --help` | Display help for command | |\n881\t\n882\t***\n883\t\n884\t## Debugging and development tools\n885\t\n886\t### Debugging commands\n887\t\n888\tUse `claude --debug` to see plugin loading details:\n889\t\n890\tThis shows:\n891\t\n892\t* Which plugins are being loaded\n893\t* Any errors in plugin manifests\n894\t* Skill, agent, and hook registration\n895\t* MCP server initialization\n896\t\n897\t### Common issues\n898\t\n899\t| Issue | Cause | Solution |\n900\t| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n901\t| Plugin not loading | Invalid `plugin.json` | Run `claude plugin validate` or `/plugin validate` to check `plugin.json`, skill/agent/command frontmatter, and `hooks/hooks.json` for syntax and schema errors |\n902\t| Skills not appearing | Wrong directory structure | Ensure `skills/` or `commands/` is at the plugin root, not inside `.claude-plugin/` |\n903\t| Hooks not firing | Script not executable | Run `chmod +x script.sh` |\n904\t| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |\n905\t| Path errors | Absolute paths used | All paths must be relative and start with `./` |\n906\t| LSP `Executable not found in $PATH` | Language server not installed | Install the binary (e.g., `npm install -g typescript-language-server typescript`) |\n907\t\n908\t### Example error messages\n909\t\n910\t**Manifest validation errors**:\n911\t\n912\t* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings\n913\t* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`: a required field is missing\n914\t* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error\n915\t\n916\t**Plugin loading errors**:\n917\t\n918\t* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: command path exists but contains no valid command files\n919\t* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: the `source` path in marketplace.json points to a non-existent directory\n920\t* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: remove duplicate component definitions or remove `strict: false` in marketplace entry\n921\t\n922\t### Hook troubleshooting\n923\t\n924\t**Hook script not executing**:\n925\t\n926\t1. Check the script is executable: `chmod +x ./scripts/your-script.sh`\n927\t2. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash`\n928\t3. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `\"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh\"`\n929\t4. Test the script manually: `./scripts/your-script.sh`\n930\t\n931\t**Hook not triggering on expected events**:\n932\t\n933\t1. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`\n934\t2. Check the matcher pattern matches your tools: `\"matcher\": \"Write|Edit\"` for file operations\n935\t3. Confirm the hook type is valid: `command`, `http`, `mcp_tool`, `prompt`, or `agent`\n936\t\n937\t### MCP server troubleshooting\n938\t\n939\t**Server not starting**:\n940\t\n941\t1. Check the command exists and is executable\n942\t2. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable\n943\t3. Check the MCP server logs: `claude --debug` shows initialization errors\n944\t4. Test the server manually outside of Claude Code\n945\t\n946\t**Server tools not appearing**:\n947\t\n948\t1. Ensure the server is properly configured in `.mcp.json` or `plugin.json`\n949\t2. Verify the server implements the MCP protocol correctly\n950\t3. Check for connection timeouts in debug output\n951\t\n952\t### Directory structure mistakes\n953\t\n954\t**Symptoms**: Plugin loads but components (skills, agents, hooks) are missing.\n955\t\n956\t**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.\n957\t\n958\t```text theme={null}\n959\tmy-plugin/\n960\t├── .claude-plugin/\n961\t│ └── plugin.json ← Only manifest here\n962\t├── commands/ ← At root level\n963\t├── agents/ ← At root level\n964\t└── hooks/ ← At root level\n965\t```\n966\t\n967\tIf your components are inside `.claude-plugin/`, move them to the plugin root.\n968\t\n969\t**Debug checklist**:\n970\t\n971\t1. Run `claude --debug` and look for \"loading plugin\" messages\n972\t2. Check that each component directory is listed in the debug output\n973\t3. Verify file permissions allow reading the plugin files\n974\t\n975\t***\n976\t\n977\t## Distribution and versioning reference\n978\t\n979\t### Version management\n980\t\n981\tClaude Code uses the plugin's version as the cache key that determines whether an update is available. When you run `/plugin update` or auto-update fires, Claude Code computes the current version and skips the update if it matches what's already installed.\n982\t\n983\tThe version is resolved from the first of these that is set:\n984\t\n985\t1. The `version` field in the plugin's `plugin.json`\n986\t2. The `version` field in the plugin's marketplace entry in `marketplace.json`\n987\t3. The git commit SHA of the plugin's source, for `github`, `url`, `git-subdir`, and relative-path sources in a git-hosted marketplace\n988\t4. `unknown`, for `npm` sources or local directories not inside a git repository\n989\t\n990\tThis gives you two ways to version a plugin:\n991\t\n992\t| Approach | How | Update behavior | Best for |\n993\t| :--------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |\n994\t| **Explicit version** | Set `\"version\": \"2.1.0\"` in `plugin.json` | Users get updates only when you bump this field. Pushing new commits without bumping it has no effect, and `/plugin update` reports \"already at the latest version\". | Published plugins with stable release cycles |\n995\t| **Commit-SHA version** | Omit `version` from both `plugin.json` and the marketplace entry | Users get updates on every new commit to the plugin's git source | Internal or team plugins under active development |\n996\t\n997\t<Warning>\n998\t If you set `version` in `plugin.json`, you must bump it every time you want users to receive changes. Pushing new commits alone is not enough, because Claude Code sees the same version string and keeps the cached copy. If you're iterating quickly, leave `version` unset so the git commit SHA is used instead.\n999\t</Warning>\n1000\t\n1001\tIf you use explicit versions, follow [semantic versioning](https://semver.org) (`MAJOR.MINOR.PATCH`): bump MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes. Document changes in a `CHANGELOG.md`.\n1002\t\n1003\t***\n1004\t\n1005\t## See also\n1006\t\n1007\t* [Plugins](/en/plugins) - Tutorials and practical usage\n1008\t* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces\n1009\t* [Skills](/en/skills) - Skill development details\n1010\t* [Subagents](/en/sub-agents) - Agent configuration and capabilities\n1011\t* [Hooks](/en/hooks) - Event handling and automation\n1012\t* [MCP](/en/mcp) - External tool integration\n1013\t* [Settings](/en/settings) - Configuration options for plugins\n1014\t"}]},"uuid":"075b7082-eb81-46d3-baa3-5b018c1fe47f","timestamp":"2026-05-04T17:52:15.345Z","sourceToolAssistantUUID":"45060797-8678-4d6a-8c8c-711cd1a8629c","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"075b7082-eb81-46d3-baa3-5b018c1fe47f","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_013Jifs4rrFvmDAqyhZNrTKj","type":"message","role":"assistant","content":[{"type":"text","text":"Perfect. I found the theme documentation. Let me fetch the terminal config page to check for any additional color control mechanisms."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":15627,"cache_read_input_tokens":14671,"cache_creation":{"ephemeral_5m_input_tokens":15627,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011CahxKDeb8vmZEmbHBvBaA","attributionAgent":"claude-code-guide","type":"assistant","uuid":"5dd16c28-3b78-4f22-891d-8a70a4fd7553","timestamp":"2026-05-04T17:52:16.766Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"5dd16c28-3b78-4f22-891d-8a70a4fd7553","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_013Jifs4rrFvmDAqyhZNrTKj","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01QZTtxYo1J7eLuUUeLJ4QxC","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/terminal-config.md","prompt":"color theme ANSI terminal appearance"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":15627,"cache_read_input_tokens":14671,"output_tokens":117,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":15627},"inference_geo":"","iterations":[{"input_tokens":2,"output_tokens":117,"cache_read_input_tokens":14671,"cache_creation_input_tokens":15627,"cache_creation":{"ephemeral_5m_input_tokens":15627,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011CahxKDeb8vmZEmbHBvBaA","attributionAgent":"claude-code-guide","type":"assistant","uuid":"1ef43179-2fba-46bd-92a2-cabb9a1d5bf2","timestamp":"2026-05-04T17:52:17.432Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"1ef43179-2fba-46bd-92a2-cabb9a1d5bf2","isSidechain":true,"promptId":"909f6261-516f-42bf-b495-c5399e06bb47","agentId":"a6e013aa57a31cae7","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01QZTtxYo1J7eLuUUeLJ4QxC","type":"tool_result","content":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Configure your terminal for Claude Code\n\n> Fix Shift+Enter for newlines, get a terminal bell when Claude finishes, configure tmux, match the color theme, and enable Vim mode in the Claude Code CLI.\n\nClaude Code works in any terminal without configuration. This page is for when something specific is not behaving the way you expect. Find your symptom below. If everything already feels right, you do not need this page.\n\n* [Shift+Enter submits instead of inserting a newline](#enter-multiline-prompts)\n* [Option-key shortcuts do nothing on macOS](#enable-option-key-shortcuts-on-macos)\n* [No sound or alert when Claude finishes](#get-a-terminal-bell-or-notification)\n* [You run Claude Code inside tmux](#configure-tmux)\n* [Display flickers or scrollback jumps](#switch-to-fullscreen-rendering)\n* [You want Vim keys in the prompt](#edit-prompts-with-vim-keybindings)\n\nThis page is about getting your terminal to send the right signals to Claude Code. To change which keys Claude Code itself responds to, see [keybindings](/en/keybindings) instead.\n\n## Enter multiline prompts\n\nPressing Enter submits your message. To add a line break without submitting, press Ctrl+J, or type `\\` and then press Enter. Both work in every terminal with no setup.\n\nIn most terminals you can also press Shift+Enter, but support varies by terminal emulator:\n\n| Terminal | Shift+Enter for newline |\n| :---------------------------------------------------------------------------------- | :------------------------------------------ |\n| Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal | Works without setup |\n| VS Code, Cursor, Windsurf, Alacritty, Zed | Run `/terminal-setup` once |\n| Windows Terminal, gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio | Not available; use Ctrl+J or `\\` then Enter |\n\nFor VS Code, Cursor, Windsurf, Alacritty, and Zed, `/terminal-setup` writes Shift+Enter and other keybindings into the terminal's configuration file. In VS Code, Cursor, and Windsurf it also sets `terminal.integrated.mouseWheelScrollSensitivity` in the editor settings for smoother scrolling in [fullscreen mode](/en/fullscreen). Existing bindings and settings are left in place; if you see a message such as `VSCode terminal Shift+Enter key binding already configured`, no change was made. Run `/terminal-setup` directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's configuration.\n\nIf you are running inside tmux, Shift+Enter also requires the [tmux configuration below](#configure-tmux) even when the outer terminal supports it.\n\nTo bind newline to a different key, or to swap behavior so Enter inserts a newline and Shift+Enter submits, map the `chat:newline` and `chat:submit` actions in your [keybindings file](/en/keybindings).\n\n## Enable Option key shortcuts on macOS\n\nSome Claude Code shortcuts use the Option key, such as Option+Enter for a newline or Option+P to switch models. On macOS, most terminals do not send Option as a modifier by default, so these shortcuts do nothing until you enable it. The terminal setting for this is usually labeled \"Use Option as Meta Key\"; Meta is the historical Unix name for the key now labeled Option or Alt.\n\n<Tabs>\n <Tab title=\"Apple Terminal\">\n Open Settings → Profiles → Keyboard and check \"Use Option as Meta Key\".\n\n If you accepted Claude Code's first-run prompt that offered \"Option+Enter for newlines and visual bell\", this is already done. That prompt runs `/terminal-setup` for you, which enables Option as Meta and switches the audio bell to a visual screen flash in your Apple Terminal profile.\n </Tab>\n\n <Tab title=\"iTerm2\">\n Open Settings → Profiles → Keys → General and set Left Option key and Right Option key to \"Esc+\".\n\n Running `/terminal-setup` in iTerm2 enables \"Applications in terminal may access clipboard\" under Settings → General → Selection so the `/copy` command can write to your system clipboard. The command detects iTerm2 even when run from inside tmux. Restart iTerm2 for the change to take effect.\n </Tab>\n\n <Tab title=\"VS Code\">\n Add `\"terminal.integrated.macOptionIsMeta\": true` to your VS Code settings.\n </Tab>\n</Tabs>\n\nFor Ghostty, Kitty, and other terminals, look for an Option-as-Alt or Option-as-Meta setting in the terminal's configuration file.\n\n## Get a terminal bell or notification\n\nWhen Claude finishes a task or pauses for a permission prompt, it fires a notification event. Surfacing this as a terminal bell or desktop notification lets you switch to other work while a long task runs.\n\nBy default Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In other terminals, set [`preferredNotifChannel`](/en/settings#available-settings) to `\"terminal_bell\"` to ring the terminal bell instead, or configure a [Notification hook](#play-a-sound-with-a-notification-hook) for a custom sound or command.\n\nThe desktop notification reaches your local machine over SSH, so a remote session can still alert you. Ghostty and Kitty forward it to your OS notification center without further setup. iTerm2 requires you to enable forwarding:\n\n<Steps>\n <Step title=\"Open iTerm2 notification settings\">\n Go to Settings → Profiles → Terminal.\n </Step>\n\n <Step title=\"Enable alerts\">\n Check \"Notification Center Alerts\", then click \"Filter Alerts\" and enable \"Send escape sequence-generated alerts\".\n </Step>\n</Steps>\n\nIf notifications still do not appear, confirm that your terminal application has notification permission in your OS settings, and if you are running inside tmux, [enable passthrough](#configure-tmux).\n\n### Play a sound with a Notification hook\n\nIn any terminal you can configure a [Notification hook](/en/hooks-guide#get-notified-when-claude-needs-input) to play a sound or run a custom command when Claude needs your attention. Hooks run alongside the built-in notification rather than replacing it, so terminals that do not receive a desktop notification, such as Warp or the VS Code integrated terminal, can use a hook or set `preferredNotifChannel` to `\"terminal_bell\"` instead.\n\nThe example below plays a system sound on macOS. The linked guide has desktop notification commands for macOS, Linux, and Windows.\n\n```json ~/.claude/settings.json theme={null}\n{\n \"hooks\": {\n \"Notification\": [\n {\n \"hooks\": [{ \"type\": \"command\", \"command\": \"afplay /System/Library/Sounds/Glass.aiff\" }]\n }\n ]\n }\n}\n```\n\n## Configure tmux\n\nWhen Claude Code runs inside tmux, two things break by default: Shift+Enter submits instead of inserting a newline, and desktop notifications and the [progress bar](/en/settings#available-settings) never reach the outer terminal. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:\n\n```bash ~/.tmux.conf theme={null}\nset -g allow-passthrough on\nset -s extended-keys on\nset -as terminal-features 'xterm*:extkeys'\n```\n\nThe `allow-passthrough` line lets notifications and progress updates reach iTerm2, Ghostty, or Kitty instead of being swallowed by tmux. The `extended-keys` lines let tmux distinguish Shift+Enter from plain Enter so the newline shortcut works.\n\n## Match the color theme\n\nUse the `/theme` command, or the theme picker in `/config`, to choose a Claude Code theme that matches your terminal. Selecting the auto option detects your terminal's light or dark background, so the theme follows OS appearance changes whenever your terminal does. Claude Code does not control the terminal's own color scheme, which is set by the terminal application.\n\nTo customize what appears at the bottom of the interface, configure a [custom status line](/en/statusline) that shows the current model, working directory, git branch, or other context.\n\n### Create a custom theme\n\n<Note>\n Custom themes require Claude Code v2.1.118 or later.\n</Note>\n\nIn addition to the built-in presets, `/theme` lists any custom themes you have defined and any themes contributed by installed [plugins](/en/plugins-reference#themes). Select **New custom theme…** at the end of the list to create one interactively: you name the theme, then pick individual color tokens to override. Press `Ctrl+E` while a custom theme is highlighted to edit it.\n\nEach custom theme is a JSON file in `~/.claude/themes/`. The filename without the `.json` extension is the theme's slug, and selecting the theme stores `custom:<slug>` as your theme preference. The file has three optional fields:\n\n| Field | Type | Description |\n| :---------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | string | Display label shown in `/theme`. Defaults to the filename slug |\n| `base` | string | Built-in preset the theme starts from: `dark`, `light`, `dark-daltonized`, `light-daltonized`, `dark-ansi`, or `light-ansi`. Defaults to `dark` |\n| `overrides` | object | Map of color token names to color values. Tokens not listed here fall through to the base preset |\n\nColor values accept `#rrggbb`, `#rgb`, `rgb(r,g,b)`, `ansi256(n)`, or `ansi:<name>` where `<name>` is one of the 16 standard ANSI color names such as `red` or `cyanBright`. Unknown tokens and invalid color values are ignored, so a typo cannot break rendering.\n\nThe following example defines a theme that keeps the dark preset but recolors the prompt accent, error text, and success text:\n\n```json ~/.claude/themes/dracula.json theme={null}\n{\n \"name\": \"Dracula\",\n \"base\": \"dark\",\n \"overrides\": {\n \"claude\": \"#bd93f9\",\n \"error\": \"#ff5555\",\n \"success\": \"#50fa7b\"\n }\n}\n```\n\nClaude Code watches `~/.claude/themes/` and reloads when a file changes, so edits made in your editor apply to a running session without a restart.\n\nThe reference below covers the tokens you can set in `overrides`. The interactive editor in `/theme` shows the same tokens with a live preview, plus a few single-purpose accents such as onboarding screen colors that are omitted here.\n\n<Accordion title=\"Color token reference\">\n The following example combines tokens from several of the groups below: the brand accent, the plan mode border, the diff backgrounds, and the fullscreen message background.\n\n ```json ~/.claude/themes/midnight.json theme={null}\n {\n \"name\": \"Midnight\",\n \"base\": \"dark\",\n \"overrides\": {\n \"claude\": \"#a78bfa\",\n \"planMode\": \"#38bdf8\",\n \"diffAdded\": \"#14532d\",\n \"diffRemoved\": \"#7f1d1d\",\n \"userMessageBackground\": \"#1e1b4b\"\n }\n }\n ```\n\n #### Text and accent colors\n\n Control the primary brand accent and the foreground text shades used throughout the interface.\n\n | Token | Controls |\n | :------------ | :--------------------------------------------------------------- |\n | `claude` | Primary brand accent, used for the spinner and assistant label |\n | `text` | Default foreground text |\n | `inverseText` | Text drawn on top of a colored background, such as status badges |\n | `inactive` | Secondary text such as hints, timestamps, and disabled items |\n | `subtle` | Faint borders and de-emphasized secondary text |\n | `suggestion` | Autocomplete suggestions and selection highlight in pickers |\n | `permission` | Dialog borders, including permission prompts and pickers |\n | `remember` | Memory and `CLAUDE.md` indicators |\n\n #### Status colors\n\n Signal success, failure, and warning states across messages and indicators.\n\n | Token | Controls |\n | :-------- | :--------------------------------------------------- |\n | `success` | Success messages and passing checks |\n | `error` | Error messages and failures |\n | `warning` | Warnings, caution messages, and the auto mode border |\n | `merged` | Merged pull request status |\n\n #### Input box and mode indicators\n\n Set the input box border color and the accent shown while a permission mode or indicator is active.\n\n | Token | Controls |\n | :------------- | :------------------------------------------------- |\n | `promptBorder` | Input box border in the default permission mode |\n | `planMode` | Plan mode accent and border |\n | `autoAccept` | Accept-edits mode accent and border |\n | `bashBorder` | Input box border when entering a `!` shell command |\n | `ide` | IDE connection indicator |\n | `fastMode` | Fast mode indicator |\n\n #### Diff rendering\n\n Color added and removed code in file edits and reviews.\n\n | Token | Controls |\n | :------------------ | :------------------------------------------------- |\n | `diffAdded` | Background of added lines |\n | `diffRemoved` | Background of removed lines |\n | `diffAddedDimmed` | Background of unchanged context near added lines |\n | `diffRemovedDimmed` | Background of unchanged context near removed lines |\n | `diffAddedWord` | Word-level highlight within an added line |\n | `diffRemovedWord` | Word-level highlight within a removed line |\n\n #### Fullscreen mode\n\n Apply only in [fullscreen rendering mode](/en/fullscreen), where messages have a background fill.\n\n | Token | Controls |\n | :--------------------------- | :----------------------------------------------------------------- |\n | `userMessageBackground` | Background behind your messages in the transcript |\n | `userMessageBackgroundHover` | Background behind a message while hovered or expanded |\n | `messageActionsBackground` | Background behind the selected message when the action bar is open |\n | `bashMessageBackgroundColor` | Background behind `!` shell command entries in the transcript |\n | `memoryBackgroundColor` | Background behind `#` memory entries in the transcript |\n | `selectionBg` | Background of text selected with the mouse |\n\n #### Usage meter and speaker labels\n\n Adjust the bar shown in the `/usage` view and the labels that distinguish your messages from Claude's.\n\n | Token | Controls |\n | :----------------- | :------------------------------------------------ |\n | `rate_limit_fill` | Filled portion of the usage meter |\n | `rate_limit_empty` | Unfilled portion of the usage meter |\n | `briefLabelYou` | Color of the `You` label on your messages |\n | `briefLabelClaude` | Color of the `Claude` label on assistant messages |\n\n #### Shimmer variants and subagent colors\n\n Several tokens have a paired shimmer variant that supplies the lighter color used in the spinner's animated gradient. Override the shimmer alongside its base token if the animation looks mismatched.\n\n * `claude` and `claudeShimmer`\n * `warning` and `warningShimmer`\n * `permission` and `permissionShimmer`\n * `promptBorder` and `promptBorderShimmer`\n * `inactive` and `inactiveShimmer`\n * `fastMode` and `fastModeShimmer`\n\n Each [subagent](/en/sub-agents) and parallel task is shown in one of eight named colors so you can tell them apart in the transcript. The token names follow the pattern `<color>_FOR_SUBAGENTS_ONLY`, where `<color>` is `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan`. Override these to change what each named color looks like. For example, a subagent with `color: blue` in its definition is drawn using the `blue_FOR_SUBAGENTS_ONLY` value.\n\n The [`ultrathink`](/en/model-config#use-ultrathink-for-one-off-deep-reasoning) and [`ultraplan`](/en/ultraplan) keywords in the prompt input are rendered with a seven-color rainbow gradient. The token names follow the pattern `rainbow_<color>` and `rainbow_<color>_shimmer`, where `<color>` is `red`, `orange`, `yellow`, `green`, `blue`, `indigo`, or `violet`.\n</Accordion>\n\n## Switch to fullscreen rendering\n\nIf the display flickers or the scroll position jumps while Claude is working, switch to [fullscreen rendering mode](/en/fullscreen). It draws to a separate screen the terminal reserves for full-screen apps instead of appending to your normal scrollback, which keeps memory usage flat and adds mouse support for scrolling and selection. In this mode you scroll with the mouse or PageUp inside Claude Code rather than with your terminal's native scrollback; see the [fullscreen page](/en/fullscreen#search-and-review-the-conversation) for how to search and copy.\n\nRun `/tui fullscreen` to switch in the current session with your conversation intact. To make it the default, set the `CLAUDE_CODE_NO_FLICKER` environment variable before starting Claude Code:\n\n<CodeGroup>\n ```bash Bash and Zsh theme={null}\n CLAUDE_CODE_NO_FLICKER=1 claude\n ```\n\n ```powershell PowerShell theme={null}\n $env:CLAUDE_CODE_NO_FLICKER = \"1\"; claude\n ```\n\n ```json ~/.claude/settings.json theme={null}\n {\n \"env\": {\n \"CLAUDE_CODE_NO_FLICKER\": \"1\"\n }\n }\n ```\n</CodeGroup>\n\n## Paste large content\n\nWhen you paste more than 10,000 characters into the prompt, Claude Code collapses the input to a `[Pasted text]` placeholder so the input box stays usable. The full content is still sent to Claude when you submit.\n\nThe VS Code integrated terminal can drop characters from very large pastes before they reach Claude Code, so prefer file-based workflows there. For very large inputs such as entire files or long logs, write the content to a file and ask Claude to read it instead of pasting. This keeps the conversation transcript readable and lets Claude reference the file by path in later turns.\n\n## Edit prompts with Vim keybindings\n\nClaude Code includes a Vim-style editing mode for the prompt input. Enable it through `/config` → Editor mode, or by setting [`editorMode`](/en/settings#available-settings) to `\"vim\"` in `~/.claude/settings.json`. Set Editor mode back to `normal` to turn it off.\n\nVim mode supports a subset of NORMAL- and VISUAL-mode motions and operators, such as `hjkl` navigation, `v`/`V` selection, and `d`/`c`/`y` with text objects. See the [Vim editor mode reference](/en/interactive-mode#vim-editor-mode) for the full key table. Vim motions are not remappable through the keybindings file.\n\nPressing Enter still submits your prompt in INSERT mode, unlike standard Vim. Use `o` or `O` in NORMAL mode, or Ctrl+J, to insert a newline instead.\n\n## Related resources\n\n* [Interactive mode](/en/interactive-mode): full keyboard shortcut reference and the Vim key table\n* [Keybindings](/en/keybindings): remap any Claude Code shortcut, including Enter and Shift+Enter\n* [Fullscreen rendering](/en/fullscreen): details on scrolling, search, and copy in fullscreen mode\n* [Hooks guide](/en/hooks-guide): more Notification hook examples for Linux and Windows\n* [Troubleshooting](/en/troubleshooting): fixes for issues outside terminal configuration\n"}]},"uuid":"15eff659-fcea-41ff-9e26-1f5db0f41538","timestamp":"2026-05-04T17:52:18.434Z","sourceToolAssistantUUID":"1ef43179-2fba-46bd-92a2-cabb9a1d5bf2","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
{"parentUuid":"15eff659-fcea-41ff-9e26-1f5db0f41538","isSidechain":true,"agentId":"a6e013aa57a31cae7","message":{"model":"claude-haiku-4-5-20251001","id":"msg_01XjUJN8uVzF6sRQD5JFs8uC","type":"message","role":"assistant","content":[{"type":"text","text":"Excellent. I now have all the information needed to provide a definitive answer. Let me compile the findings.\n\n## Definitive Answer: Claude Code Theme Customization (v2.1.126)\n\n**1. Built-in themes:**\nClaude Code ships with 6 preset themes accessible via `/theme`:\n- `dark` (default)\n- `light`\n- `dark-daltonized` (colorblind-friendly)\n- `light-daltonized` (colorblind-friendly)\n- `dark-ansi` (terminal-aware)\n- `light-ansi` (terminal-aware)\n\n**2. Custom themes—YES, fully supported (v2.1.118+):**\nUsers CAN create custom color themes. Implementation:\n- Create JSON files in `~/.claude/themes/`\n- Each file = one theme with `name`, `base` (preset), and `overrides` (color token map)\n- Interactive editor: select \"New custom theme…\" in `/theme` to build one step-by-step\n- Supported color formats: `#rrggbb`, `#rgb`, `rgb(r,g,b)`, `ansi256(n)`, or `ansi:<name>`\n- Live reload: changes apply immediately without restart\n- Pressable: distribute custom themes via plugins\n\n**3. Color tokens (token reference):**\n40+ tokens cover every UI element: `claude` (brand accent), `text`, `error`, `success`, `diffAdded`, `diffRemoved`, `userMessageBackground`, `promptBorder`, `planMode`, `pathBorder`, and more. Full list in the accordion at https://code.claude.com/docs/en/terminal-config.md#color-token-reference\n\n**4. Terminal interaction:**\nClaude Code uses ANSI colors that respect the terminal's configured palette. The `dark-ansi` and `light-ansi` presets map to standard 16-color ANSI names. The theme system does NOT control the terminal's own color scheme (that's the terminal app's responsibility).\n\n**5. Individual color override:**\nNot separately—users must define a theme (even a sparse one) to override specific tokens. No per-color env vars or hooks.\n\n**Bottom line:** Tell your user they can absolutely create a custom theme with their exact color palette. Point them to `~/.claude/themes/` and the schema example at https://code.claude.com/docs/en/terminal-config.md. They can use the interactive `/theme` UI or hand-edit JSON. No fabricated features needed."}],"stop_reason":"end_turn","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":5090,"cache_read_input_tokens":30298,"output_tokens":585,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":5090},"inference_geo":"","iterations":[{"input_tokens":2,"output_tokens":585,"cache_read_input_tokens":30298,"cache_creation_input_tokens":5090,"cache_creation":{"ephemeral_5m_input_tokens":5090,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011CahxKSorY6nWxPFeyEEkG","attributionAgent":"claude-code-guide","type":"assistant","uuid":"9aff175a-ed2c-4916-8baa-0390c5bcd859","timestamp":"2026-05-04T17:52:28.761Z","userType":"external","entrypoint":"cli","cwd":"/Users/steve.briggs","sessionId":"2f266a34-3639-442a-bf64-5c2a9eee6fcf","version":"2.1.126","gitBranch":"HEAD"}
Reference in a new issue View git blame Copy permalink