Claude Code Configuration

Learn how Sculptor syncs your Claude Code configuration, including slash commands, subagents, MCP servers, and settings into agent containers.

Overview

Syncing your Claude Code configuration ensures that the behavior you experience locally (slash commands, subagents, MCP access, settings) is reproduced inside Sculptor's isolated agent containers.

Claude Code can be configured in various ways. We continuously work on expanding the extent of your local Claude Code configuration that you can reuse when working with Claude-based Sculptor agents.

We currently automatically synchronize the following pieces of Claude Code configuration:

• Custom slash commands

• Subagents

• MCP server definitions and auth

• settings.json

You can disable this using the Synchronize Claude Code Configuration experimental toggle in the settings page.

Sculptor settings page showing the "Synchronize Claude Code Configuration" toggle

Claude Code configuration is not stored in a single file. Some items (like settings) live in JSON files, while slash commands, subagents, and MCP servers live in their own directories. Sculptor syncs each of these according to where Claude expects them.

Where configuration lives

Type	Location	Scope	Synchronized into agent containers?
Slash commands	~/.claude/commands/	User	Yes
Slash commands	.claude/commands/	Project	Yes
Subagents	~/.claude/agents/	User	Yes
Subagents	.claude/agents/	Project	Yes
MCP servers	~/.claude.json	User	Yes
MCP servers	~/.claude.json	Local	Yes
MCP servers	.mcp.json	Project	Yes
Settings	~/.claude/settings.json	User	Yes
Settings	.claude/settings.json	Project	Yes
Local overrides	.claude/settings.local.json	Local	Yes

---

Custom Slash Commands

What are slash commands?

Claude supports custom slash commands defined as Markdown files. Each .md file represents a command you can trigger with / inside Sculptor.

Typical locations:

• Global commands: ~/.claude/commands/

• Project commands: <project>/.claude/commands/

Examples:

• review.md – reviews uncommitted changes for bugs or style

• deploy.md – runs deployment sequences

• test.md – runs tests or linters

Tip: Slash commands act as named reusable prompts. They're great for common checks like reviews, testing, or security scans.

How slash command syncing works

When slash command syncing is enabled, Sculptor:

• Reads global commands from ~/.claude/commands/*

• Reads project commands from <project>/.claude/commands/*

• Syncs them into each agent's container

• Validates that the commands you call actually exist

When you type / inside an agent, Sculptor shows a menu of all synced commands.

Slash command menu

Using slash commands in an agent

Inside an agent task:

1. Focus the message input

2. Type /

3. Sculptor shows available commands from:

   • ~/.claude/commands

   • <project>/.claude/commands

Choose a command like /review or /test.

Sculptor runs the command inside the agent's isolated container and streams results back into the UI.

Command update behavior

When you add, edit, or delete a .md command file, Sculptor updates the slash command list based on these rules:

Global commands

• Update immediately

• Old commands disappear instantly

• New commands become available right away

Project commands

• Update when the project is synced (Pairing Mode, git push, etc.)

• Active containers update at the next project sync event

• New containers always start with the latest commands

Note: If your project uses Git, you must sync your repo state (push, pull, or Pairing Mode) before Sculptor updates active containers.

---

Subagents

Your locally defined subagents can live in two different places:

• In ~/.claude/agents/. This is called user scope, and these agents will be synchronized into all your active task containers automatically, in near real-time.

• In .claude/agents/ inside your project. This is called project scope; these agents are typically tracked in git together with the rest of your repository and are synchronized together with it.

You can learn more about the purpose of subagents here.

---

MCP Server Definitions and Auth

In Claude Code, you can use the /mcp slash command to connect your agent to tools provided by various MCP servers.

We synchronize local-scope and user-scope MCP server configuration into your task containers automatically every time you send a message to your agent.

As part of this, we also make sure that agents inside containers can still access the MCP servers even if they need authentication (provided you previously authenticated locally).

In other words, you can for example:

1. Add the Sentry MCP server: claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

2. Authenticate to Sentry by using the /mcp command.

3. Then ask your Sculptor agents to do tasks that require them to access the Sentry MCP server.

Project-scope MCP server configuration is synchronized together with the rest of the project's repository.

---

Settings.json

We also synchronize your settings.json files:

• Your local project settings (.claude/settings.local.json) and user settings (~/.claude/settings.json) are synchronized into all your active task containers automatically, in near real-time.

• Your shared project settings (.claude/settings.json) are typically git-tracked and are synchronized together with the rest of your project repository.

Only some of the settings are meaningful in the context of Sculptor, but you can use them, for example, to set up hooks to automatically run formatters (potentially in conjunction with custom dependencies installation).

Known limitations

• Permissions defined in the settings are not respected. This is due to the nature of Sculptor's approach to sandboxed parallel agents.

• Git-ignoring ~/.claude/settings.json or un-ignoring .claude/settings.local.json can result in strange synchronization behavior.

• Managed settings are not synchronized at the moment.

• Hooks that rely on tools you configured only on your local machine may not work correctly inside agent containers.

• Typically, only public servers will be accessible from Sculptor containers. If you have any locally running MCP servers, you'll need to find a way of exposing them inside the containers.

• Sculptor refreshes MCP authentication tokens by invoking your local claude CLI. Because of this, you must have the claude binary available in your system PATH. If it isn't, token refreshes may fail and MCP servers inside agent containers may stop working.

• Settings that could disrupt the typical workflow in Sculptor may be omitted (such as apiKeyHelper).

---

Summary

Claude Code configuration syncing allows you to:

• Use custom slash commands for reusable prompts and workflows

• Share project-specific commands and subagents via Git

• Access MCP servers from within agent containers

• Apply your local settings to all agents automatically

Global configurations sync in near real-time, while project configurations sync when you update your repository state.