claude-code - 💡(How to fix) Fix [Feature Request] Add CLAUDE_AGENT_NAME environment variable for multi-agent workflows [1 comments, 2 participants]

Bug Description --agent/--name flag does not expose agent name as an environment variable

Problem

When launching Claude Code with claude --agent devex or claude --name devex, the spawned process does not expose the agent name to its shell environment. There is no CLAUDE_AGENT_NAME, CLAUDE_NAME, or equivalent variable that downstream tooling can read.

This is a hard blocker for any workflow that runs multiple agents concurrently and needs to tell them apart from outside the Claude Code process — terminal tab titles, shell prompts, status lines, tmux pane labels, telemetry tagging, per-agent log routing, and so on.

Steps to reproduce

1. Launch multiple Claude Code sessions with different agent names: claude --agent captain claude --agent devex claude --agent iscp
2. Inside each session, inspect the environment: env | grep -i agent env | grep -i claude
3. Inspect the terminal tab/title bar.

Observed: No environment variable references the agent name. All terminal tabs display a generic "agent" label. $CLAUDE_AGENT_NAME is unset.

Expected: An environment variable — CLAUDE_AGENT_NAME, or similar — is set in the child process, containing the name passed to --agent / --name. Terminal integration features would use this to populate the tab title automatically.

Why this matters

• Multi-agent development is the use case Claude Code is being used for. Many teams (including ours) run captain + multiple worktree agents simultaneously. Differentiating them outside the Claude Code process is currently impossible.
• Terminal ergonomics matter. Humans looking at a row of terminal tabs need to see which one is doing what. Generic "agent" labels everywhere is a paper cut that becomes painful fast.
• Tool integration matters. Shell prompts, tmux status lines, monitoring tools, and IDE integrations all want to know "which agent is this?" and there's no answer.
• Programmatic agent-aware scripting is blocked. Shell scripts that want to behave differently per agent (e.g., "if this is captain, use the admin path; otherwise, use the worktree path") have no reliable way to detect the agent context.

Requested behavior

Minimal change: Set CLAUDE_AGENT_NAME (or a namespace-qualified variant like CLAUDE_CODE_AGENT_NAME) in the spawned process's environment when --agent / --name is passed. The variable should be readable from shell, from tools invoked via Bash, and from hooks.

Nice to have:

• Also set CLAUDE_SESSION_ID so concurrent sessions can be distinguished programmatically
• Document the full set of environment variables Claude Code exposes to child processes in the public docs
• Consider a structured session metadata file (e.g., $XDG_RUNTIME_DIR/claude-code/{session-id}.json) for richer integration

Workaround

We maintain a project-local .agency-agent file that records the expected agent name per worktree, and our agent-identity tool reads this file to produce a fallback identity. This works for us because we control the worktree directory layout, but it's not a general solution.

Reporter

• Name: Jordan Dea-Mattson
• GitHub: @jordandm (the-agency-ai), @jordan-of (OrdinaryFolk)
• Email: [email protected], [email protected]
• Framework: https://github.com/the-agency-ai/the-agency
• Claude Code version: (fill at submission — claude --version)

Related

• Session identity broken for worktree workflows (#46853) — the session-level companion to this process-level request
• Agent permission UX (#46855) — another aspect of the multi-agent workflow gap
• Filed as part of the 2026-04-11/12 feedback batch

Environment Info

• Platform: darwin
• Terminal: ghostty
• Version: 2.1.101
• Feedback ID: 0894552a-1614-4553-9eef-0acf597598e5

Errors

[{"error":"Error: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"Output blocked by content filtering policy\"},\"request_id\":\"req_011CZwHyHAGs3JxBGJEgkNGQ\"}\n    at generate (/$bunfs/root/src/entrypoints/cli.js:11:53430)\n    at makeRequest (/$bunfs/root/src/entrypoints/cli.js:50:4943)\n    at processTicksAndRejections (native:7:39)","timestamp":"2026-04-11T03:43:27.528Z"},{"error":"Error: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"Output blocked by content filtering policy\"},\"request_id\":\"req_011CZwJQ4AsrsX6YgSuRMn2i\"}\n    at generate (/$bunfs/root/src/entrypoints/cli.js:11:53430)\n    at makeRequest (/$bunfs/root/src/entrypoints/cli.js:50:4943)\n    at processTicksAndRejections (native:7:39)","timestamp":"2026-04-11T03:49:07.527Z"},{"error":"Error: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"Output blocked by content filtering policy\"},\"request_id\":\"req_011CZwJZoTsSiAuQDu2k85ey\"}\n …

Note: Content was truncated.