Synchronizing Claude Configuration

Learn how Sculptor syncs your Claude Code configuration 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

See the dedicated page for more details.

As a reminder:

  • User-scope commands live in ~/.claude/commands/.

  • Project-scope commands live in .claude/commands/ inside your project.

Sculptor syncs these directories into task containers so the same / commands you use in Claude Code are available to your agents.

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

Last updated