> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Desktop Agent Setup

> Install Claude Code, connect to project-scoped MCP tools, and use it as a repo-first local coding agent.

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">Need help?</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>Ask in Discord</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>Open a GitHub issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>Support guide</span>
    </a>
  </div>
</div>

Claude Code is a terminal-based coding agent from Anthropic. In this workshop
track, use it as another local agent surface for reading a repo, editing files,
and running checks. The current official docs make three practical boundaries
worth keeping visible from the start:

* the repository root Claude Code should work inside
* the MCP tools and data sources you connect into that repo
* the reusable project instructions you keep in version control

## Install

Install Claude Code with the native installer:

```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
claude --version
```

On macOS, Homebrew is also supported:

```bash theme={null}
brew install --cask claude-code
```

On Windows, use the installer command from the official Claude Code docs for
PowerShell, CMD, or WinGet. For new workshop setups, prefer the native installer
or package-manager paths first. The current Anthropic docs still document npm as
a supported global package, but native install is the recommended starting point.

## Start In A Repository

Run Claude Code from the project you want it to inspect:

```bash theme={null}
cd path/to/your/repo
claude
```

Follow the authentication flow shown by the CLI.

## Connect Tools With MCP

Claude Code becomes more useful once the repo can reach the same systems your
team already uses. Anthropic's current MCP docs distinguish three scopes:

* `local`: the default server scope for the current project entry in
  `~/.claude.json`
* `project`: a team-shared `.mcp.json` file checked into the repository
* `user`: private cross-project servers stored in `~/.claude.json`

For a team-shared server, the current command shape is:

```bash theme={null}
claude mcp add --transport http --scope project <name> <url>
```

Claude Code writes the shared server into `.mcp.json` and prompts for approval
before using a project-scoped server from version control. Use `/mcp` when a
remote server needs OAuth login.

Prefer project scope for handbook workshops when the same tool boundary should
be visible to every contributor. Prefer user scope only for personal utilities
or credentials that should not live in the repository.

## Keep Project Instructions Explicit

Claude Code's current docs expect teams to keep repo-specific instructions in a
checked-in `CLAUDE.md`. Use it for coding standards, architecture decisions,
review checklists, and the "how we work here" rules that should stay close to
the repo rather than inside a one-off prompt.

This handbook uses the same idea for public learning material: keep workshop
steps, source maps, and contributor guidance as visible artifacts that can be
reviewed and updated.

## Basic Working Loop

Before starting a task:

```bash theme={null}
git status --short
```

Ask Claude Code to:

* inspect the existing repo structure before proposing changes
* keep edits aligned with the current issue or workshop step
* run the repo's validation command after changing files
* report changed files and any commands that failed
* name any MCP server, repo instruction file, or permission boundary it relied on

## Good Defaults

* Keep the terminal rooted at the repo you want to change.
* Do not paste secrets, bot tokens, or API keys into chat.
* Treat untrusted MCP servers and prompt-injection-prone data sources as a real
  security boundary, not as a convenience feature.
* Prefer small, reviewable changes during a workshop.
* Use the same validation checklist you would use for Codex work.

## Next Steps

* Compare this setup with [Codex Workshop](/workshops/codex)
  when you want a second local coding-agent surface.
* Read [Skills Introduction](/workshops/skills-introduction) after desktop setup
  is working and you want repeatable slash-command workflows.
* Use [Local Agent Tooling Source Map](/contributor-kit/reference-notes/local-agent-tooling-source-map)
  when you need the repo's terminology for runtimes, skills, roots, resources,
  and connectors.

## Reference

* [Claude Code overview](https://code.claude.com/docs/en/overview)
* [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
* [anthropics/claude-code](https://github.com/anthropics/claude-code)