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.
- GitHub: github.com/Alvarito1983
- Docker Hub: hub.docker.com/u/afraguas1983
- Part 1: Claude Code: The Complete Guide
Top comments (2)
Really interesting breakdown—this idea of using sub-agents feels like a natural next step once you start treating tools like Claude as real collaborators. I like how you separate concerns and keep context clean, that aligns with the whole “analysis → plan → execute” workflow that makes these systems actually reliable . Definitely makes building features in parallel feel more structured instead of chaotic.
Exactly — the "collaborator" framing is what makes the difference. Once you stop thinking of it as autocomplete and start thinking of it as someone you delegate to, the whole interaction changes. You invest in giving it context, you review the output critically, and you hold it accountable when it's wrong.
The context isolation point is underrated. Each sub-agent starting fresh means no accumulated confusion from a long session. The cost is that you have to be exhaustive in your specs — they don't have the conversational history you've built up. But that constraint actually forces clearer thinking about what you're asking for, which usually produces better output anyway.