You Don’t Have to Abandon Claude DesktopThe Practical Case for Claude Code CLI, Subagents, and Agent Teams

1. The conclusion: choose the interface that matches the shape of the work

There is no need to declare either Claude Desktop or the Claude Code CLI the superior product. The practical conclusion in September 2026 is simpler: use Desktop when the work depends on seeing, comparing, and handing over images or PDFs; use the CLI when the work depends on shell-native automation or Agent Teams.

“CLI” in this article does not mean a separate API-only contract or a custom Agent SDK application. It means opening a terminal and running claude with Claude Code under an ordinary Claude Pro or Max subscription. Anthropic’s documentation also supports Team and Enterprise subscriptions, while Claude Console API billing is a separate authentication route.^[1][2]

I spent a long time preferring Desktop because it was more convenient, without seriously investigating what the CLI changed. Images can be dragged into a conversation. PDFs can be opened in place. Artifacts and previews let you inspect a result while discussing it. In the Code tab, chat, diffs, files, a terminal, and a browser can be arranged as panes, and multiple sessions can be managed from one interface. This is not merely a beginner-friendly GUI. It is a development environment with a strong visual-review surface.^[3][4]

At the same time, the claim that “Desktop cannot run subagents” or that all multi-agent work is exclusive to the terminal is no longer accurate. The Desktop Code tab has a subagent pane and runs Subagents and dynamic workflows on the same Claude Code engine. The feature that remains CLI-only is Agent Teams: coordinated sessions with a shared task list and direct inter-agent communication. Anthropic’s current Desktop comparison states this boundary explicitly.^[3]

The useful question is therefore not which camp to join. It is whether the current job is primarily a sequence of human visual decisions, or a system of operating-system processes, logs, credentials, and independent tasks that need coordination. Even if you use only one interface, understanding what you gain and give up turns that habit into an engineering decision rather than loyalty to a tool.

2. Do not underestimate Desktop: visibility is part of quality

Desktop’s value is not that it has buttons. Its value is that different kinds of evidence can occupy the same field of view.

For a design change, you can place the conversation on the left, a browser preview on the right, and the diff below. Images and PDFs arrive by drag and drop rather than by explaining paths. In the general Chat surface, Artifacts separate a draft, chart, or interface from the surrounding conversation. In the Code tab, file editing, visual diffs, live application previews, and side chats can be combined. When visual inspection is the bottleneck, that integration directly reduces feedback loops.^[3][4]

Desktop can also run parallel sessions and isolate their changes in Git worktrees. The picture of “one window, therefore only a one-to-one turn-taking conversation” is outdated. Desktop already supports multiple independent sessions, and a session can itself use Subagents.

Desktop is strongest when judgment depends on comparing things visually. For image, PDF, diff, and live-screen work, the GUI becomes part of the review system.

Window and tab management alone, however, is not a decisive Desktop advantage. iTerm2 provides tabs, horizontal and vertical panes, moving a tab into another window, and saved window arrangements. Add tmux, and a session can survive an SSH disconnect. A CLI user can keep research, implementation, tests, and logs in separate panes and detach one onto another display.^[5]

The interface-management gap can therefore shrink to a matter of preference and task type. The decisive differences appear in the data flowing through those windows and in the communication structure among agents.

3. The CLI is not beside your local environment; it becomes part of its plumbing

Desktop’s Code tab can read local files and run commands in an integrated terminal. But a Desktop process does not always inherit the complete shell environment. On macOS, Anthropic says an app launched from Finder or the Dock extracts PATH and a fixed set of Claude Code variables from the shell profile, while other exported variables are not automatically collected. Those values must be added through Desktop’s local-environment editor.^[6]

The CLI starts from the current directory and the exported environment of the terminal in which the developer is already working. An AWS SSO session, AWS_PROFILE, the active Docker context, the selected language runtime, and internal commands on PATH begin at the same entrance as the human workflow. Authentication failures do not magically disappear, but one whole class of “the app launched from Finder never received the variable” mismatches becomes less likely.

Aliases require a caveat. Exported environment variables pass to child processes, while a shell alias normally does not. An alias may be available if Claude Code’s shell loads the same startup configuration, but it is not a reliable interface. If a shortcut is essential to the workflow, turn it into a small executable on PATH or a consistently loaded shell function. Claude Code also runs Bash tool commands in separate processes, so an export performed in one tool call does not automatically persist into the next. Anthropic documents CLAUDE_ENV_FILE and SessionStart hooks as the supported ways to persist environment values.^[7]

Pipes make the difference concrete. There is no need to save a Docker log, upload it to a chat, and explain what it contains. The operating system’s stdout can become Claude’s stdin.

docker compose logs --since=10m api \
  | grep -E 'ERROR|WARN|timeout' \
  | claude -p 'List the three most likely causes by severity. Cite the supporting log lines and give the next diagnostic command.'

cat build-error.txt \
  | claude -p 'Identify only the first root cause and separate it from cascading errors.'

The current stdin limit for non-interactive mode is 10 MB. Instead of pouring an entire log history into the model, use --since, tail, grep, and jq to constrain it first. This is more than a cost trick. The shell defines the observation; the model performs the inference. The resulting command can be rerun, reviewed, or inserted into CI.^[8]

In the CLI, Claude is part of the same pipeline as the log or diff, not a separate destination receiving a copied result. The method of selecting evidence becomes reproducible.

4. Token control means touching only the necessary files

The CLI is not automatically cheap, and Desktop is not automatically wasteful. Both use the same Claude Code engine, and token use grows with the amount of context the model processes. What matters is whether the input surface is deliberately constrained.^[9]

The terminal makes that constraint explicit:

git diff -- src/auth tests/auth \
  | claude -p 'Review only trust boundaries, exception handling, and regression coverage.'

rg -n 'TODO|FIXME|deprecated' src/payments \
  | claude -p 'Classify only items that could plausibly cause a production incident.'

This style does not begin with “read the whole repository.” The developer narrows the directory, diff, time window, and error level first. It is closer to a surgeon selecting an examination site from symptoms than to scanning the entire body on every visit.

Subagents reinforce the same idea. A large search or noisy log can be processed in an isolated context, with only a summary returned to the main conversation. Anthropic lists preserving the main context, enforcing tool restrictions, reusing roles, and selecting an appropriate model among the reasons to use them. Agent Teams are more powerful, but every teammate is a separate Claude instance. Anthropic’s cost guidance says teams running in plan mode can use roughly seven times the tokens of a standard session. Parallel is not synonymous with efficient.^[10][9]

5. The largest difference is not headcount but communication structure

Subagents resemble a manager delegating work to specialists. Each Subagent has an isolated context and a constrained tool set, handles research, review, or implementation, and returns its result to the caller. They work in both Desktop Code and the CLI. They can run in the background while the main session continues with something else.^[10]

Agent Teams change the topology. The main session becomes a team lead, while multiple teammates run as independent Claude Code sessions. They claim work from a shared task list, send messages to each other, and release dependent work when prerequisites finish. A human can speak to a teammate directly instead of routing every exchange through the lead. This is not merely “three Subagents instead of one.” It changes centralized delegation into a network with team-level coordination.^[11]

Subagents isolate specialist work and return results. Agent Teams add a shared task system and lateral communication. The important difference is topology, not the number of workers.

Consider a production incident:

1. log-investigator reads only the production timeline and identifies the first anomaly.
2. code-investigator reads the relevant commit and call path, then proposes failure hypotheses.
3. test-investigator builds a reproduction and tries to falsify those hypotheses.
4. team lead reconciles the evidence and hands one root cause to a fixer.

Subagents can parallelize the three investigations. Agent Teams become useful when the log investigator needs to send a timestamp directly to the code investigator, who then sends a concrete input condition to the test investigator before any of them has finished. If the deliverables are independent and only need to be summarized at the end, Subagents are lighter.

6. When Agent Teams appeared, and how they evolved through September 2026

Agent Teams are not a long-established, finished facility. They entered Claude Code 2.1.32 on February 5, 2026 as a research preview. From the beginning, they required CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and were described as token-intensive. Version 2.1.33 on February 6 fixed teammate messaging in tmux and added TeammateIdle and TaskCompleted hooks. Version 2.1.45 on February 17 fixed propagation of provider environment variables to tmux-spawned teammates on Bedrock, Vertex, and Foundry. Version 2.1.49 on February 19 added worktree isolation and always-background execution to Subagent definitions, strengthening the safety and observability of parallel work more broadly.^[12]

Agent Teams did not arrive as a finished product. Messaging, shared tasks, environment propagation, and background execution have been rebuilt in short cycles to create a sturdier collaboration surface.

As of September 2026, the official Agent Teams guide describes the post-2.1.178 design. The explicit team-creation and deletion steps required by early builds are gone; teams form from the session and clean themselves up on exit. Yet Anthropic still labels the feature experimental and disabled by default, and documents known limitations in resuming sessions, task coordination, and shutdown behavior.^[11]

Enabling the feature does not require switching to API billing. It is an ordinary Claude Code setting:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or enable it for one shell invocation:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

Then describe roles with independent boundaries:

Create an Agent Team.
- investigator: read-only review of the incident logs and latest diff
- test-owner: own only the reproduction test
- fixer: edit only after investigator and test-owner agree

Do not edit the same file concurrently. Record evidence and file ownership in the shared task list.

There is no official public date for Agent Teams in Desktop. Desktop already has parallel sessions, a subagent pane, an integrated terminal, and task views, so a future integration would not be visually implausible. But Agent Teams must jointly handle independent session startup, permission inheritance, shared tasks, lateral messaging, and clean shutdown and resumption—the exact areas where the experimental guide still lists limitations. There is no evidence strong enough to promise that the change is merely “a matter of time.” The honest planning assumption is that Agent Teams remain CLI-only until Anthropic says otherwise.

7. Keep configuration from polluting the repository by separating shared and personal scope

A custom Subagent is a Markdown file with YAML frontmatter. Claude Code has two standard locations: ~/.claude/agents/ makes an agent available across every project on the machine, while .claude/agents/ scopes it to the current project. A project definition takes precedence when the same name exists in both places.^[10]

Shared and personal settings change roles through placement. Put cross-project tools at home scope, unshared project specifics inside the local box, and team rules where everyone can see and review them.

Method 1: store personal agents in your home directory

If review style or log-reading behavior belongs to your personal workflow, keep it outside Git from the start.

mkdir -p ~/.claude/agents
$EDITOR ~/.claude/agents/code-reviewer.md
$EDITOR ~/.claude/agents/log-watcher.md
claude

There is then nothing to commit accidentally, and the same agent name works across projects. Confidential URLs, personal sandbox names, and machine-local commands should likewise live in CLAUDE.local.md or a home-scoped file rather than a shared CLAUDE.md. Anthropic documents CLAUDE.local.md for personal, project-specific instructions.^[13]

Method 2: keep definitions inside the project but exclude them locally

This is useful when an agent needs project-specific paths and test commands, but the team has not agreed to distribute it.

mkdir -p .claude/agents
cp ~/.claude/agents/code-reviewer.md .claude/agents/

printf '\n/.claude/agents/\n/CLAUDE.local.md\n' >> .git/info/exclude
git check-ignore -v .claude/agents/code-reviewer.md CLAUDE.local.md
git status --short

.git/info/exclude affects that repository and is normally not committed. If you want the same personal exclusion in every repository, configure a global ignore file:

touch ~/.gitignore_global
printf '\n**/.claude/agents/\n**/CLAUDE.local.md\n' >> ~/.gitignore_global
git config --global core.excludesFile ~/.gitignore_global
git check-ignore -v .claude/agents/code-reviewer.md

Git’s documentation draws the same boundary: use a committed .gitignore for exclusions the whole team should share, .git/info/exclude for untracked files specific to one user in one repository, and core.excludesFile for a user’s cross-repository patterns. Ignore rules do not affect tracked files. Check first with git ls-files .claude CLAUDE.local.md, and do not run git rm --cached without a team decision.^[14]

CLAUDE.md deserves a different policy. Build commands, test gates, architecture rules, and shared prohibitions should usually be committed and reviewed. Only personal preferences should be hidden. If shared rules are excluded, another developer or CI agent cannot reproduce the same decisions.

8. Two copy-ready Subagents, with permissions that match their roles

The first useful agent is a reviewer that cannot edit. Save this as ~/.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Read-only review of changed code, reporting findings by severity without implementing fixes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer.

Inspect only the requested changes and their immediate dependencies. Report:
1. security, data-loss, authentication, and authorization defects;
2. runtime bugs, race conditions, and missing boundary handling;
3. missing tests and maintainability risks.

For every finding, include file, line, reproduction condition, and the smallest safe remediation.
Label unsupported hypotheses as "needs verification."
Do not create or edit files, commit, or push.
If there are no material findings, say "no material findings."

The second watches logs without fixing or restarting anything. Save it as ~/.claude/agents/log-watcher.md:

---
name: log-watcher
description: Monitors local Docker and application logs, summarizing only new anomalies and evidence. Never fixes or restarts services.
tools: Bash, Read, Grep, Glob
disallowedTools: Write, Edit
permissionMode: plan
model: sonnet
background: true
---

You are a read-only log observer.

At startup, establish the target service, observation window, and healthy baseline.
Use --since, --tail, grep, and jq to read only the necessary range.
Collapse repeated known lines. Report the first anomalous timestamp, preceding events,
ranked hypotheses, and the next diagnostic command a human should run.

Never change source, settings, databases, or containers.
Never start, stop, restart, kill, deploy, commit, or push.
If nothing new appears, report the observed range and "no new anomaly."

Removing Write and Edit does not make Bash physically read-only; shell commands can still write. That is why the example layers permissionMode: plan and explicit prohibitions. If the boundary truly must not fail, add enforcement outside the prompt: a monitoring-only OS account, a read-only Docker socket proxy, or read-only CloudWatch IAM permissions. A prompt is one safety layer, not an authorization system.

Invoke the definitions in natural language:

Use code-reviewer to review the changes under src/auth.
Start log-watcher in the background and observe api for 15 minutes.

Claude uses each agent’s description to decide when to delegate, and those descriptions enter startup context. Anthropic warns when the combined description text of custom agents exceeds 15,000 tokens. Keep the description to “when to use this agent,” and put the detailed procedure in the body.^[10]

9. The operating model: separate the control plane from the work plane

Claude Desktop is strong at visual work involving images, PDFs, Artifacts, diffs, previews, and multiple sessions. It can use Subagents. The CLI is strong at stdin and stdout, Docker and Git pipelines, launching from the current shell environment, scripting and CI, and—at present—Agent Teams.

A natural combined workflow is to use Desktop as the control plane for visual judgment and the CLI as the work plane connecting the operating system to agents. If you prefer to use only one, choose with these criteria:

• Repeatedly compare images, PDFs, rendered screens, and diffs: Desktop.
• Filter logs, Git diffs, or JSON through a pipeline: CLI.
• Isolate independent research: Subagents in either Desktop or CLI.
• Let workers exchange intermediate findings through a shared task list: Agent Teams in the CLI.
• Make a small sequential edit to one file: one session in either interface.

Choosing an AI development tool is not a personality test between keyboard people and mouse people. It is a systems decision about which data flows through which permissions to how many agents under what communication topology.

The more you appreciate Desktop’s convenience, the more the CLI’s pipelines and Agent Teams can change how you divide work. The more deeply you live in the terminal, the more Desktop’s visual review and Subagents reveal work that never needed to be forced into a terminal. If you understand both and still open only one today, that choice now has a reason.