Agentic Shell Workflows — Claude Code Sub-Agents in Practice

Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel. Let's build a real sub-agent workflow end to end.

55 min · Reviewed 2026

A Small Team in Your Terminal

A sub-agent is a separately-scoped Claude instance spawned by your main session to handle a focused job. Up to 10 can run in parallel. Each has its own system prompt, tool access, and MCP servers. You stop being one person typing and become an orchestrator directing specialists.

When to reach for sub-agents

Tasks that split cleanly into parallel parts (explore 5 files independently)
Jobs with different tool needs (one agent reads DB, another edits code)
Long-running investigations where main session would spiral
Research tasks you can batch (summarize every file in src/)
Multi-step pipelines (plan → implement → test → review)

Defining a sub-agent

# .claude/agents/explorer.md
---
name: explorer
description: Map unfamiliar code — summarize files, identify entry points, trace data flow
tools:
  - Read
  - Grep
  - Glob
mcpServers:
  # Explorer gets read-only GitHub access; no edit privileges.
  github-readonly:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github", "--readonly"]
---

You are an exploration agent. Your job:
1. Read files requested by the parent agent.
2. Produce concise, structured summaries.
3. Cite file paths and line numbers for every claim.
4. Never edit files — explore only.One markdown file, one scoped agent. Frontmatter controls tools and MCP access.

Orchestrator patterns

Pattern	Use case
Fan-out	Split a job across N agents, merge results (explore 10 directories)
Pipeline	Sequence of specialized agents (planner → coder → tester → reviewer)
Supervisor	Main agent supervises narrow workers (main plans, subagents execute)
Sandbox	Run risky commands in a scoped subagent with limited tools

A real fan-out session

You (in main Claude Code session):
  "Use the explorer agent to summarize each of these 5 files in parallel:
   src/auth/login.ts, src/auth/signup.ts, src/auth/reset.ts,
   src/auth/sessions.ts, src/auth/middleware.ts
   Then synthesize a single auth-system overview."

Claude (main):
  Spawns 5 explorer subagents, one per file, in parallel.
  Receives 5 summaries in ~30 seconds total.
  Synthesizes a cross-file overview citing each summary.A task that would take 5 minutes of serial reading done in 30 seconds of parallel subagents.

Scoped tools as safety

The best subagent designs restrict capabilities. An explorer that can only read. A tester that can only run tests. A deployer that can only run deploy scripts. Scoping prevents a single hallucinated command from wrecking your repo, and it makes audit trails trivial.

Debugging agent sessions

Every subagent logs to .claude/logs/ — read these when things go sideways
Use hooks on SubagentStart/Stop to track timing and token usage
Ask the orchestrator to summarize what each subagent did at the end
Keep agents single-responsibility — overloaded agents fail opaquely

A production-ready sub-agent registry

explorer: read-only repo mapping
tester: runs tests, reports failures, never edits
reviewer: reviews diffs, read access only
deployer: runs deploy scripts in a narrow shell
researcher: web search and summarization, no code access

You are no longer a typist. You are a conductor.
— A Claude Code power user

The big idea: sub-agents transform Claude Code from assistant to orchestra. Define specialists, give each the minimum tools it needs, and compose them into workflows that are faster and safer than any single agent could be.

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-agentic-shell-workflows-creators

What is the core idea behind "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel. Let's build a real sub-agent workflow end to end.
2. Type a single comment describing the function you want
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
Which term best describes a foundational idea in "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. fan-out
2. sub-agent
3. pipeline
4. scoped tools
A learner studying Agentic Shell Workflows — Claude Code Sub-Agents in Practice would need to understand which concept?
1. sub-agent
2. pipeline
3. fan-out
4. scoped tools
Which of these is directly relevant to Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. sub-agent
2. fan-out
3. scoped tools
4. pipeline
Which of the following is a key point about Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Tasks that split cleanly into parallel parts (explore 5 files independently)
2. Jobs with different tool needs (one agent reads DB, another edits code)
3. Long-running investigations where main session would spiral
4. Research tasks you can batch (summarize every file in src/)
Which of these does NOT belong in a discussion of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Tasks that split cleanly into parallel parts (explore 5 files independently)
3. Long-running investigations where main session would spiral
4. Jobs with different tool needs (one agent reads DB, another edits code)
Which statement is accurate regarding Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Use hooks on SubagentStart/Stop to track timing and token usage
2. Ask the orchestrator to summarize what each subagent did at the end
3. Every subagent logs to .claude/logs/ — read these when things go sideways
4. Keep agents single-responsibility — overloaded agents fail opaquely
Which of these does NOT belong in a discussion of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Ask the orchestrator to summarize what each subagent did at the end
2. Every subagent logs to .claude/logs/ — read these when things go sideways
3. Use hooks on SubagentStart/Stop to track timing and token usage
4. Type a single comment describing the function you want
What is the key insight about "The 10-agent ceiling" in the context of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Up to 10 subagents run in parallel. Beyond that, they queue. Design fan-outs with batch size in mind — 10 explorers + 1 …
2. Type a single comment describing the function you want
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
What is the key insight about "Cost scales with parallelism" in the context of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Ten parallel subagents burn ~10x the tokens of a serial session.
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
Which statement accurately describes an aspect of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Move to the next task list — resist sidequests
3. A sub-agent is a separately-scoped Claude instance spawned by your main session to handle a focused job. Up to 10 can run in parallel.
4. Then: 'Now make it jump.'
What does working with Agentic Shell Workflows — Claude Code Sub-Agents in Practice typically involve?
1. Type a single comment describing the function you want
2. Move to the next task list — resist sidequests
3. Then: 'Now make it jump.'
4. The best subagent designs restrict capabilities. An explorer that can only read. A tester that can only run tests.
Which of the following is true about Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. The big idea: sub-agents transform Claude Code from assistant to orchestra.
2. Type a single comment describing the function you want
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
Which best describes the scope of "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. It is unrelated to ai-coding workflows
2. It focuses on Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in para
3. It applies only to the opposite beginner tier
4. It was deprecated in 2024 and no longer relevant
Which section heading best belongs in a lesson about Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Move to the next task list — resist sidequests
3. When to reach for sub-agents
4. Then: 'Now make it jump.'

← Back to interactive lesson

Tendril · Creators · AI-Assisted Coding

Agentic Shell Workflows — Claude Code Sub-Agents in Practice

Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel. Let's build a real sub-agent workflow end to end.

55 min · Reviewed 2026

A Small Team in Your Terminal

When to reach for sub-agents

Tasks that split cleanly into parallel parts (explore 5 files independently)
Jobs with different tool needs (one agent reads DB, another edits code)
Long-running investigations where main session would spiral
Research tasks you can batch (summarize every file in src/)
Multi-step pipelines (plan → implement → test → review)

Defining a sub-agent

# .claude/agents/explorer.md
---
name: explorer
description: Map unfamiliar code — summarize files, identify entry points, trace data flow
tools:
  - Read
  - Grep
  - Glob
mcpServers:
  # Explorer gets read-only GitHub access; no edit privileges.
  github-readonly:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github", "--readonly"]
---

You are an exploration agent. Your job:
1. Read files requested by the parent agent.
2. Produce concise, structured summaries.
3. Cite file paths and line numbers for every claim.
4. Never edit files — explore only.One markdown file, one scoped agent. Frontmatter controls tools and MCP access.

Orchestrator patterns

Pattern	Use case
Fan-out	Split a job across N agents, merge results (explore 10 directories)
Pipeline	Sequence of specialized agents (planner → coder → tester → reviewer)
Supervisor	Main agent supervises narrow workers (main plans, subagents execute)
Sandbox	Run risky commands in a scoped subagent with limited tools

A real fan-out session

You (in main Claude Code session):
  "Use the explorer agent to summarize each of these 5 files in parallel:
   src/auth/login.ts, src/auth/signup.ts, src/auth/reset.ts,
   src/auth/sessions.ts, src/auth/middleware.ts
   Then synthesize a single auth-system overview."

Claude (main):
  Spawns 5 explorer subagents, one per file, in parallel.
  Receives 5 summaries in ~30 seconds total.
  Synthesizes a cross-file overview citing each summary.A task that would take 5 minutes of serial reading done in 30 seconds of parallel subagents.

Scoped tools as safety

Debugging agent sessions

Every subagent logs to .claude/logs/ — read these when things go sideways
Use hooks on SubagentStart/Stop to track timing and token usage
Ask the orchestrator to summarize what each subagent did at the end
Keep agents single-responsibility — overloaded agents fail opaquely

A production-ready sub-agent registry

explorer: read-only repo mapping
tester: runs tests, reports failures, never edits
reviewer: reviews diffs, read access only
deployer: runs deploy scripts in a narrow shell
researcher: web search and summarization, no code access

You are no longer a typist. You are a conductor.
— A Claude Code power user

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-agentic-shell-workflows-creators

What is the core idea behind "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel. Let's build a real sub-agent workflow end to end.
2. Type a single comment describing the function you want
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
Which term best describes a foundational idea in "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. fan-out
2. sub-agent
3. pipeline
4. scoped tools
A learner studying Agentic Shell Workflows — Claude Code Sub-Agents in Practice would need to understand which concept?
1. sub-agent
2. pipeline
3. fan-out
4. scoped tools
Which of these is directly relevant to Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. sub-agent
2. fan-out
3. scoped tools
4. pipeline
Which of the following is a key point about Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Tasks that split cleanly into parallel parts (explore 5 files independently)
2. Jobs with different tool needs (one agent reads DB, another edits code)
3. Long-running investigations where main session would spiral
4. Research tasks you can batch (summarize every file in src/)
Which of these does NOT belong in a discussion of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Tasks that split cleanly into parallel parts (explore 5 files independently)
3. Long-running investigations where main session would spiral
4. Jobs with different tool needs (one agent reads DB, another edits code)
Which statement is accurate regarding Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Use hooks on SubagentStart/Stop to track timing and token usage
2. Ask the orchestrator to summarize what each subagent did at the end
3. Every subagent logs to .claude/logs/ — read these when things go sideways
4. Keep agents single-responsibility — overloaded agents fail opaquely
Which of these does NOT belong in a discussion of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Ask the orchestrator to summarize what each subagent did at the end
2. Every subagent logs to .claude/logs/ — read these when things go sideways
3. Use hooks on SubagentStart/Stop to track timing and token usage
4. Type a single comment describing the function you want
What is the key insight about "The 10-agent ceiling" in the context of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Up to 10 subagents run in parallel. Beyond that, they queue. Design fan-outs with batch size in mind — 10 explorers + 1 …
2. Type a single comment describing the function you want
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
What is the key insight about "Cost scales with parallelism" in the context of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Ten parallel subagents burn ~10x the tokens of a serial session.
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
Which statement accurately describes an aspect of Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Move to the next task list — resist sidequests
3. A sub-agent is a separately-scoped Claude instance spawned by your main session to handle a focused job. Up to 10 can run in parallel.
4. Then: 'Now make it jump.'
What does working with Agentic Shell Workflows — Claude Code Sub-Agents in Practice typically involve?
1. Type a single comment describing the function you want
2. Move to the next task list — resist sidequests
3. Then: 'Now make it jump.'
4. The best subagent designs restrict capabilities. An explorer that can only read. A tester that can only run tests.
Which of the following is true about Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. The big idea: sub-agents transform Claude Code from assistant to orchestra.
2. Type a single comment describing the function you want
3. Move to the next task list — resist sidequests
4. Then: 'Now make it jump.'
Which best describes the scope of "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. It is unrelated to ai-coding workflows
2. It focuses on Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in para
3. It applies only to the opposite beginner tier
4. It was deprecated in 2024 and no longer relevant
Which section heading best belongs in a lesson about Agentic Shell Workflows — Claude Code Sub-Agents in Practice?
1. Type a single comment describing the function you want
2. Move to the next task list — resist sidequests
3. When to reach for sub-agents
4. Then: 'Now make it jump.'

← Back to interactive lesson