Agents and Teams
These variables control subagents, agent teams, background tasks, and workflows. They set limits, switch features on, and change how child agents behave. Several are experimental and may change without notice.
This page lists 80 variables. Switch rows take 1 or 0.
Example
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
claude
Claude Code does not start background tasks.
Variables
The table is sorted by name. See Environment Variables for what each column and badge means.
| Variable | Status | What it does | Values and default | Notes |
|---|---|---|---|---|
CLAUDE_ | Documented: An official docs page names this item. | Removes all built-in subagent types. The agent list is then empty. | On or off. It takes effect only in non-interactive mode | Non-interactive and SDK use. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Records when the agents view last auto-relaunched itself on the latest build. The view skips another auto relaunch for 6 hours. | A number. Claude Code sets it for the relaunched child. The view reads it with Number() | claude agents view. Not set from project env before trust |
CLAUDE_ | Documented: An official docs page names this item. | Sets the stall timeout for background subagents. | A number of milliseconds. Whole number from 1 to 2147483647. Without it, the default is 600000 when the stream watchdog is off. Otherwise the default is the stream idle timeout plus 300000, capped at 2147483647 | Subagents. Not set from project env before trust |
CLAUDE_ | Documented: An official docs page names this item. | Moves a subagent to the background after about two minutes. | On or off. When set, the code uses a 120000 ms delay. It also turns on the worker check-in schedule. Set it to 1 to allow auto background in -, including MCP auto background | Subagents and non-interactive mode. Project env can set it before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Marks a session that runs under the background daemon. A daemon session handles SIGHUP and color output in its own way. | Text. The value daemon turns on the daemon paths. Claude Code sets it when it starts a background session | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Holds the hash of the carried prompts file for a respawned background session. | Text. Claude Code reads it once, then unsets it. The code checks the hash against the carried prompts file | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets worktree isolation for a background session. | Text. Otherwise the job or the worktree. setting decides. It changes the prompt text | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Marks a respawn after a clear. The session then skips the -- not-found check and the agent prompt step. | On or off. Claude Code sets 1 on respawn attempts after the first when the session id changed | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Gives the path of the rendezvous socket for a background session. The session starts a server on it. | Text. Claude Code reads it once, deletes it, and removes the socket file | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Tells how a background session started. The value spare marks a pre-started spare. A telemetry event also records it. | Text. The code reports free text as other | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the time before the startup wedge watchdog fires for a background session. | A number of milliseconds, 45000 by default. Whole number, default 45000 when unset or 0 | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Holds the agent name of the main thread. Claude Code records it in the session registry file. | Text. Claude Code sets it from the -- flag | All sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Turns on subagent progress summaries when the host check in the startup code passes. | On or off. A host check gates the call. The name is part of a list of host-controlled names | SDK and host sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Marks that the agents view was relaunched. The view reads it once and deletes it. | On or off. Claude Code sets it to 1 in the env of the relaunched child | claude agents view. Not set from project env before trust |
CLAUDE_ | Documented: An official docs page names this item. | Controls whether a non-interactive session keeps a running status after a turn ends while background work runs. | On, off, or unset, on by default | Non-interactive sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets how a subagent token budget adds on top of the start budget. | Text. forks and all are valid. Any other value means none. Works with a feature flag | Subagents, gated by a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Forces the bound Slack thread mode on or off. Claude Code then treats posts from that thread as relayed human messages. | Off by default. Env value, else a feature flag, default off. Needs a prior platform check | Bound Slack thread sessions, gated by a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Adds extra tool names to the tools that coordinator mode keeps. A tool matches when its name starts with a listed entry. | A comma-separated list, empty by default. Needs coordinator mode | Coordinator mode |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Makes workers inherit the session model. The coordinator prompt and the Agent tool then say the model parameter is ignored. | On or off, off by default. CLAUDE_ has the same effect on the prompt | Coordinator mode |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Turns on coordinator mode, where the main session delegates work to workers. | On or off. Claude Code sets it to 1 or deletes it when the session mode switches | Disabled in some remote sessions unless CLAUDE_ is set |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | In coordinator mode, copies the pending nested memory triggers from the parent context into a worker context. | On or off, off by default. If the parent has none, the code skips the copy with a debug message | Coordinator mode |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Sets the cold start mode of the background service. Overrides the daemon setting. | Text. Else the setting, then a feature flag | Background service |
CLAUDE_ | Documented: An official docs page names this item. | Turns off background agents and agent view. Matches the disable setting. | On or off. The disable message names the variable | All sessions. Project env can set it before trust |
CLAUDE_ | Documented: An official docs page names this item. | Turns off background tasks, including run_, auto-backgrounding and Ctrl+B. | On or off. Another gate that disables background work also forces it. 1 also turns off MCP auto background | All sessions. Project env can set it before trust |
CLAUDE_ | Documented: An official docs page names this item. | Stops a background session from handing its running background work to the next process. | On or off. Checked in the exit handoff code of background sessions | Background sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Makes the background session pty host start from the running executable instead of a stable path lookup. | On or off. The code removes it from the child environment. It applies only on macOS | MacOS background sessions |
CLAUDE_ | Documented: An official docs page names this item. | Turns off scheduled tasks and the cron tools. | On or off. Gates a feature flag check | All sessions. Project env can set it before trust |
CLAUDE_ | Documented: An official docs page names this item. | Turns off the built-in Explore and Plan subagents. | On or off. Claude Code reads it once and keeps the result for the session | All sessions. Project env can set it before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Turns off the quiet wait of a headless session that waits only for background shell tasks. The session then checks again every 100 ms. Added in 2.. | On or off, off by default. Without it the session waits up to 1 second and wakes on a queue, store, or state change | Headless sessions with background shell tasks |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Appends the append option text to the system prompt of every subagent. | On or off, off by default. Claude Code sets it to 1 when you use -- or the - flag. The variable alone changes nothing. A probe saw the flag text as the last lines of the subagent prompt (Probes) | -- mode only |
CLAUDE_ | Documented: An official docs page names this item. | Selects the Task tools. Set to 0 to use Todo instead. | On, off, or unset, on by default. Only false turns it off | All sessions. Project env can set it before trust |
CLAUDE_ | Documented: An official docs page names this item. | Gives the task tools to every model, not only the default list. | On or off, off by default. Only true counts | All sessions |
CLAUDE_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate Experimental: The program or the official docs call this experimental or beta. | Turns on agent teams. The -- flag does the same. | On or off, off by default. Also needs a feature flag, default on | All sessions. Project env can set it before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate Experimental: The program or the official docs call this experimental or beta. | Turns on observer agents, which use the observer field of agent definitions. | On or off, off by default. Needs a feature flag, default on. Fan-out needs a feature flag. A probe confirmed that without this variable Claude Code ignores the observer field (Probes) | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Shows past sessions in the fleet agent view. | The code checks it against true with a second env accessor. Otherwise a feature flag decides | Agent view |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Turns on the simple fleet view of the agent view. | On or off, off by default. Else a feature flag | Agent view |
CLAUDE_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Controls fork mode for subagents. 0 turns it off everywhere and 1 forces it on, also in -. | On, off, or unset. Org setting fork wins. In non-interactive mode a true feature flag turns it off unless this is 1 | All sessions. Project env can set it before trust |
CLAUDE_ | Documented: An official docs page names this item. | Emits subagent text and thinking blocks in stream-json output, like --. | On or off, off by default. Either this variable or the flag turns it on | claude - with stream-json |
CLAUDE_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets how long background work can defer a goal before Claude is asked to check on it. | A number, on by default. Whole number from 0 to 10080, plain digits. 0 turns it off | Goal mode |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Turns cross-session messaging on or off. | Text, on by default. Unset uses a feature flag, default on. Org setting messaging wins | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Lowers the effort of a subagent that sets none. A level name sets that level and a negative integer steps down the effort list. | Text. Falls back to a feature flag. Applies only when it is lower than the subagent effort and that is not low | All sessions, subagents |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Lets a local host declare that a run is one of its own scheduled runs, so it can name the run kind. | On or off. The code keeps the run kind only when it is 1 to 32 lowercase letters or underscores and the host started the process with 1 | Host apps (desktop scheduler) |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Turns the keepalive of / on or off. At keepalive, the loop ends when the model declines to reschedule twice. | On, off, or unset, on by default. Unset follows a feature flag, default on | All sessions, / |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Selects the persistent autonomous loop preamble instead of the normal one. | On or off, off by default | All sessions, / |
CLAUDE_ | Documented: An official docs page names this item. | Caps how many subagents run at once in a session. | A number, 20 by default. Whole number min 1, digits only | All sessions, Agent tool |
CLAUDE_ | Documented: An official docs page names this item. | Sets how many subagent layers may sit below the main conversation. | A number. Whole number min 1, digits only. Unset reads a feature flag, whose fallback is 3 | All sessions, Agent tool |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | When set, Claude Code skips one extra block that it adds to the subagent system prompt. A print-mode probe showed no visible effect (Probes). | On or off. Unset adds the block, except for isolated contexts | Subagents |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets plan for a teammate when no team context gives it. A true value makes the teammate plan first. | On or off. Project settings may set it before trust (safe_) | Teammates and swarm sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Overrides the agent count of a plan v2 helper. Without it the count is 3 for max 20x, team, and enterprise plans, otherwise 1. | A number. Whole number from 1 to 10. Claude Code ignores other values | Plan mode |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Overrides the explore agent count of a plan v2 helper. Default is 3. | A number. Whole number from 1 to 10. Claude Code ignores other values | Plan mode |
CLAUDE_ | Documented: An official docs page names this item. | Sets the idle wait ceiling for background work after the last turn in - mode. | A number of milliseconds. Whole number in ms of 0 or more. Docs default is 600000 | Non-interactive - mode |
CLAUDE_ | Documented: An official docs page names this item. | Starts the processes that Claude Code launches from its own binary through a corporate launcher. | Text. Argv prefix string | Background service and agent view |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Forces the subagent final-report handback tool on or off in auto mode. The tool tells a subagent to deliver its report through it. | Read directly from the environment. When unset, a feature flag decides with a default of true | Subagents in auto mode. gated by a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Tells a child session that a person attends its parent session. Claude Code stores it as the spawned-by-attended flag. | On, off, or unset. The code removes it from the env that it passes to some child processes | Child sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Forces a feature flag subagent budget note on or off. The note tells a subagent its token budget. | On, off, or unset. The note shows only when a budget value exists | Subagents. gated by a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Overrides the wording of the subagent budget note. The code replaces the token {N} with the budget number. | Text. Claude Code ignores an empty or blank value. A feature flag is the fallback | Subagents. Needs the budget note on |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Forces on a feature flag behavior for subagent requests. A print-mode probe showed no visible effect (Probes). | On or off, off by default. Applies only on a first-party provider path. The flag is the fallback and defaults to off | Subagents. gated by a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Turns the subagent config check warning on with 1 or off with 0. The check looks at CLAUDE., skills, and agents for subagents. | On, off, or unset. When unset, a feature flag config decides | Subagents. gated by a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Adds an "Earlier in this session" row to the background tasks dialog. It lists the subagents that the session recorded, as a tree. | On or off. Without it a feature flag decides, off by default. Since 2. | Interactive UI |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Marks a subagent to start with a system prompt snapshot. Claude Code sets the snapshot flag on the subagent options. | On or off. It does not apply when another local condition holds. The effect of the snapshot was not read further | Subagents |
CLAUDE_ | Documented: An official docs page names this item. | Sets the ID of the task list that the Task tools use, so several sessions share one list. | Text. Wins over team name and session id. When set, Claude Code skips the carry-over of tasks to a forked session | Sessions with Task tools |
CLAUDE_ | Documented: An official docs page names this item. | Sets how long a non-interactive session waits at exit for its agent team to shut down. | A number of milliseconds, 10000 by default | Non-interactive sessions with agent teams |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Turns on the WebFetch agent path. Env wins over a feature flag. | On, off, or unset, off by default. Off when CLAUDE_ or CLAUDE_ is set. When on, a web- agent type exists and the main session loses its own Web tool (Probes) | Default mode sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Tells the model not to start subagents unless the user asks. It works only in Cowork sessions. | Any non-empty value. Off by default. Since 2. | Set by a host app. On the Pro plan the program adds the same rule without it |
CLAUDE_ | Documented: An official docs page names this item. | Sets waits between reminders to check on running background subagents. Needs CLAUDE_. Docs only. The read site was not re-checked. | A comma-separated list. Unset gives no reminders | Background subagents |
CLAUDE_ | Documented: An official docs page names this item. | Sets how many agents one workflow run executes at once. | Plain digits 1 to 256. Claude Code logs the gate value when it is set | Workflows |
CLAUDE_ | Documented: An official docs page names this item. | Sets how long a workflow agent waits for a same-prefix sibling before its first request. | A number of milliseconds. Integer, 0 or more. Claude Code forces it to 0 when DISABLE_ is set | Workflows |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. A feature flag or server gate decides by default. This variable overrides it | Adds a provenance note to workflow prompts, such as that no user is present in a trigger run. Env wins over a feature flag. | On or off, on by default | Workflows |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the agent count where the workflow size warning fires. | A number. Integer, at least 1. Order: env, workflow, a feature flag, built-in default | Workflows |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the token count where the workflow size warning fires. | A number. Integer, at least 1. Order: env, a feature flag, built-in default | Workflows |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | 0 or false turns off workflows. 1 makes them available if the feature flag allows it. | On, off, or unset. Unset means the flag decides, and default-on is off for the pro plan | All sessions |
CLAUDE_ | Documented: An official docs page names this item. | Stops in-flight background work when you move a session to the background. Claude Code does not carry that work over. | On or off. Any true value turns off adoption | Background sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets how often the PTY host pings its clients. The host drops a client that misses 3 pings. | A number of milliseconds | - |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Marks a PTY host started in exec mode. The host reads it, deletes it, and then removes the CLAUDE_ file. | - | - |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | When set to 1, the macOS re-exec skips the stable binary path and uses the current executable. | A path | - |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the interval of the orphan watchdog of the PTY host. After 30 checks with a new parent and no client, the host stops its child. | A number of milliseconds | - |
SELF_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets the idle time in ms before the self-hosted runner releases a session. | Text. The -- flag writes it as minutes times 60000. Help text says 0 disables | claude self- only |
SELF_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets how long the runner waits for the Claude process to exit after a session ends, before it force-kills it. | A number of milliseconds. The -- flag writes it as seconds times 1000 and needs a positive value. The post-session hook runs after | claude self- only |
SELF_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets the startup timeout in ms for a runner session. | A number of milliseconds. Default is 900000 when unset or empty. A value of 0 or a bad number gives 0, and the maximum is 2147483647 | claude self- only |
SELF_ | Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Controls whether the runner trusts the session workspace. The help text says 0 turns it off. | On or off. Parsed as a boolean by a runner helper with a default. Help text: SELF_ disables | claude self- only |
How It Works
A subagent is a child session with its own prompt and tools. Some variables here pass to child sessions. Others change only the parent. The Notes column says which when the code shows it.
Related Pages
- Environment Variables: how Claude Code reads variables and which value wins.
- Subagents
- Undocumented Items: every item that only the program shows.
Source: the program (variable names found in the 2.1.312 binary) and the Environment Variables page of the official docs.