This is Part 2 of my Claude Code series. Part 1 covers the fundamentals — installation, CLAUDE.md, prompts, and workflow patterns. Read that first if you're new to Claude Code.

This part is about something most guides don't cover: sub-agents. How to run multiple specialized AI agents in parallel, coordinate them, and use them to build entire features simultaneously.

This isn't theoretical. Everything here comes from building NEXUS Ecosystem — six self-hosted Docker tools — where sub-agents went from curiosity to core workflow.

What sub-agents actually are

When you run Claude Code normally, you have one agent doing one thing at a time. It reads, thinks, writes, verifies — sequentially.

Sub-agents change that. You can launch multiple specialized agents that work in parallel, each focused on a specific task, while the main agent orchestrates.

The mental model: instead of one developer doing everything, you have a tech lead (the main agent) coordinating a team of specialists (sub-agents).

Here's what it looks like in practice:

● 2 background agents launched (↓ to manage)
   ├─ nexus-security improvements: Check Now fix, sidebar logs, Report view
   └─ nexus-hub Log Center: backend routes, tool log helpers, frontend Logs panel
● Both agents are running in parallel.

That's two agents simultaneously building two different modules of the same project. One fixing and extending the Security tool. One building an entirely new Log Center in Hub. Neither blocking the other.

The work that would have taken 3-4 sequential hours took under 45 minutes.

Installing the agent marketplace

Claude Code has a built-in agent system, but the real power comes from the community marketplace. The one worth installing is wshobson/agents — 22 specialized agents covering everything from backend security to Kubernetes to incident response.

Install it:

# Add the marketplace
claude config set extraKnownMarketplaces.claude-code-workflows.source.source github
claude config set extraKnownMarketplaces.claude-code-workflows.source.repo wshobson/agents

# Install the agents you need
claude plugin install agent-teams@claude-code-workflows
claude plugin install backend-development@claude-code-workflows
claude plugin install security-scanning@claude-code-workflows
claude plugin install debugging-toolkit@claude-code-workflows
claude plugin install comprehensive-review@claude-code-workflows
claude plugin install incident-response@claude-code-workflows

Verify what's installed:

claude plugin list
# or inside a session:
/agents

The /agents command opens a panel showing all available agents with their model assignments (haiku, sonnet, or opus depending on complexity).

The agents worth knowing

Not all 22 agents are equally useful. These are the ones I actually use:

agent-teams:team-lead (opus) — Orchestrates other agents. Use this when you need someone to break down a complex task and delegate to specialists. It thinks slower but plans better.

agent-teams:team-implementer (opus) — Pure implementation. Give it a spec and it builds. Works best when the architecture is already decided.

agent-teams:team-reviewer (opus) — Code review. Run this after implementation to catch issues before you do.

backend-development:security-auditor (sonnet) — Scans backend code for vulnerabilities, auth issues, injection risks. Genuinely useful before deploying.

debugging-toolkit:debugger (sonnet) — Specialized in diagnosis. Give it a symptom and it traces through the code to find the cause. Better than the general agent for tricky bugs.

comprehensive-review:architect-review (opus) — High-level architecture review. Use this when you've built something significant and want a second opinion on the design decisions.

security-scanning:threat-modeling-expert — Thinks about what could go wrong in your system. Good for security-sensitive features.

How to launch sub-agents

The simplest way is to describe parallel work in your prompt and ask Claude Code to use sub-agents:

Implement two features in parallel using sub-agents:

## SUB-AGENT 1 — Security improvements
[detailed spec for security work]

## SUB-AGENT 2 — Log Center
[detailed spec for log center work]

Report when both complete.

Claude Code launches both agents and manages them. You see output like:

● Agent "Security improvements" completed
● Sub-agente 1 completado. Resumen:
  - Check Now fix: polling cada 3s...
  - Panel de logs: ring buffer 50 entradas...
  - Report view: deduplicación de CVEs...
  ---
  Sub-agent 2 sigue en ejecución.

The key insight: each sub-agent gets its own context window. They don't share state or interfere with each other. This is why parallel work is possible — there's no race condition on the context.

Checking on agents without interrupting them

This took me a while to figure out. When agents are running in background, you don't want to interrupt them — but you might want to know what's happening.

The /btw command is designed exactly for this:

/btw how are the two background agents doing?

You get a status report without the agents noticing:

  Los agentes siguen corriendo.
  Sub-agente 1 (nexus-security) — en progreso
  - Ya modificó containerMonitor.js
  - Queda: fix Check Now, panel de logs, vista Report

  Sub-agente 2 (nexus-hub Log Center) — en progreso  
  - Sin cambios confirmados aún
  - Tiene más trabajo: rutas logs.js, helper logToHub(),
    componente LogsPanel.jsx con 3 tabs

The agents keep running. You keep informed. No interruption.

To actually manage them, press ↓ to open the agent panel:

● 2 background agents launched (↓ to manage)
   ├─ nexus-security improvements ✓ completed
   └─ nexus-hub Log Center — still running

The orchestrator pattern

For complex multi-service projects, the most effective pattern is explicit orchestration: one agent that reads the full context and coordinates, specialists that implement.

Here's a real prompt structure I use:

You are the orchestrator for this task. 
Before launching any sub-agents:

1. Read the CLAUDE.md completely
2. Read these files to understand current state:
   - nexus-hub/backend/server.js
   - nexus-security/backend/src/routes/scan.js
   - nexus-hub/backend/src/services/flowEngine.js

3. Plan the work and split into parallel tracks
4. Launch sub-agents with specific, complete specs
5. Wait for all to complete
6. Run a final integration check

The goal: implement CVE scanning in Security with 
automatic alerts to Hub when Critical found.

Use security-scanning:security-auditor for the 
security implementation and backend-development:backend-architect 
for the Hub integration.

The orchestrator reads everything first, makes the architectural decisions, then delegates implementation to specialists who don't need to understand the full picture.

Real example: building Security and Log Center in parallel

Here's a condensed version of a real session from building NEXUS. I needed to:

Add a progress bar to Security's Check Now button
Add a sidebar activity log to Security
Build an entirely new Log Center in Hub with 3 tabs
Add logToHub() helper to all 5 tools

Instead of doing this sequentially (3-4 hours), I launched two sub-agents:

Dos tareas en paralelo con sub-agentes:

## SUB-AGENTE 1 — nexus-security
Lee nexus-security/frontend/src/components/Dashboard.jsx
y nexus-security/backend/src/services/containerMonitor.js

Implementa:
1. Check Now con progreso real — polling /api/scan/results
   cada 3s, timeout 5min, toast al terminar
2. Panel Activity en sidebar — ring buffer 50 entradas,
   logs tiempo real via Socket.io, color-coded por tipo

Rebuild: docker compose -f docker-compose.test.yml up --build -d nexus-security

## SUB-AGENTE 2 — nexus-hub Log Center
Lee nexus-hub/backend/server.js y src/routes/ (todos)

Implementa:
- POST /api/logs — ingest con X-Api-Key
- GET /api/logs/ecosystem, /app/:source, /docker/:source
- Retención 10 días en /app/data/logs/[source]/[YYYY-MM-DD].json
- LogsPanel.jsx con 3 tabs: Ecosystem Events / App Logs / Docker Logs
- logToHub() helper en los 5 tools

Rebuild: todos los servicios al terminar

Results:

● Agent "nexus-security improvements" completed  ✓  8m 12s
● Agent "nexus-hub Log Center" completed         ✓  19m 44s

Two significant features. Parallel. ~20 minutes total.

The Security agent finished first (simpler scope). The Log Center agent took longer (6 services to modify). But they didn't block each other.

What makes sub-agents faster

It's not magic. Here's the actual reason parallel agents save time:

No context switching cost. When one agent finishes reading Security's files, it doesn't have to context-switch to understand Hub's architecture. The Hub agent has its own fresh context, already loaded with the right files.

No sequential dependencies (when designed correctly). If you structure the work so agents aren't waiting on each other's output, they run fully in parallel. The Log Center doesn't need Security's code to be finished — it's a separate service.

Model specialization. A security-auditor agent running on sonnet is tuned differently than a general team-implementer. The right model for the right task.

The failure mode: creating false dependencies. If you ask Agent 2 to "use the pattern that Agent 1 will establish", Agent 2 has to wait. Design your parallel tasks to be genuinely independent.

Giving agents their own CLAUDE.md context

This is underused. You can pre-load agents with specific context using the prompt structure:

## CONTEXT FOR THIS AGENT
You are working on nexus-security only.
The project is at E:\Claude\NEXUS\nexus-security

Key facts:
- Accent color: #ef4444 (red)
- Backend port: 9093, container: nexus-security-test  
- Frontend uses CSS custom properties, no Tailwind
- Socket.io is already configured in server.js
- The scan result format is: { id, severity, package, 
  version, fixedIn, description }
- Do not touch nexus-hub — that's a separate agent's scope

## YOUR TASK
[specific instructions]

This context header tells the agent exactly what it needs to know without reading the entire CLAUDE.md. For sub-agents with narrow scope, targeted context is more efficient than full project context.

The mistakes I made

Launching agents with vague specs. Sub-agents don't have the conversational context you've built up in the main session. They start cold. If your spec says "fix the Check Now button", the agent doesn't know what's wrong with it, what the expected behavior is, or what files to look at. Be exhaustively specific.

Creating dependent parallel tasks. I once launched two agents where Agent 2 needed to "follow the pattern Agent 1 establishes". Agent 2 started before Agent 1 finished, made its own decisions, and the patterns were inconsistent. Now I either sequence dependent tasks or make both specs completely explicit.

Not including the rebuild step. Sub-agents will write perfect code and then stop. If you don't explicitly tell them to rebuild the Docker containers, you won't see the changes. Always end sub-agent specs with the rebuild command.

Overloading a single sub-agent. One agent doing 10 things is slower than two agents doing 5 things each. But one agent doing 30 things will run out of context before it finishes. Scope sub-agents to coherent, bounded tasks.

Ignoring the completion order. Agents complete when they're done, not when you expect them to. The faster one might complete while the slower one is still running. Check both before doing integration work.

When not to use sub-agents

Sub-agents are powerful but not always the right tool.

Don't use them for tasks with shared state. If both agents are writing to the same store.js or modifying the same Docker compose file, you'll get conflicts. One agent's changes will overwrite the other's.

Don't use them for highly sequential work. If Step B genuinely cannot start until Step A is complete, sub-agents just add overhead. Sequential is fine.

Don't use them for quick tasks. Launching a sub-agent has overhead. For a 5-minute task, just do it directly.

Don't use them when you need to watch the work. Sub-agents run in background. If you need to review and approve intermediate steps, sequential work with explicit phase breaks is better.

The real productivity shift

When I look back at building NEXUS Ecosystem — six tools, SSO, CVE scanning, real-time logs, event-driven alerts — the sub-agent pattern is what made the scope possible for a solo developer.

Not because it's magic. Because it matches how real work is structured: parallel tracks, specialized expertise, coordinated by someone who understands the full system.

That someone is still you. The orchestration decisions, the architectural choices, the review — those are yours. Sub-agents execute. You direct.

The ceiling on what one person can build has moved. Sub-agents are a significant part of why.

NEXUS Ecosystem is open source. All the patterns above come from real sessions building it.