Documentation 2026-01-10 21:01 UTC to 2026-01-11 18:02 UTC

8 8 

9The Claude desktop app provides a native interface for running multiple Claude Code sessions on your local machine and seamless integration with Claude Code on the web.9The Claude desktop app provides a native interface for running multiple Claude Code sessions on your local machine and seamless integration with Claude Code on the web.

10 10 

11## Features11## Installation

12 12 

13Claude Code on desktop provides:13Download the Claude desktop app for your platform:

14 14 

15* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree15<CardGroup cols={2}>

16* **Include files listed in your `.gitignore` in your worktrees**: Automatically copy files in your `.gitignore`, like `.env`, to new worktrees using `.worktreeinclude`16 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

17* **Launch Claude Code on the web**: Kick off secure cloud sessions directly from the desktop app17 Universal build for Intel and Apple Silicon

18 </Card>

18 19 

19## Installation20 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">

21 For x64 processors

22 </Card>

23</CardGroup>

20 24 

21Download and install the Claude Desktop app from [claude.ai/download](https://claude.ai/download)25For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).

22 26 

23<Note>27<Note>

24 Local sessions are not available on Windows arm64 architectures.28 Local sessions are not available on Windows ARM64.

25</Note>29</Note>

26 30 

31## Features

32 

33Claude Code on desktop provides:

34 

35* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree

36* **Include files listed in your `.gitignore` in your worktrees**: Automatically copy files in your `.gitignore`, like `.env`, to new worktrees using `.worktreeinclude`

37* **Launch Claude Code on the web**: Kick off secure cloud sessions directly from the desktop app

38 

27## Using Git worktrees39## Using Git worktrees

28 40 

29Claude Code on desktop enables running multiple Claude Code sessions in the same repository using Git worktrees. Each session gets its own isolated worktree, allowing Claude to work on different tasks without conflicts. The default location for worktrees is `~/.claude-worktrees` but this can be configured in your settings on the Claude desktop app.41Claude Code on desktop enables running multiple Claude Code sessions in the same repository using Git worktrees. Each session gets its own isolated worktree, allowing Claude to work on different tasks without conflicts. The default location for worktrees is `~/.claude-worktrees` but this can be configured in your settings on the Claude desktop app.

210/plugin marketplace add ./path/to/marketplace.json210/plugin marketplace add ./path/to/marketplace.json

211```211```

212 212 

213Or add a remote `marketplace.json` file via URL:213### Add from remote URLs

214 

215Add a remote `marketplace.json` file via URL:

214 216 

215```shell theme={null}217```shell theme={null}

216/plugin marketplace add https://example.com/marketplace.json218/plugin marketplace add https://example.com/marketplace.json

217```219```

218 220 

221<Note>

222 URL-based marketplaces have some limitations compared to Git-based marketplaces. If you encounter "path not found" errors when installing plugins, see [Troubleshooting](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).

223</Note>

224 

219## Install plugins225## Install plugins

220 226 

221Once you've added marketplaces, you can install plugins directly (installs to user scope by default):227Once you've added marketplaces, you can install plugins directly (installs to user scope by default):

502 502 

503### PreToolUse Input503### PreToolUse Input

504 504 

505The exact schema for `tool_input` depends on the tool.505The exact schema for `tool_input` depends on the tool. Here are examples for commonly hooked tools.

506 

507#### Bash tool

508 

509The Bash tool is the most commonly hooked tool for command validation:

510 

511```json theme={null}

512{

513 "session_id": "abc123",

514 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

515 "cwd": "/Users/...",

516 "permission_mode": "default",

517 "hook_event_name": "PreToolUse",

518 "tool_name": "Bash",

519 "tool_input": {

520 "command": "psql -c 'SELECT * FROM users'",

521 "description": "Query the users table",

522 "timeout": 120000

523 },

524 "tool_use_id": "toolu_01ABC123..."

525}

526```

527 

528| Field | Type | Description |

529| :------------------ | :------ | :-------------------------------------------- |

530| `command` | string | The shell command to execute |

531| `description` | string | Optional description of what the command does |

532| `timeout` | number | Optional timeout in milliseconds |

533| `run_in_background` | boolean | Whether to run the command in background |

534 

535#### Write tool

506 536 

507```json theme={null}537```json theme={null}

508{538{

520}550}

521```551```

522 552 

553| Field | Type | Description |

554| :---------- | :----- | :--------------------------------- |

555| `file_path` | string | Absolute path to the file to write |

556| `content` | string | Content to write to the file |

557 

558#### Edit tool

559 

560```json theme={null}

561{

562 "session_id": "abc123",

563 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

564 "cwd": "/Users/...",

565 "permission_mode": "default",

566 "hook_event_name": "PreToolUse",

567 "tool_name": "Edit",

568 "tool_input": {

569 "file_path": "/path/to/file.txt",

570 "old_string": "original text",

571 "new_string": "replacement text"

572 },

573 "tool_use_id": "toolu_01ABC123..."

574}

575```

576 

577| Field | Type | Description |

578| :------------ | :------ | :-------------------------------------------------- |

579| `file_path` | string | Absolute path to the file to edit |

580| `old_string` | string | Text to find and replace |

581| `new_string` | string | Replacement text |

582| `replace_all` | boolean | Whether to replace all occurrences (default: false) |

583 

584#### Read tool

585 

586```json theme={null}

587{

588 "session_id": "abc123",

589 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

590 "cwd": "/Users/...",

591 "permission_mode": "default",

592 "hook_event_name": "PreToolUse",

593 "tool_name": "Read",

594 "tool_input": {

595 "file_path": "/path/to/file.txt"

596 },

597 "tool_use_id": "toolu_01ABC123..."

598}

599```

600 

601| Field | Type | Description |

602| :---------- | :----- | :----------------------------------------- |

603| `file_path` | string | Absolute path to the file to read |

604| `offset` | number | Optional line number to start reading from |

605| `limit` | number | Optional number of lines to read |

606 

523### PostToolUse Input607### PostToolUse Input

524 608 

525The exact schema for `tool_input` and `tool_response` depends on the tool.609The exact schema for `tool_input` and `tool_response` depends on the tool.

61Claude Code uses a tiered permission system to balance power and safety:61Claude Code uses a tiered permission system to balance power and safety:

62 62 

63| Tool Type | Example | Approval Required | "Yes, don't ask again" Behavior |63| Tool Type | Example | Approval Required | "Yes, don't ask again" Behavior |

64| :---------------- | :------------------- | :---------------- | :-------------------------------------------- |64| :---------------- | :--------------- | :---------------- | :-------------------------------------------- |

65| Read-only | File reads, LS, Grep | No | N/A |65| Read-only | File reads, Grep | No | N/A |

66| Bash Commands | Shell execution | Yes | Permanently per project directory and command |66| Bash Commands | Shell execution | Yes | Permanently per project directory and command |

67| File Modification | Edit/write files | Yes | Until session end |67| File Modification | Edit/write files | Yes | Until session end |

68 68 

141 141 

142**Read & Edit**142**Read & Edit**

143 143 

144`Edit` rules apply to all built-in tools that edit files. Claude will make a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep, Glob, and LS.144`Edit` rules apply to all built-in tools that edit files. Claude will make a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob.

145 145 

146Read & Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:146Read & Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:

147 147 

103 103 

104```markdown theme={null}104```markdown theme={null}

105---105---

106paths: src/api/**/*.ts106paths:

107 - "src/api/**/*.ts"

107---108---

108 109 

109# API Development Rules110# API Development Rules

126| `*.md` | Markdown files in the project root |127| `*.md` | Markdown files in the project root |

127| `src/components/*.tsx` | React components in a specific directory |128| `src/components/*.tsx` | React components in a specific directory |

128 129 

129You can use braces to match multiple patterns efficiently:130You can specify multiple patterns:

130 131 

131```markdown theme={null}132```markdown theme={null}

132---133---

133paths: src/**/*.{ts,tsx}134paths:

135 - "src/**/*.ts"

136 - "lib/**/*.ts"

137 - "tests/**/*.test.ts"

134---138---

135 

136# TypeScript/React Rules

137```139```

138 140 

139This expands to match both `src/**/*.ts` and `src/**/*.tsx`. You can also combine multiple patterns with commas:141Brace expansion is supported for matching multiple extensions or directories:

140 142 

141```markdown theme={null}143```markdown theme={null}

142---144---

143paths: {src,lib}/**/*.ts, tests/**/*.test.ts145paths:

146 - "src/**/*.{ts,tsx}"

147 - "{src,lib}/**/*.ts"

144---148---

149 

150# TypeScript/React Rules

145```151```

146 152 

153This expands `src/**/*.{ts,tsx}` to match both `.ts` and `.tsx` files.

154 

147### Subdirectories155### Subdirectories

148 156 

149Rules can be organized into subdirectories for better structure:157Rules can be organized into subdirectories for better structure:

217}217}

218```218```

219 219 

220<Note>

221 Relative paths only work when users add your marketplace via Git (GitHub, GitLab, or git URL). If users add your marketplace via a direct URL to the `marketplace.json` file, relative paths will not resolve correctly. For URL-based distribution, use GitHub, npm, or git URL sources instead. See [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.

222</Note>

223 

220### GitHub repositories224### GitHub repositories

221 225 

222```json theme={null}226```json theme={null}

487* For GitHub sources, ensure repositories are public or you have access491* For GitHub sources, ensure repositories are public or you have access

488* Test plugin sources manually by cloning/downloading492* Test plugin sources manually by cloning/downloading

489 493 

494### Plugins with relative paths fail in URL-based marketplaces

495 

496**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.

497 

498**Cause**: URL-based marketplaces only download the `marketplace.json` file itself. They do not download plugin files from the server. Relative paths in the marketplace entry reference files on the remote server that were not downloaded.

499 

500**Solutions**:

501 

502* **Use external sources**: Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths:

503 ```json theme={null}

504 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

505 ```

506* **Use a Git-based marketplace**: Host your marketplace in a Git repository and add it with the git URL. Git-based marketplaces clone the entire repository, making relative paths work correctly.

507 

490### Files not found after installation508### Files not found after installation

491 509 

492**Symptoms**: Plugin installs but references to files fail, especially files outside the plugin directory510**Symptoms**: Plugin installs but references to files fail, especially files outside the plugin directory

518 518 

519Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)519Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)

520 520 

521<Note>

522 URL-based marketplaces only download the `marketplace.json` file. They do not download plugin files from the server. Plugins in URL-based marketplaces must use external sources (GitHub, npm, or git URLs) rather than relative paths. For plugins with relative paths, use a Git-based marketplace instead. See [Troubleshooting](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.

523</Note>

524 

5214. **NPM packages**:5254. **NPM packages**:

522 526 

523```json theme={null}527```json theme={null}

256 256 

257For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others.257For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others.

258 258 

259This example creates a subagent that only allows read-only database queries by validating commands before execution:259This example creates a subagent that only allows read-only database queries. The `PreToolUse` hook runs the script specified in `command` before each Bash command executes:

260 260 

261```yaml theme={null}261```yaml theme={null}

262---262---

272---272---

273```273```

274 274 

275The validation script inspects `$TOOL_INPUT` and exits with a non-zero code to block write operations. See [Define hooks for subagents](#define-hooks-for-subagents) for more hook configuration options.275Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](/en/hooks#exit-code-2-behavior) to block write operations:

276 

277```bash theme={null}

278#!/bin/bash

279# ./scripts/validate-readonly-query.sh

280 

281INPUT=$(cat)

282COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

283 

284# Block SQL write operations (case-insensitive)

285if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then

286 echo "Blocked: Only SELECT queries are allowed" >&2

287 exit 2

288fi

289 

290exit 0

291```

292 

293See [Hook input](/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/en/hooks#exit-codes) for how exit codes affect behavior.

276 294 

277#### Disable specific subagents295#### Disable specific subagents

278 296 

620Always ensure queries are efficient and cost-effective.638Always ensure queries are efficient and cost-effective.

621```639```

622 640 

641### Database query validator

642 

643A subagent that allows Bash access but validates commands to permit only read-only SQL queries. This example shows how to use `PreToolUse` hooks for conditional validation when you need finer control than the `tools` field provides.

644 

645```markdown theme={null}

646---

647name: db-reader

648description: Execute read-only database queries. Use when analyzing data or generating reports.

649tools: Bash

650hooks:

651 PreToolUse:

652 - matcher: "Bash"

653 hooks:

654 - type: command

655 command: "./scripts/validate-readonly-query.sh"

656---

657 

658You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

659 

660When asked to analyze data:

6611. Identify which tables contain the relevant data

6622. Write efficient SELECT queries with appropriate filters

6633. Present results clearly with context

664 

665You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

666```

667 

668Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](/en/hooks#exit-code-2-behavior) to block execution and returns an error message to Claude via stderr.

669 

670Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:

671 

672```bash theme={null}

673#!/bin/bash

674# Blocks SQL write operations, allows SELECT queries

675 

676# Read JSON input from stdin

677INPUT=$(cat)

678 

679# Extract the command field from tool_input using jq

680COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

681 

682if [ -z "$COMMAND" ]; then

683 exit 0

684fi

685 

686# Block write operations (case-insensitive)

687if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then

688 echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2

689 exit 2

690fi

691 

692exit 0

693```

694 

695Make the script executable:

696 

697```bash theme={null}

698chmod +x ./scripts/validate-readonly-query.sh

699```

700 

701The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](/en/hooks#exit-codes) for details on exit codes and [Hook input](/en/hooks#pretooluse-input) for the complete input schema.

702 

623## Next steps703## Next steps

624 704 

625Now that you understand subagents, explore these related features:705Now that you understand subagents, explore these related features: