[FEATURE] Claude code agent selector feature request

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature request

Expose the existing --agent session mode as a GUI agent selector in the Claude Code VS Code extension and the Claude Desktop app's Code tab — not just the CLI.

For example, when starting a new conversation:

New session

Agent:
○ Default
○ Feature Planner
○ Architect
○ Code Implementation
○ Marketing

The selected agent becomes the persistent root of that session — its system prompt, tool restrictions, and model — for the session's entire lifetime, including across --resume/sidebar-reopen. This is not a request for a new capability; the CLI already does exactly this via claude --agent <name> and .claude/agents/*.md. The request is to surface that existing primitive in both GUI surfaces.

Current state (what already works)

• .claude/agents/<name>.md (project scope) and ~/.claude/agents/<name>.md (user scope) define an agent: YAML frontmatter for name, description, tools, model, plus a body that becomes the system prompt.
• claude --agent <name> starts a session where the main thread itself takes on that agent's prompt, tool restrictions, and model — distinct from subagent delegation, where a generic parent spawns a worker and absorbs its output.
• "agent": "<name>" in .claude/settings.json sets a project default; the CLI flag overrides it.
• None of this is exposed in the VS Code extension's command menu (/) or in the Desktop app's session-start controls. The Desktop docs' own "CLI flag equivalents" table lists a GUI equivalent for --model, --resume, --permission-mode, --dangerously-skip-permissions, --add-dir, --verbose, and env vars — --agent has no row, and no equivalent exists in the VS Code extension either.

Current limitation

Subagents (Task tool delegation) and the model/permission-mode selectors already in both GUIs solve a different problem than this request. Specifically:

• A subagent is a delegated worker with its own context; its output is returned or summarized to the parent, and the user keeps talking to the generic parent session. It's built for bounded side-quests, not for a session that is a role for its full lifetime.
• The model dropdown changes which model answers, but not the system prompt or tool restrictions — an Architect-role session and a Code-Implementation-role session need different tools and different behavioral contracts, not just different models.
• Custom subagent definitions exist for use inside a session, but there's no way to make one the root of a new top-level GUI session the way --agent does in the terminal.

Why this matters

Some workflows split into genuinely distinct, long-lived roles rather than one generic assistant handling everything ad hoc — e.g., a planning role that owns roadmap/feature decisions and needs to stay pinned and resumed over weeks or months, a scoping/architecture role scoped to one phase at a time, and a narrowly-scoped code-implementation role restricted from touching planning artifacts. Each role plausibly needs:

• a different system prompt (its own contract/boundaries),
• different tool access (e.g., a planning role might be read-only; an implementation role needs full file + shell access),
• a different model (heavier reasoning model for planning/architecture, a cheaper model for mechanical execution),
• its own persistent, resumable conversation — not a sub-thread of a generic parent.

The need isn't limited to technical roles, either. A Marketing agent working the same repo/workspace might need an almost entirely different profile from any of the technical roles above: web research and browsing tools instead of shell/file-edit access, connectors for docs or communication tools rather than a compiler or build system, a system prompt built around brand voice and positioning rather than architecture contracts, and a permission model that never touches source code at all. Forcing a role this different to either (a) live as a subagent of a generic technical parent, or (b) share the same GUI session config as the coding roles, doesn't fit — it needs to be just as first-class and independently selectable as the technical roles, with a completely different tool/model/permission profile.

--agent already models this correctly in the CLI. The only gap is that switching roles currently requires leaving whichever GUI surface you're in and going to a terminal, which is exactly the friction these GUI surfaces exist to remove.

Requested behavior

• Both the VS Code extension and the Desktop app's Code tab show an agent selector when starting a new session, populated from the same .claude/agents/ (project) and ~/.claude/agents/ (user) files the CLI already reads — no new agent-definition format needed.
• The selected agent is the root of the session (prompt, tools, model) for its full lifetime, including through session history / resume in either surface.
• The active agent is visibly labeled in the session (sidebar entry, tab title, or header) so it's clear which role a given open conversation is running as.
• Setting "agent": "<name>" in .claude/settings.json continues to work as a default, but a per-session override in the GUI takes precedence for that session, mirroring how --agent already overrides the settings default in the CLI.
• A rooted custom agent can still spawn subagents where its config allows, without itself being treated as one.

Suggested acceptance criteria

• [ ] Agent selector available when starting a new session in the VS Code extension
• [ ] Agent selector available when starting a new session in the Desktop app's Code tab
• [ ] Selector is populated from existing .claude/agents/*.md (project) and ~/.claude/agents/*.md (user) definitions — same files the CLI reads today
• [ ] Selected agent persists as session root across resume/history in both surfaces
• [ ] Active agent is visibly identified in the session UI
• [ ] Per-session GUI selection overrides the agent key in .claude/settings.json, consistent with existing CLI flag-over-setting precedence
• [ ] Behavior matches the CLI's --agent semantics (main thread takes the role; not subagent delegation)

Why this is a small ask relative to the payoff

Unlike a request for a brand-new subsystem, every underlying piece already exists and works in the CLI today: the agent-definition file format, the settings key, and the session-root semantics. This request is scoped entirely to exposing that existing, working primitive as a selector in two GUI surfaces that already read the same config files and already run the same underlying engine.

Proposed Solution

When starting a new session in the VS Code extension or the Desktop app's Code tab, show a simple dropdown — next to the existing model/project pickers — listing the custom agents found in .claude/agents/ (project) and ~/.claude/agents/ (user). These are the same agent files --agent already reads in the CLI.

How it would work:

1. Click "New session."
2. A dropdown shows the available agents: Default, Feature Planner, Architect, Code Implementation, Marketing, etc.
3. Pick one, e.g. "Architect."
4. The session starts running as that agent right away: its system prompt, its tool restrictions, and its model/reasoning effort — all pulled from the agent's own definition file. No flags, no editing settings.json, no terminal.
5. The session stays labeled with that agent (sidebar entry, tab title) for its whole lifetime, including after closing and resuming — it doesn't quietly fall back to the default agent.
6. The existing model and reasoning/effort dropdowns still work exactly as they do today, on top of this. If I want to override the agent's default for just this session — e.g. drop to a cheaper model, or bump reasoning effort up for a harder phase — I use those same dropdowns. That override applies to the session only; it doesn't change the saved agent file.

In short: the agent file sets the default model and reasoning effort for that role, and the existing dropdowns become the per-session override — the same one-click simplicity as picking a model today, just applied to picking an agent first.

Alternative Solutions

The only current workaround is claude --agent <name> in the terminal CLI. This works functionally — the session correctly takes on the agent's prompt, tools, and model — but it means giving up the GUI entirely for that session: no side-by-side diff viewer, no file/plan/browser panes, no clickable diff review, no sidebar session list, none of the reasons I'd choose the VS Code extension or Desktop app in the first place.

I also considered:

Setting a default via "agent": "<name>" in .claude/settings.json — this works, but it's a static, file-level default. Switching roles means editing that file every time, and it doesn't let me pick a different agent per session the way a dropdown would.
Using subagents (the Task tool) instead of root agents — doesn't fit, since a subagent is a delegated worker whose output returns to a generic parent session. I'd still be talking to the generic default agent, not directly to the specialized role, and I'd lose the role's own persistent, independently-resumable conversation history.
VS Code's native Copilot Chat "Custom Agents" feature, which does have a GUI dropdown and can even read the same .claude/agents/ files — but this routes through a GitHub Copilot subscription rather than my Claude subscription.

So in practice, the only way to get a properly-scoped agent session today is to drop out of the GUI and work entirely in the terminal for that session, which isn't a real substitute for the extension/desktop app experience.

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

1. I'm working on a large C++ project using a structured multi-role workflow — a Feature Planner (roadmap/phase decisions), an Architect (per-phase implementation plans), a Code Implementation role (executes one approved step at a time), and potentially non-coding roles like Marketing (brand voice, web research, no code access) — each needing its own system prompt, tools, and model.
2. I need to switch between these roles without losing their distinct configs, and without being stuck in a terminal — right now claude --agent <name> gives me exactly this, but only in the CLI; the VS Code extension and Desktop app have no agent selector, so I can't pick up a role-specific session from either GUI.
3. With this feature, I could open the VS Code extension or Desktop app, pick "Architect" or "Code Implementation" (or "Marketing") from a session-start selector backed by my existing .claude/agents/*.md files, and have that session run with the right prompt, tools, and model for its entire lifetime — including on resume — all without touching a terminal.
4. This would save me time because I currently have to leave my GUI of choice and drop into the CLI any time I want a properly-scoped role instead of the default agent, which breaks my flow and makes the GUI surfaces unusable for the exact multi-role workflow they're otherwise well suited for.

Additional Context

_No response_