Agents, sessions, and worktrees

Set the default agent, control teammates and cross-session messaging, and configure worktrees. See Subagents and Worktrees.

agent

Run the main thread as a named subagent, so Claude Code applies that subagent's system prompt, tool restrictions, and model to your session. The same key sets the default agent for sessions you dispatch from claude agents.

• Scope: Any file
• Type: string, the name of a built-in or custom agent
• Default: unset, so the main thread runs as Claude Code's default agent
• Per-session overrides: --agent takes precedence over this key for one session

{
  "agent": "code-reviewer"
}

A plugin's own settings.json can also supply this key; see Ship default settings with your plugin.

crossSessionInbound

Choose what this session does with messages arriving from your other Claude Code sessions. When no value applies, Claude Code decides per message from the two sessions' permission-mode classes. Requires Claude Code v2.1.224 or later.

• Scope: Any file. A project or local value applies only when it's stricter than the value managed settings, the --settings flag, or user settings give.
• Type: string, one of:
  • "accept": Claude Code delivers the message to Claude
  • "hold": Claude Code shows a notice for the message without delivering it
  • "refuse": Claude Code drops the message
• Default: unset, so Claude Code decides per message

{
  "crossSessionInbound": "hold"
}

Claude Code reads managed settings first, then the --settings flag, then user settings, and applies the first value found. refuse is stricter than hold, and hold is stricter than accept. When none of the trusted sources sets a value, a project or local hold or refuse still applies, replacing the per-message default. In sessions with cross-session messaging, this key appears in /config as Messages from your other sessions, which writes it to user settings; the row requires Claude Code v2.1.232 or later, and Claude Code hides it while the --settings flag or managed settings set the key.

Claude Code warns when you set a value it doesn't recognize. While that value is present in a user, project, local, or --settings file, Claude Code holds inbound messages, even when a source that takes precedence sets accept. A refuse that another source sets still applies. Fix or remove the value to clear the hold.

When the unrecognized value is in managed settings, Claude Code instead treats it as refuse until an administrator fixes it. Before v2.1.248, Claude Code ignored an unrecognized value without warning.

disableAgentView

Turn off background agents and agent view: claude agents, --bg, /background, and the on-demand supervisor. Set it in managed settings to enforce it for an organization.

• Scope: Any file
• Type: Boolean
  • true: Claude Code turns off claude agents, --bg, /background, and the on-demand supervisor
  • false: agent view is available
• Default: unset, so agent view is available
• Per-session overrides: CLAUDE_CODE_DISABLE_AGENT_VIEW turns agent view off for one session; whichever of the two turns it off, the other can't turn it back on

{
  "disableAgentView": true
}

isolatePeerMachines

Require your explicit approval before Claude's SendMessage reaches one of your sessions beyond this machine; see Require approval for cross-machine messages. The approval prompt appears even in bypassPermissions mode.

• Scope: Any file. A true from any scope applies, so a checked-in project file can turn the requirement on but not off.
• Type: Boolean
  • true: Claude Code asks for your approval before Claude's SendMessage reaches one of your sessions beyond this machine
  • false: cross-machine messages don't prompt
• Default: unset, so cross-machine messages don't prompt

{
  "isolatePeerMachines": true
}

The cross-machine SendMessage approval requires Claude Code v2.1.224 or later.

processWrapper

On macOS and Linux, place a corporate launcher command in front of the background processes Claude Code starts. Claude Code runs the launcher with its own command line appended, so the launcher must exec into Claude Code; see Run Claude Code behind a corporate launcher for the launcher contract. Requires Claude Code v2.1.210 or later.

• Scope: User or managed
• Type: string, the launcher command as an argv prefix, such as an absolute path with optional arguments
• Default: unset, so background processes start unwrapped
• Per-session overrides: CLAUDE_CODE_PROCESS_WRAPPER takes precedence over this key for one session

{
  "processWrapper": "/opt/corp/launcher --profile claude"
}

Claude Code ignores the launcher on Windows and starts every process unwrapped. Requires Claude Code v2.1.210 or later.

teammateMode

Choose where Claude Code shows agent team teammates: inside your main terminal pane, or in split panes when your terminal supports them. See Choose a display mode.

• Scope: Any file. Claude Code also reads a value left in ~/.claude.json by older versions.
• Type: string, one of:
  • "in-process": teammates run inside your main terminal pane
  • "auto": split panes when you're running inside tmux, or inside iTerm2 with it2 on your PATH or tmux installed; in-process otherwise
  • "tmux": split panes using tmux or iTerm2, detected from your terminal
  • "iterm2": iTerm2 native split panes through the it2 CLI, in Claude Code v2.1.186 or later
• Default: "in-process"
• Per-session overrides: --teammate-mode takes precedence over this key for one session

{
  "teammateMode": "auto"
}

Before v2.1.179, the default was auto. The iterm2 value requires Claude Code v2.1.186 or later.

<span id="worktree-settings" />

worktree

Configure how Claude Code creates and manages git worktrees for --worktree, the EnterWorktree tool, and isolated subagents and background sessions.

• Scope: Any file
• Type: object with baseRef, symlinkDirectories, sparsePaths, and bgIsolation
• Default: unset

This example branches new worktrees from your current HEAD and symlinks node_modules into each one:

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"]
  }
}

To copy gitignored files like .env into new worktrees, add a .worktreeinclude file to your project root instead of a setting.

worktree.baseRef