I need a definitive answer about Claude Code's theme customization, current as of late 2025 / early 2026 (Claude Code 2.1.126).

Specifically:

1. What are the built-in themes accessible via `/theme` or settings.json's `theme` field? List them all.

2. 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.

3. 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.

4. 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?

I'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.


I'll fetch the official Claude Code documentation to give you a definitive answer.


WebFetch

Prompt: theme customization color settings built-in themes


<persisted-output>
Output 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

Preview (first 2KB):
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude code docs map

# Claude Code Documentation Map

This is a comprehensive map of all Claude Code documentation pages with their headings, designed for easy navigation by LLMs.

> **Note:** This file is auto-generated by GitHub Actions. Do not edit manually.
> Last updated: 2026-05-04 14:18:49 UTC

## Document Structure

This map uses a hierarchical structure:

* **##** marks documentation groups (e.g., 'Getting started')
* **###** marks individual documentation pages
* **Nested bullets** show the heading structure within each page
* Each page title links to the full documentation

## Getting started

### [overview](https://code.claude.com/docs/en/overview.md)

* Get started
* What you can do
* Use Claude Code everywhere
* Next steps

### [quickstart](https://code.claude.com/docs/en/quickstart.md)

* Before you begin
* Step 1: Install Claude Code
* Step 2: Log in to your account
* Step 3: Start your first session
* Step 4: Ask your first question
* Step 5: Make your first code change
* Step 6: Use Git with Claude Code
* Step 7: Fix a bug or add a feature
* Step 8: Test out other common workflows
* Essential commands
* Pro tips for beginners
* What's next?
* Getting help

### [changelog](https://code.claude.com/docs/en/changelog.md)

* (No headings found)

## Core concepts

### [how-claude-code-works](https://code.claude.com/docs/en/how-claude-code-works.md)

* The agentic loop
  * Models
  * Tools
* What Claude can access
* Environments and interfaces
  * Execution environments
  * Interfaces
* Work with sessions
  * Work across branches
  * Resume or fork sessions
  * The context window
    * When context fills up
    * Manage context with skills and subagents
* Stay safe with checkpoints and permissions
  * Undo changes with checkpoints
  * Control what Claude can do
...
</persisted-output>


Let me fetch the settings and customization documentation.


Prompt: theme color customization built-in themes


Prompt: theme color settings customization


# Claude Code Settings Documentation

Claude Code provides comprehensive configuration options through a **scope system** that determines where settings apply and who they affect.

## Configuration Scopes

| Scope | Location | Who it affects | Shared with team? |
|-------|----------|---|---|
| **Managed** | Server/MDM/system-level | All users on machine | Yes (IT-deployed) |
| **User** | `~/.claude/` | You, all projects | No |
| **Project** | `.claude/` in repo | All collaborators | Yes (git-committed) |
| **Local** | `.claude/settings.local.json` | You, this repo only | No (gitignored) |

## Scope Precedence

When the same setting appears in multiple scopes, this hierarchy applies (highest to lowest):

1. **Managed** - cannot be overridden
2. **Command line arguments** - temporary session overrides
3. **Local** - personal project overrides
4. **Project** - team-shared settings
5. **User** - personal global settings

## Key Settings Files

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(~/.zshrc)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "model": "claude-sonnet-4-6",
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build"]
    }
  }
}
```

## Important Features

- **Array settings merge** across scopes (they concatenate, not replace)
- **Managed settings** are the highest priority and cannot be overridden
- **Automatic backups** - timestamped backups of config files (5 most recent retained)
- **Run `/status`** to verify which settings sources are active

For detailed settings reference, see the complete [available settings table](https://code.claude.com/docs/settings) in the documentation.


# Claude Code Settings Documentation

Claude Code offers comprehensive configuration through a **scope system** with four levels of settings management:

## Configuration Scopes

| Scope | Location | Who it affects | Shared? |
|-------|----------|---|---|
| **Managed** | Server/MDM/system files | All machine users | Yes (IT-deployed) |
| **User** | `~/.claude/` | You, all projects | No |
| **Project** | `.claude/` in repo | Team collaborators | Yes (git-committed) |
| **Local** | `.claude/settings.local.json` | You, this repo only | No (gitignored) |

**Precedence** (highest to lowest):
1. Managed settings (cannot be overridden)
2. Command line arguments
3. Local project settings
4. Shared project settings
5. User settings

## Settings Files

### Main Configuration (`settings.json`)

Locations:
- **User**: `~/.claude/settings.json`
- **Project**: `.claude/settings.json`
- **Local**: `.claude/settings.local.json`

**Example**:
```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(~/.zshrc)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}
```

### Managed Settings

Deployed through multiple mechanisms:
- **Server-managed**: Via Claude.ai admin console
- **macOS**: `com.anthropic.claudecode` plist or `/Library/Application Support/ClaudeCode/`
- **Windows**: `HKLM\SOFTWARE\Policies\ClaudeCode` or `C:\Program Files\ClaudeCode\`
- **Linux/WSL**: `/etc/claude-code/`

File-based managed settings support drop-in directories (`managed-settings.d/`) for modular policy fragments merged in alphabetical order.

## Key Configuration Settings

| Setting | Purpose | Example |
|---------|---------|---------|
| `permissions` | Allow/deny/ask tool usage | `{"deny": ["Read(./.env)"]}` |
| `env` | Environment variables | `{"MY_VAR": "value"}` |
| `model` | Default LLM model | `"claude-sonnet-4-6"` |
| `autoMode` | Auto-mode classifier rules | `{"soft_deny": ["$defaults"]}` |
| `sandbox` | Bash sandboxing config | `{"enabled": true}` |
| `hooks` | Lifecycle event handlers | Custom commands |
| `plugins` | Plugin marketplace config | `enabledPlugins`, `extraKnownMarketplaces` |
| `agent` | Run as named subagent | `"code-reviewer"` |

## Permission Rules

Format: `Tool` or `Tool(specifier)`

**Examples**:
```json
{
  "allow": [
    "Bash(npm run *)",
    "Read(./src/**)"
  ],
  "deny": [
    "Bash(curl *)",
    "Read(./.env)",
    "WebFetch(domain:sensitive.com)"
  ]
}
```

## Sandboxing Configuration

Enable bash command isolation:
```json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "filesystem": {
      "allowWrite": ["/tmp/build"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["sensitive.cloud.example.com"]
    }
  }
}
```

## Verify Configuration

Run `/status` in Claude Code to see:
- Active settings sources
- Origin (remote, plist, registry, file)
- Configuration errors

## Subagents and Plugins

- **Subagents**: `~/.claude/agents/` (user) or `.claude/agents/` (project)
- **Plugins**: Configured via `enabledPlugins` and `extraKnownMarketplaces`
- **MCP servers**: `~/.claude.json` (user) or `.mcp.json` (project)

For complete settings reference and advanced configurations, visit the [documentation index](https://code.claude.com/docs/llms.txt).


I notice neither result mentions theme customization. Let me search the full documentation index more directly.


Prompt: theme color customization UI appearance visual


# Theme Color Customization in Claude Code

Based on the Claude Code documentation, theme color customization is available through **custom color themes that you can build and ship in plugins**.

## Key Resources

1. **Custom Color Themes in Plugins**
   - 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"
   - Themes can be created as part of Claude Code plugins for distribution

2. **Related Documentation**
   - [Create plugins](https://code.claude.com/docs/en/plugins.md) - Create custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers
   - [Plugins reference](https://code.claude.com/docs/en/plugins-reference.md) - Complete technical reference for the plugin system, including schemas and component specifications
   - [Discover and install prebuilt plugins through marketplaces](https://code.claude.com/docs/en/discover-plugins.md) - Find and install plugins with themes from marketplaces

3. **Terminal Configuration**
   - [Configure your terminal for Claude Code](https://code.claude.com/docs/en/terminal-config.md) - Match the color theme and configure terminal appearance

4. **Status Line Customization**
   - [Customize your status line](https://code.claude.com/docs/en/statusline.md) - Configure a custom status bar for visual customization

## Implementation

To 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.


Good lead. Let me get the plugin reference documentation to understand the actual schema.


Prompt: color theme schema UI elements colors


<persisted-output>
Output 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

Preview (first 2KB):
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins reference

> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.

<Tip>
  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).
</Tip>

This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.

A **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.

## Plugin components reference

### Skills

Plugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke.

**Location**: `skills/` or `commands/` directory in plugin root

**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files

**Skill structure**:

```text theme={null}
skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md
```

**Integration behavior**:

* Skills and commands are automatically discovered when the plugin is installed
* Claude can invoke them automatically based on task context
* Skills can include supporting files alongside SKILL.md

For complete details, see [Skills](/en/skills).

### Agents

Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.

**Location**: `agents/` directory in plugin root

**File format**: Markdown files describing agent capabilities

**Agent structure**:

```markdown theme={null}
---
name: agent-name
...
</persisted-output>


Let me search more specifically for the theme component schema in the plugins reference.


1	> ## Documentation Index
2	> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3	> Use this file to discover all available pages before exploring further.
4
5	# Plugins reference
6
7	> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.
8
9	<Tip>
10	  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).
11	</Tip>
12
13	This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.
14
15	A **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.
16
17	## Plugin components reference
18
19	### Skills
20
21	Plugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke.
22
23	**Location**: `skills/` or `commands/` directory in plugin root
24
25	**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files
26
27	**Skill structure**:
28
29	```text theme={null}
30	skills/
31	├── pdf-processor/
32	│   ├── SKILL.md
33	│   ├── reference.md (optional)
34	│   └── scripts/ (optional)
35	└── code-reviewer/
36	    └── SKILL.md
37	```
38
39	**Integration behavior**:
40
41	* Skills and commands are automatically discovered when the plugin is installed
42	* Claude can invoke them automatically based on task context
43	* Skills can include supporting files alongside SKILL.md
44
45	For complete details, see [Skills](/en/skills).
46
47	### Agents
48
49	Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.
50
51	**Location**: `agents/` directory in plugin root
52
53	**File format**: Markdown files describing agent capabilities
54
55	**Agent structure**:
56
57	```markdown theme={null}
58	---
59	name: agent-name
60	description: What this agent specializes in and when Claude should invoke it
61	model: sonnet
62	effort: medium
63	maxTurns: 20
64	disallowedTools: Write, Edit
65	---
66
67	Detailed system prompt for the agent describing its role, expertise, and behavior.
68	```
69
70	Plugin 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.
71
72	**Integration points**:
73
74	* Agents appear in the `/agents` interface
75	* Claude can invoke agents automatically based on task context
76	* Agents can be invoked manually by users
77	* Plugin agents work alongside built-in Claude agents
78
79	For complete details, see [Subagents](/en/sub-agents).
80
81	### Hooks
82
83	Plugins can provide event handlers that respond to Claude Code events automatically.
84
85	**Location**: `hooks/hooks.json` in plugin root, or inline in plugin.json
86
87	**Format**: JSON configuration with event matchers and actions
88
89	**Hook configuration**:
90
91	```json theme={null}
92	{
93	  "hooks": {
94	    "PostToolUse": [
95	      {
96	        "matcher": "Write|Edit",
97	        "hooks": [
98	          {
99	            "type": "command",
100	            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
101	          }
102	        ]
103	      }
104	    ]
105	  }
106	}
107	```
108
109	Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):
110
111	| Event                 | When it fires                                                                                |
112	| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
113	| `SessionStart`        | When a session begins or resumes                                                                                |
114	| `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             |
115	| `UserPromptSubmit`    | When you submit a prompt, before Claude processes it                                                                                |
116	| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion                                                     |
117	| `PreToolUse`          | Before a tool call executes. Can block it                                                                                |
118	| `PermissionRequest`   | When a permission dialog appears                                                                                |
119	| `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                     |
120	| `PostToolUse`         | After a tool call succeeds                                                                                |
121	| `PostToolUseFailure`  | After a tool call fails                                                                                |
122	| `PostToolBatch`       | After a full batch of parallel tool calls resolves, before the next model call                                                                         |
123	| `Notification`        | When Claude Code sends a notification                                                                                |
124	| `SubagentStart`       | When a subagent is spawned                                                                                |
125	| `SubagentStop`        | When a subagent finishes                                                                                |
126	| `TaskCreated`         | When a task is being created via `TaskCreate`                                                                                |
127	| `TaskCompleted`       | When a task is being marked as completed                                                                                |
128	| `Stop`                | When Claude finishes responding                                                                                |
129	| `StopFailure`         | When the turn ends due to an API error. Output and exit code are ignored                                                                               |
130	| `TeammateIdle`        | When an [agent team](/en/agent-teams) teammate is about to go idle                                                                                |
131	| `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         |
132	| `ConfigChange`        | When a configuration file changes during a session                                                                                |
133	| `CwdChanged`          | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |
134	| `FileChanged`         | When a watched file changes on disk. The `matcher` field specifies which filenames to watch                                                            |
135	| `WorktreeCreate`      | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior                                            |
136	| `WorktreeRemove`      | When a worktree is being removed, either at session exit or when a subagent finishes                                                                   |
137	| `PreCompact`          | Before context compaction                                                                                |
138	| `PostCompact`         | After context compaction completes                                                                                |
139	| `Elicitation`         | When an MCP server requests user input during a tool call                                                                                |
140	| `ElicitationResult`   | After a user responds to an MCP elicitation, before the response is sent back to the server                                                            |
141	| `SessionEnd`          | When a session terminates                                                                                |
142
143	**Hook types**:
144
145	* `command`: execute shell commands or scripts
146	* `http`: send the event JSON as a POST request to a URL
147	* `mcp_tool`: call a tool on a configured [MCP server](/en/mcp)
148	* `prompt`: evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)
149	* `agent`: run an agentic verifier with tools for complex verification tasks
150
151	### MCP servers
152
153	Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools and services.
154
155	**Location**: `.mcp.json` in plugin root, or inline in plugin.json
156
157	**Format**: Standard MCP server configuration
158
159	**MCP server configuration**:
160
161	```json theme={null}
162	{
163	  "mcpServers": {
164	    "plugin-database": {
165	      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
166	      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
167	      "env": {
168	        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
169	      }
170	    },
171	    "plugin-api-client": {
172	      "command": "npx",
173	      "args": ["@company/mcp-server", "--plugin-mode"],
174	      "cwd": "${CLAUDE_PLUGIN_ROOT}"
175	    }
176	  }
177	}
178	```
179
180	**Integration behavior**:
181
182	* Plugin MCP servers start automatically when the plugin is enabled
183	* Servers appear as standard MCP tools in Claude's toolkit
184	* Server capabilities integrate seamlessly with Claude's existing tools
185	* Plugin servers can be configured independently of user MCP servers
186
187	### LSP servers
188
189	<Tip>
190	  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.
191	</Tip>
192
193	Plugins 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.
194
195	LSP integration provides:
196
197	* **Instant diagnostics**: Claude sees errors and warnings immediately after each edit
198	* **Code navigation**: go to definition, find references, and hover information
199	* **Language awareness**: type information and documentation for code symbols
200
201	**Location**: `.lsp.json` in plugin root, or inline in `plugin.json`
202
203	**Format**: JSON configuration mapping language server names to their configurations
204
205	**`.lsp.json` file format**:
206
207	```json theme={null}
208	{
209	  "go": {
210	    "command": "gopls",
211	    "args": ["serve"],
212	    "extensionToLanguage": {
213	      ".go": "go"
214	    }
215	  }
216	}
217	```
218
219	**Inline in `plugin.json`**:
220
221	```json theme={null}
222	{
223	  "name": "my-plugin",
224	  "lspServers": {
225	    "go": {
226	      "command": "gopls",
227	      "args": ["serve"],
228	      "extensionToLanguage": {
229	        ".go": "go"
230	      }
231	    }
232	  }
233	}
234	```
235
236	**Required fields:**
237
238	| Field                 | Description                                  |
239	| :-------------------- | :------------------------------------------- |
240	| `command`             | The LSP binary to execute (must be in PATH)  |
241	| `extensionToLanguage` | Maps file extensions to language identifiers |
242
243	**Optional fields:**
244
245	| Field                   | Description                                               |
246	| :---------------------- | :-------------------------------------------------------- |
247	| `args`                  | Command-line arguments for the LSP server                 |
248	| `transport`             | Communication transport: `stdio` (default) or `socket`    |
249	| `env`                   | Environment variables to set when starting the server     |
250	| `initializationOptions` | Options passed to the server during initialization        |
251	| `settings`              | Settings passed via `workspace/didChangeConfiguration`    |
252	| `workspaceFolder`       | Workspace folder path for the server                      |
253	| `startupTimeout`        | Max time to wait for server startup (milliseconds)        |
254	| `shutdownTimeout`       | Max time to wait for graceful shutdown (milliseconds)     |
255	| `restartOnCrash`        | Whether to automatically restart the server if it crashes |
256	| `maxRestarts`           | Maximum number of restart attempts before giving up       |
257
258	<Warning>
259	  **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.
260	</Warning>
261
262	**Available LSP plugins:**
263
264	| Plugin           | Language server            | Install command                                                                            |
265	| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- |
266	| `pyright-lsp`    | Pyright (Python)           | `pip install pyright` or `npm install -g pyright`                                          |
267	| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript`                                     |
268	| `rust-lsp`       | rust-analyzer              | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |
269
270	Install the language server first, then install the plugin from the marketplace.
271
272	### Monitors
273
274	Plugins 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.
275
276	Plugin 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.
277
278	<Note>
279	  Plugin monitors require Claude Code v2.1.105 or later.
280	</Note>
281
282	**Location**: `monitors/monitors.json` in the plugin root, or inline in `plugin.json`
283
284	**Format**: JSON array of monitor entries
285
286	The following `monitors/monitors.json` watches a deployment status endpoint and a local error log:
287
288	```json theme={null}
289	[
290	  {
291	    "name": "deploy-status",
292	    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
293	    "description": "Deployment status changes"
294	  },
295	  {
296	    "name": "error-log",
297	    "command": "tail -F ./logs/error.log",
298	    "description": "Application error log",
299	    "when": "on-skill-invoke:debug"
300	  }
301	]
302	```
303
304	To 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"`.
305
306	**Required fields:**
307
308	| Field         | Description                                                                                |
309	| :------------ | :-------------------------------------------------------------------------------------------------------------------- |
310	| `name`        | Identifier unique within the plugin. Prevents duplicate processes when the plugin reloads or a skill is invoked again |
311	| `command`     | Shell command run as a persistent background process in the session working directory                                 |
312	| `description` | Short summary of what is being watched. Shown in the task panel and in notification summaries                         |
313
314	**Optional fields:**
315
316	| Field  | Description                                                                                |
317	| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
318	| `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 |
319
320	The `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.
321
322	Disabling a plugin mid-session does not stop monitors that are already running. They stop when the session ends.
323
324	### Themes
325
326	Plugins 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.
327
328	```json theme={null}
329	{
330	  "name": "Dracula",
331	  "base": "dark",
332	  "overrides": {
333	    "claude": "#bd93f9",
334	    "error": "#ff5555",
335	    "success": "#50fa7b"
336	  }
337	}
338	```
339
340	Selecting 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.
341
342	***
343
344	## Plugin installation scopes
345
346	When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:
347
348	| Scope     | Settings file                                   | Use case                                                 |
349	| :-------- | :---------------------------------------------- | :------------------------------------------------------- |
350	| `user`    | `~/.claude/settings.json`                       | Personal plugins available across all projects (default) |
351	| `project` | `.claude/settings.json`                         | Team plugins shared via version control                  |
352	| `local`   | `.claude/settings.local.json`                   | Project-specific plugins, gitignored                     |
353	| `managed` | [Managed settings](/en/settings#settings-files) | Managed plugins (read-only, update only)                 |
354
355	Plugins 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).
356
357	***
358
359	## Plugin manifest schema
360
361	The `.claude-plugin/plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options.
362
363	The 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.
364
365	### Complete schema
366
367	```json theme={null}
368	{
369	  "name": "plugin-name",
370	  "version": "1.2.0",
371	  "description": "Brief plugin description",
372	  "author": {
373	    "name": "Author Name",
374	    "email": "author@example.com",
375	    "url": "https://github.com/author"
376	  },
377	  "homepage": "https://docs.example.com/plugin",
378	  "repository": "https://github.com/author/plugin",
379	  "license": "MIT",
380	  "keywords": ["keyword1", "keyword2"],
381	  "skills": "./custom/skills/",
382	  "commands": ["./custom/commands/special.md"],
383	  "agents": ["./custom/agents/reviewer.md"],
384	  "hooks": "./config/hooks.json",
385	  "mcpServers": "./mcp-config.json",
386	  "outputStyles": "./styles/",
387	  "themes": "./themes/",
388	  "lspServers": "./.lsp.json",
389	  "monitors": "./monitors.json",
390	  "dependencies": [
391	    "helper-lib",
392	    { "name": "secrets-vault", "version": "~2.1.0" }
393	  ]
394	}
395	```
396
397	### Required fields
398
399	If you include a manifest, `name` is the only required field.
400
401	| Field  | Type   | Description                               | Example              |
402	| :----- | :----- | :---------------------------------------- | :------------------- |
403	| `name` | string | Unique identifier (kebab-case, no spaces) | `"deployment-tools"` |
404
405	This name is used for namespacing components. For example, in the UI, the
406	agent `agent-creator` for the plugin with name `plugin-dev` will appear as
407	`plugin-dev:agent-creator`.
408
409	### Metadata fields
410
411	| Field         | Type   | Description                                                                                | Example                                                           |
412	| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
413	| `$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"` |
414	| `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"`                                                         |
415	| `description` | string | Brief explanation of plugin purpose                                                                                | `"Deployment automation tools"`                                   |
416	| `author`      | object | Author information                                                                                | `{"name": "Dev Team", "email": "dev@company.com"}`                |
417	| `homepage`    | string | Documentation URL                                                                                | `"https://docs.example.com"`                                      |
418	| `repository`  | string | Source code URL                                                                                | `"https://github.com/user/plugin"`                                |
419	| `license`     | string | License identifier                                                                                | `"MIT"`, `"Apache-2.0"`                                           |
420	| `keywords`    | array  | Discovery tags                                                                                | `["deployment", "ci-cd"]`                                         |
421
422	### Component path fields
423
424	| Field          | Type                  | Description                                                                                | Example                                              |
425	| :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
426	| `skills`       | string\|array         | Custom skill directories containing `<name>/SKILL.md` (replaces default `skills/`)                                                                        | `"./custom/skills/"`                                 |
427	| `commands`     | string\|array         | Custom flat `.md` skill files or directories (replaces default `commands/`)                                                                               | `"./custom/cmd.md"` or `["./cmd1.md"]`               |
428	| `agents`       | string\|array         | Custom agent files (replaces default `agents/`)                                                                                | `"./custom/agents/reviewer.md"`                      |
429	| `hooks`        | string\|array\|object | Hook config paths or inline config                                                                                | `"./my-extra-hooks.json"`                            |
430	| `mcpServers`   | string\|array\|object | MCP config paths or inline config                                                                                | `"./my-extra-mcp-config.json"`                       |
431	| `outputStyles` | string\|array         | Custom output style files/directories (replaces default `output-styles/`)                                                                                | `"./styles/"`                                        |
432	| `themes`       | string\|array         | Color theme files/directories (replaces default `themes/`). See [Themes](#themes)                                                                         | `"./themes/"`                                        |
433	| `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"`                                      |
434	| `monitors`     | string\|array         | Background [Monitor](/en/tools-reference#monitor-tool) configurations that start automatically when the plugin is active. See [Monitors](#monitors)       | `"./monitors.json"`                                  |
435	| `userConfig`   | object                | User-configurable values prompted at enable time. See [User configuration](#user-configuration)                                                           | See below                                            |
436	| `channels`     | array                 | Channel declarations for message injection (Telegram, Slack, Discord style). See [Channels](#channels)                                                    | See below                                            |
437	| `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" }]` |
438
439	### User configuration
440
441	The `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`.
442
443	```json theme={null}
444	{
445	  "userConfig": {
446	    "api_endpoint": {
447	      "type": "string",
448	      "title": "API endpoint",
449	      "description": "Your team's API endpoint"
450	    },
451	    "api_token": {
452	      "type": "string",
453	      "title": "API token",
454	      "description": "API authentication token",
455	      "sensitive": true
456	    }
457	  }
458	}
459	```
460
461	Keys must be valid identifiers. Each option supports these fields:
462
463	| Field         | Required | Description                                                                              |
464	| :------------ | :------- | :--------------------------------------------------------------------------------------- |
465	| `type`        | Yes      | One of `string`, `number`, `boolean`, `directory`, or `file`                             |
466	| `title`       | Yes      | Label shown in the configuration dialog                                                  |
467	| `description` | Yes      | Help text shown beneath the field                                                        |
468	| `sensitive`   | No       | If `true`, masks input and stores the value in secure storage instead of `settings.json` |
469	| `required`    | No       | If `true`, validation fails when the field is empty                                      |
470	| `default`     | No       | Value used when the user provides nothing                                                |
471	| `multiple`    | No       | For `string` type, allow an array of strings                                             |
472	| `min` / `max` | No       | Bounds for `number` type                                                                 |
473
474	Each 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.
475
476	Non-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.
477
478	### Channels
479
480	The `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.
481
482	```json theme={null}
483	{
484	  "channels": [
485	    {
486	      "server": "telegram",
487	      "userConfig": {
488	        "bot_token": {
489	          "type": "string",
490	          "title": "Bot token",
491	          "description": "Telegram bot token",
492	          "sensitive": true
493	        },
494	        "owner_id": {
495	          "type": "string",
496	          "title": "Owner ID",
497	          "description": "Your Telegram user ID"
498	        }
499	      }
500	    }
501	  ]
502	}
503	```
504
505	The `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.
506
507	### Path behavior rules
508
509	For `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.
510
511	* All paths must be relative to the plugin root and start with `./`
512	* Components from custom paths use the same naming and namespacing rules
513	* Multiple paths can be specified as arrays
514	* 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/"]`
515	* 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.
516
517	**Path examples**:
518
519	```json theme={null}
520	{
521	  "commands": [
522	    "./specialized/deploy.md",
523	    "./utilities/batch-process.md"
524	  ],
525	  "agents": [
526	    "./custom-agents/reviewer.md",
527	    "./custom-agents/tester.md"
528	  ]
529	}
530	```
531
532	### Environment variables
533
534	Claude 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.
535
536	**`${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.
537
538	**`${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.
539
540	```json theme={null}
541	{
542	  "hooks": {
543	    "PostToolUse": [
544	      {
545	        "hooks": [
546	          {
547	            "type": "command",
548	            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
549	          }
550	        ]
551	      }
552	    ]
553	  }
554	}
555	```
556
557	#### Persistent data directory
558
559	The `${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/`.
560
561	A 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.
562
563	This `SessionStart` hook installs `node_modules` on the first run and again whenever a plugin update includes a changed `package.json`:
564
565	```json theme={null}
566	{
567	  "hooks": {
568	    "SessionStart": [
569	      {
570	        "hooks": [
571	          {
572	            "type": "command",
573	            "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\""
574	          }
575	        ]
576	      }
577	    ]
578	  }
579	}
580	```
581
582	The `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.
583
584	Scripts bundled in `${CLAUDE_PLUGIN_ROOT}` can then run against the persisted `node_modules`:
585
586	```json theme={null}
587	{
588	  "mcpServers": {
589	    "routines": {
590	      "command": "node",
591	      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
592	      "env": {
593	        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
594	      }
595	    }
596	  }
597	}
598	```
599
600	The 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.
601
602	***
603
604	## Plugin caching and file resolution
605
606	Plugins are specified in one of two ways:
607
608	* Through `claude --plugin-dir`, for the duration of a session.
609	* Through a marketplace, installed for future sessions.
610
611	For 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.
612
613	Each 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.
614
615	Claude's Glob and Grep tools skip orphaned version directories during searches, so file results don't include outdated plugin code.
616
617	### Path traversal limitations
618
619	Installed 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.
620
621	### Working with external dependencies
622
623	If 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:
624
625	```bash theme={null}
626	ln -s /path/to/shared-utils ./shared-utils
627	```
628
629	This provides flexibility while maintaining the security benefits of the caching system.
630
631	***
632
633	## Plugin directory structure
634
635	### Standard plugin layout
636
637	A complete plugin follows this structure:
638
639	```text theme={null}
640	enterprise-plugin/
641	├── .claude-plugin/           # Metadata directory (optional)
642	│   └── plugin.json             # plugin manifest
643	├── skills/                   # Skills
644	│   ├── code-reviewer/
645	│   │   └── SKILL.md
646	│   └── pdf-processor/
647	│       ├── SKILL.md
648	│       └── scripts/
649	├── commands/                 # Skills as flat .md files
650	│   ├── status.md
651	│   └── logs.md
652	├── agents/                   # Subagent definitions
653	│   ├── security-reviewer.md
654	│   ├── performance-tester.md
655	│   └── compliance-checker.md
656	├── output-styles/            # Output style definitions
657	│   └── terse.md
658	├── themes/                   # Color theme definitions
659	│   └── dracula.json
660	├── monitors/                 # Background monitor configurations
661	│   └── monitors.json
662	├── hooks/                    # Hook configurations
663	│   ├── hooks.json           # Main hook config
664	│   └── security-hooks.json  # Additional hooks
665	├── bin/                      # Plugin executables added to PATH
666	│   └── my-tool               # Invokable as bare command in Bash tool
667	├── settings.json            # Default settings for the plugin
668	├── .mcp.json                # MCP server definitions
669	├── .lsp.json                # LSP server configurations
670	├── scripts/                 # Hook and utility scripts
671	│   ├── security-scan.sh
672	│   ├── format-code.py
673	│   └── deploy.js
674	├── LICENSE                  # License file
675	└── CHANGELOG.md             # Version history
676	```
677
678	<Warning>
679	  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/`.
680	</Warning>
681
682	### File locations reference
683
684	| Component         | Default Location             | Purpose                                                                                |
685	| :---------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
686	| **Manifest**      | `.claude-plugin/plugin.json` | Plugin metadata and configuration (optional)                                                                                |
687	| **Skills**        | `skills/`                    | Skills with `<name>/SKILL.md` structure                                                                                |
688	| **Commands**      | `commands/`                  | Skills as flat Markdown files. Use `skills/` for new plugins                                                                                |
689	| **Agents**        | `agents/`                    | Subagent Markdown files                                                                                |
690	| **Output styles** | `output-styles/`             | Output style definitions                                                                                |
691	| **Themes**        | `themes/`                    | Color theme definitions                                                                                |
692	| **Hooks**         | `hooks/hooks.json`           | Hook configuration                                                                                |
693	| **MCP servers**   | `.mcp.json`                  | MCP server definitions                                                                                |
694	| **LSP servers**   | `.lsp.json`                  | Language server configurations                                                                                |
695	| **Monitors**      | `monitors/monitors.json`     | Background monitor configurations                                                                                |
696	| **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                                                   |
697	| **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 |
698
699	***
700
701	## CLI commands reference
702
703	Claude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation.
704
705	### plugin install
706
707	Install a plugin from available marketplaces.
708
709	```bash theme={null}
710	claude plugin install <plugin> [options]
711	```
712
713	**Arguments:**
714
715	* `<plugin>`: Plugin name or `plugin-name@marketplace-name` for a specific marketplace
716
717	**Options:**
718
719	| Option                | Description                                       | Default |
720	| :-------------------- | :------------------------------------------------ | :------ |
721	| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local` | `user`  |
722	| `-h, --help`          | Display help for command                          |         |
723
724	Scope 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.
725
726	**Examples:**
727
728	```bash theme={null}
729	# Install to user scope (default)
730	claude plugin install formatter@my-marketplace
731
732	# Install to project scope (shared with team)
733	claude plugin install formatter@my-marketplace --scope project
734
735	# Install to local scope (gitignored)
736	claude plugin install formatter@my-marketplace --scope local
737	```
738
739	### plugin uninstall
740
741	Remove an installed plugin.
742
743	```bash theme={null}
744	claude plugin uninstall <plugin> [options]
745	```
746
747	**Arguments:**
748
749	* `<plugin>`: Plugin name or `plugin-name@marketplace-name`
750
751	**Options:**
752
753	| Option                | Description                                                                                | Default |
754	| :-------------------- | :------------------------------------------------------------------------------------------------------- | :------ |
755	| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local`                                                      | `user`  |
756	| `--keep-data`         | Preserve the plugin's [persistent data directory](#persistent-data-directory)                            |         |
757	| `--prune`             | Also remove auto-installed dependencies that no other plugin requires. See [plugin prune](#plugin-prune) |         |
758	| `-y, --yes`           | Skip the `--prune` confirmation prompt. Required when stdin is not a TTY                                 |         |
759	| `-h, --help`          | Display help for command                                                                                |         |
760
761	**Aliases:** `remove`, `rm`
762
763	By 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.
764
765	### plugin prune
766
767	Remove 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.
768
769	```bash theme={null}
770	claude plugin prune [options]
771	```
772
773	**Options:**
774
775	| Option                | Description                                                    | Default |
776	| :-------------------- | :------------------------------------------------------------- | :------ |
777	| `-s, --scope <scope>` | Prune at scope: `user`, `project`, or `local`                  | `user`  |
778	| `--dry-run`           | List what would be removed without removing anything           |         |
779	| `-y, --yes`           | Skip the confirmation prompt. Required when stdin is not a TTY |         |
780	| `-h, --help`          | Display help for command                                       |         |
781
782	**Aliases:** `autoremove`
783
784	The 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`.
785
786	<Note>
787	  `claude plugin prune` requires Claude Code v2.1.121 or later.
788	</Note>
789
790	### plugin enable
791
792	Enable a disabled plugin.
793
794	```bash theme={null}
795	claude plugin enable <plugin> [options]
796	```
797
798	**Arguments:**
799
800	* `<plugin>`: Plugin name or `plugin-name@marketplace-name`
801
802	**Options:**
803
804	| Option                | Description                                    | Default |
805	| :-------------------- | :--------------------------------------------- | :------ |
806	| `-s, --scope <scope>` | Scope to enable: `user`, `project`, or `local` | `user`  |
807	| `-h, --help`          | Display help for command                       |         |
808
809	### plugin disable
810
811	Disable a plugin without uninstalling it.
812
813	```bash theme={null}
814	claude plugin disable <plugin> [options]
815	```
816
817	**Arguments:**
818
819	* `<plugin>`: Plugin name or `plugin-name@marketplace-name`
820
821	**Options:**
822
823	| Option                | Description                                     | Default |
824	| :-------------------- | :---------------------------------------------- | :------ |
825	| `-s, --scope <scope>` | Scope to disable: `user`, `project`, or `local` | `user`  |
826	| `-h, --help`          | Display help for command                        |         |
827
828	### plugin update
829
830	Update a plugin to the latest version.
831
832	```bash theme={null}
833	claude plugin update <plugin> [options]
834	```
835
836	**Arguments:**
837
838	* `<plugin>`: Plugin name or `plugin-name@marketplace-name`
839
840	**Options:**
841
842	| Option                | Description                                               | Default |
843	| :-------------------- | :-------------------------------------------------------- | :------ |
844	| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed` | `user`  |
845	| `-h, --help`          | Display help for command                                  |         |
846
847	***
848
849	### plugin list
850
851	List installed plugins with their version, source marketplace, and enable status.
852
853	```bash theme={null}
854	claude plugin list [options]
855	```
856
857	**Options:**
858
859	| Option        | Description                                                    | Default |
860	| :------------ | :------------------------------------------------------------- | :------ |
861	| `--json`      | Output as JSON                                                 |         |
862	| `--available` | Include available plugins from marketplaces. Requires `--json` |         |
863	| `-h, --help`  | Display help for command                                       |         |
864
865	### plugin tag
866
867	Create 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).
868
869	```bash theme={null}
870	claude plugin tag [options]
871	```
872
873	**Options:**
874
875	| Option        | Description                                                                | Default |
876	| :------------ | :------------------------------------------------------------------------- | :------ |
877	| `--push`      | Push the tag to the remote after creating it                               |         |
878	| `--dry-run`   | Print what would be tagged without creating the tag                        |         |
879	| `-f, --force` | Create the tag even if the working tree is dirty or the tag already exists |         |
880	| `-h, --help`  | Display help for command                                                   |         |
881
882	***
883
884	## Debugging and development tools
885
886	### Debugging commands
887
888	Use `claude --debug` to see plugin loading details:
889
890	This shows:
891
892	* Which plugins are being loaded
893	* Any errors in plugin manifests
894	* Skill, agent, and hook registration
895	* MCP server initialization
896
897	### Common issues
898
899	| Issue                               | Cause                           | Solution                                                                                |
900	| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
901	| 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 |
902	| Skills not appearing                | Wrong directory structure       | Ensure `skills/` or `commands/` is at the plugin root, not inside `.claude-plugin/`                                                                             |
903	| Hooks not firing                    | Script not executable           | Run `chmod +x script.sh`                                                                                |
904	| MCP server fails                    | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths                                                                                |
905	| Path errors                         | Absolute paths used             | All paths must be relative and start with `./`                                                                                |
906	| LSP `Executable not found in $PATH` | Language server not installed   | Install the binary (e.g., `npm install -g typescript-language-server typescript`)                                                                               |
907
908	### Example error messages
909
910	**Manifest validation errors**:
911
912	* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings
913	* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`: a required field is missing
914	* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error
915
916	**Plugin loading errors**:
917
918	* `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
919	* `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
920	* `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
921
922	### Hook troubleshooting
923
924	**Hook script not executing**:
925
926	1. Check the script is executable: `chmod +x ./scripts/your-script.sh`
927	2. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash`
928	3. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"`
929	4. Test the script manually: `./scripts/your-script.sh`
930
931	**Hook not triggering on expected events**:
932
933	1. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`
934	2. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations
935	3. Confirm the hook type is valid: `command`, `http`, `mcp_tool`, `prompt`, or `agent`
936
937	### MCP server troubleshooting
938
939	**Server not starting**:
940
941	1. Check the command exists and is executable
942	2. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable
943	3. Check the MCP server logs: `claude --debug` shows initialization errors
944	4. Test the server manually outside of Claude Code
945
946	**Server tools not appearing**:
947
948	1. Ensure the server is properly configured in `.mcp.json` or `plugin.json`
949	2. Verify the server implements the MCP protocol correctly
950	3. Check for connection timeouts in debug output
951
952	### Directory structure mistakes
953
954	**Symptoms**: Plugin loads but components (skills, agents, hooks) are missing.
955
956	**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.
957
958	```text theme={null}
959	my-plugin/
960	├── .claude-plugin/
961	│   └── plugin.json      ← Only manifest here
962	├── commands/            ← At root level
963	├── agents/              ← At root level
964	└── hooks/               ← At root level
965	```
966
967	If your components are inside `.claude-plugin/`, move them to the plugin root.
968
969	**Debug checklist**:
970
971	1. Run `claude --debug` and look for "loading plugin" messages
972	2. Check that each component directory is listed in the debug output
973	3. Verify file permissions allow reading the plugin files
974
975	***
976
977	## Distribution and versioning reference
978
979	### Version management
980
981	Claude 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.
982
983	The version is resolved from the first of these that is set:
984
985	1. The `version` field in the plugin's `plugin.json`
986	2. The `version` field in the plugin's marketplace entry in `marketplace.json`
987	3. The git commit SHA of the plugin's source, for `github`, `url`, `git-subdir`, and relative-path sources in a git-hosted marketplace
988	4. `unknown`, for `npm` sources or local directories not inside a git repository
989
990	This gives you two ways to version a plugin:
991
992	| Approach               | How                                                              | Update behavior                                                                                | Best for                                          |
993	| :--------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |
994	| **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      |
995	| **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 |
996
997	<Warning>
998	  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.
999	</Warning>
1000
1001	If 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`.
1002
1003	***
1004
1005	## See also
1006
1007	* [Plugins](/en/plugins) - Tutorials and practical usage
1008	* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces
1009	* [Skills](/en/skills) - Skill development details
1010	* [Subagents](/en/sub-agents) - Agent configuration and capabilities
1011	* [Hooks](/en/hooks) - Event handling and automation
1012	* [MCP](/en/mcp) - External tool integration
1013	* [Settings](/en/settings) - Configuration options for plugins
1014


Perfect. I found the theme documentation. Let me fetch the terminal config page to check for any additional color control mechanisms.


Prompt: color theme ANSI terminal appearance


> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure your terminal for Claude Code

> 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.

Claude 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.

* [Shift+Enter submits instead of inserting a newline](#enter-multiline-prompts)
* [Option-key shortcuts do nothing on macOS](#enable-option-key-shortcuts-on-macos)
* [No sound or alert when Claude finishes](#get-a-terminal-bell-or-notification)
* [You run Claude Code inside tmux](#configure-tmux)
* [Display flickers or scrollback jumps](#switch-to-fullscreen-rendering)
* [You want Vim keys in the prompt](#edit-prompts-with-vim-keybindings)

This 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.

## Enter multiline prompts

Pressing 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.

In most terminals you can also press Shift+Enter, but support varies by terminal emulator:

| Terminal                                                                            | Shift+Enter for newline                     |
| :---------------------------------------------------------------------------------- | :------------------------------------------ |
| Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal                               | Works without setup                         |
| VS Code, Cursor, Windsurf, Alacritty, Zed                                           | Run `/terminal-setup` once                  |
| Windows Terminal, gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio | Not available; use Ctrl+J or `\` then Enter |

For 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.

If you are running inside tmux, Shift+Enter also requires the [tmux configuration below](#configure-tmux) even when the outer terminal supports it.

To 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).

## Enable Option key shortcuts on macOS

Some 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.

<Tabs>
  <Tab title="Apple Terminal">
    Open Settings → Profiles → Keyboard and check "Use Option as Meta Key".

    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.
  </Tab>

  <Tab title="iTerm2">
    Open Settings → Profiles → Keys → General and set Left Option key and Right Option key to "Esc+".

    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.
  </Tab>

  <Tab title="VS Code">
    Add `"terminal.integrated.macOptionIsMeta": true` to your VS Code settings.
  </Tab>
</Tabs>

For Ghostty, Kitty, and other terminals, look for an Option-as-Alt or Option-as-Meta setting in the terminal's configuration file.

## Get a terminal bell or notification

When 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.

By 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.

The 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:

<Steps>
  <Step title="Open iTerm2 notification settings">
    Go to Settings → Profiles → Terminal.
  </Step>

  <Step title="Enable alerts">
    Check "Notification Center Alerts", then click "Filter Alerts" and enable "Send escape sequence-generated alerts".
  </Step>
</Steps>

If 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).

### Play a sound with a Notification hook

In 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.

The example below plays a system sound on macOS. The linked guide has desktop notification commands for macOS, Linux, and Windows.

```json ~/.claude/settings.json theme={null}
{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}
```

## Configure tmux

When 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:

```bash ~/.tmux.conf theme={null}
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
```

The `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.

## Match the color theme

Use 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.

To 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.

### Create a custom theme

<Note>
  Custom themes require Claude Code v2.1.118 or later.
</Note>

In 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.

Each 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:

| Field       | Type   | Description                                                                                |
| :---------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | string | Display label shown in `/theme`. Defaults to the filename slug                                                                                |
| `base`      | string | Built-in preset the theme starts from: `dark`, `light`, `dark-daltonized`, `light-daltonized`, `dark-ansi`, or `light-ansi`. Defaults to `dark` |
| `overrides` | object | Map of color token names to color values. Tokens not listed here fall through to the base preset                                                |

Color 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.

The following example defines a theme that keeps the dark preset but recolors the prompt accent, error text, and success text:

```json ~/.claude/themes/dracula.json theme={null}
{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}
```

Claude Code watches `~/.claude/themes/` and reloads when a file changes, so edits made in your editor apply to a running session without a restart.

The 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.

<Accordion title="Color token reference">
  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.

  ```json ~/.claude/themes/midnight.json theme={null}
  {
    "name": "Midnight",
    "base": "dark",
    "overrides": {
      "claude": "#a78bfa",
      "planMode": "#38bdf8",
      "diffAdded": "#14532d",
      "diffRemoved": "#7f1d1d",
      "userMessageBackground": "#1e1b4b"
    }
  }
  ```

  #### Text and accent colors

  Control the primary brand accent and the foreground text shades used throughout the interface.

  | Token         | Controls                                                         |
  | :------------ | :--------------------------------------------------------------- |
  | `claude`      | Primary brand accent, used for the spinner and assistant label   |
  | `text`        | Default foreground text                                          |
  | `inverseText` | Text drawn on top of a colored background, such as status badges |
  | `inactive`    | Secondary text such as hints, timestamps, and disabled items     |
  | `subtle`      | Faint borders and de-emphasized secondary text                   |
  | `suggestion`  | Autocomplete suggestions and selection highlight in pickers      |
  | `permission`  | Dialog borders, including permission prompts and pickers         |
  | `remember`    | Memory and `CLAUDE.md` indicators                                |

  #### Status colors

  Signal success, failure, and warning states across messages and indicators.

  | Token     | Controls                                             |
  | :-------- | :--------------------------------------------------- |
  | `success` | Success messages and passing checks                  |
  | `error`   | Error messages and failures                          |
  | `warning` | Warnings, caution messages, and the auto mode border |
  | `merged`  | Merged pull request status                           |

  #### Input box and mode indicators

  Set the input box border color and the accent shown while a permission mode or indicator is active.

  | Token          | Controls                                           |
  | :------------- | :------------------------------------------------- |
  | `promptBorder` | Input box border in the default permission mode    |
  | `planMode`     | Plan mode accent and border                        |
  | `autoAccept`   | Accept-edits mode accent and border                |
  | `bashBorder`   | Input box border when entering a `!` shell command |
  | `ide`          | IDE connection indicator                           |
  | `fastMode`     | Fast mode indicator                                |

  #### Diff rendering

  Color added and removed code in file edits and reviews.

  | Token               | Controls                                           |
  | :------------------ | :------------------------------------------------- |
  | `diffAdded`         | Background of added lines                          |
  | `diffRemoved`       | Background of removed lines                        |
  | `diffAddedDimmed`   | Background of unchanged context near added lines   |
  | `diffRemovedDimmed` | Background of unchanged context near removed lines |
  | `diffAddedWord`     | Word-level highlight within an added line          |
  | `diffRemovedWord`   | Word-level highlight within a removed line         |

  #### Fullscreen mode

  Apply only in [fullscreen rendering mode](/en/fullscreen), where messages have a background fill.

  | Token                        | Controls                                                           |
  | :--------------------------- | :----------------------------------------------------------------- |
  | `userMessageBackground`      | Background behind your messages in the transcript                  |
  | `userMessageBackgroundHover` | Background behind a message while hovered or expanded              |
  | `messageActionsBackground`   | Background behind the selected message when the action bar is open |
  | `bashMessageBackgroundColor` | Background behind `!` shell command entries in the transcript      |
  | `memoryBackgroundColor`      | Background behind `#` memory entries in the transcript             |
  | `selectionBg`                | Background of text selected with the mouse                         |

  #### Usage meter and speaker labels

  Adjust the bar shown in the `/usage` view and the labels that distinguish your messages from Claude's.

  | Token              | Controls                                          |
  | :----------------- | :------------------------------------------------ |
  | `rate_limit_fill`  | Filled portion of the usage meter                 |
  | `rate_limit_empty` | Unfilled portion of the usage meter               |
  | `briefLabelYou`    | Color of the `You` label on your messages         |
  | `briefLabelClaude` | Color of the `Claude` label on assistant messages |

  #### Shimmer variants and subagent colors

  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.

  * `claude` and `claudeShimmer`
  * `warning` and `warningShimmer`
  * `permission` and `permissionShimmer`
  * `promptBorder` and `promptBorderShimmer`
  * `inactive` and `inactiveShimmer`
  * `fastMode` and `fastModeShimmer`

  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.

  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`.
</Accordion>

## Switch to fullscreen rendering

If 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.

Run `/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:

<CodeGroup>
  ```bash Bash and Zsh theme={null}
  CLAUDE_CODE_NO_FLICKER=1 claude
  ```

  ```powershell PowerShell theme={null}
  $env:CLAUDE_CODE_NO_FLICKER = "1"; claude
  ```

  ```json ~/.claude/settings.json theme={null}
  {
    "env": {
      "CLAUDE_CODE_NO_FLICKER": "1"
    }
  }
  ```
</CodeGroup>

## Paste large content

When 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.

The 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.

## Edit prompts with Vim keybindings

Claude 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.

Vim 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.

Pressing 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.

## Related resources

* [Interactive mode](/en/interactive-mode): full keyboard shortcut reference and the Vim key table
* [Keybindings](/en/keybindings): remap any Claude Code shortcut, including Enter and Shift+Enter
* [Fullscreen rendering](/en/fullscreen): details on scrolling, search, and copy in fullscreen mode
* [Hooks guide](/en/hooks-guide): more Notification hook examples for Linux and Windows
* [Troubleshooting](/en/troubleshooting): fixes for issues outside terminal configuration


Excellent. I now have all the information needed to provide a definitive answer. Let me compile the findings.

## Definitive Answer: Claude Code Theme Customization (v2.1.126)

**1. Built-in themes:**
Claude Code ships with 6 preset themes accessible via `/theme`:
- `dark` (default)
- `light`
- `dark-daltonized` (colorblind-friendly)
- `light-daltonized` (colorblind-friendly)
- `dark-ansi` (terminal-aware)
- `light-ansi` (terminal-aware)

**2. Custom themes—YES, fully supported (v2.1.118+):**
Users CAN create custom color themes. Implementation:
- Create JSON files in `~/.claude/themes/`
- Each file = one theme with `name`, `base` (preset), and `overrides` (color token map)
- Interactive editor: select "New custom theme…" in `/theme` to build one step-by-step
- Supported color formats: `#rrggbb`, `#rgb`, `rgb(r,g,b)`, `ansi256(n)`, or `ansi:<name>`
- Live reload: changes apply immediately without restart
- Pressable: distribute custom themes via plugins

**3. Color tokens (token reference):**
40+ 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

**4. Terminal interaction:**
Claude 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).

**5. Individual color override:**
Not separately—users must define a theme (even a sparse one) to override specific tokens. No per-color env vars or hooks.

**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.