Multi-CLI Workflows

What You’ll Learn

When a task grows beyond what a single Claude Code session can handle effectively, the most powerful pattern is running multiple terminal sessions simultaneously --- each with its own full context window, its own role, and its own area of focus.

By the end, you’ll understand:

• Why multiple terminals outperform a single session for large tasks
• How to assign roles to each terminal
• How terminals communicate through the filesystem
• The orchestrator pattern for coordinating work
• When to use multi-CLI vs. single CLI with subagents

The Problem

A single Claude Code session has one context window. When you are implementing a feature that touches the database schema, the API layer, the frontend, and the test suite, a single session must constantly page information in and out. While one session is running tests, you sit idle. While it is deep in a refactor, you cannot ask it to plan the next step.

The fundamental constraint: one session, one focus, one context.

How It Works

The Multi-Terminal Pattern

┌──────────────────────────────────────────────────┐
│                  Your Screen                      │
│                                                   │
│  ┌─────────────────┐  ┌─────────────────┐        │
│  │  Terminal 1      │  │  Terminal 2      │       │
│  │  ORCHESTRATOR    │  │  IMPLEMENTER     │       │
│  │  Plans the work  │  │  Writes the code │       │
│  │  Reviews results │  │  Follows the plan│       │
│  └─────────────────┘  └─────────────────┘        │
│  ┌─────────────────┐  ┌─────────────────┐        │
│  │  Terminal 3      │  │  Terminal 4      │       │
│  │  VALIDATOR       │  │  FIXER           │       │
│  │  Runs tests      │  │  Reads errors    │       │
│  │  Reports issues  │  │  Applies fixes   │       │
│  └─────────────────┘  └─────────────────┘        │
│                                                   │
└──────────────────────────────────────────────────┘

Each terminal runs its own Claude Code instance with its own full context window, used entirely for its specialized role.

Communication Through the Filesystem

Terminals do not communicate directly. They share information through the one thing they all have access to: the filesystem.

project/
├── .tasks/
│   ├── plan.md              ← Orchestrator writes
│   ├── task-01-schema.md    ← Orchestrator writes, Implementer reads
│   ├── task-02-api.md       ← Orchestrator writes, Implementer reads
│   ├── progress.md          ← Implementer writes, Orchestrator reads
│   └── errors.md            ← Validator writes, Fixer reads
├── src/                     ← Implementer + Fixer write
└── tests/                   ← Validator runs, Fixer fixes

The protocol: Orchestrator writes task files. Implementer reads tasks, writes code, updates progress. Validator runs checks, writes error reports. Fixer reads errors, applies fixes.

The Orchestrator Pattern

┌─────────────────────────────────────────────────┐
│               Orchestrator Flow                  │
│                                                  │
│  1. Read requirements                            │
│  2. Analyze codebase structure                   │
│  3. Break work into sequential tasks             │
│  4. Write task files to .tasks/                  │
│          │                                       │
│          ▼                                       │
│  5. Tell Implementer: "Start task-01"            │
│  6. Monitor progress.md for completion           │
│          │                                       │
│          ▼                                       │
│  7. When all tasks done, do final review         │
│  8. Write summary and commit                     │
│                                                  │
└─────────────────────────────────────────────────┘

Context Isolation Benefit

This is the critical advantage:

Single CLI (1 session, all tasks):
  Requirements + Schema + API + Frontend + Tests + Errors
  ████████████████████████████████████ 95%
  └── everything crammed into one window ──┘

Multi-CLI (4 sessions, specialized):
  Orchestrator:  ████████░░░░░ 40%   (plan + progress)
  Implementer:   ██████████░░░ 55%   (current task + code)
  Validator:     ██████░░░░░░░ 35%   (test output + lint)
  Fixer:         ████████░░░░░ 40%   (errors + fixes)

Each session has headroom. None is struggling at the context limit.

Key Insight

Multi-CLI workflows are the most powerful pattern for large tasks because each terminal is a specialist with a full context window, not a subagent with limited context.

A subagent returns a summary. It is good for contained subtasks. But for sustained, multi-phase work --- where each role needs deep domain awareness --- a full terminal session is fundamentally superior.

• Subagent = sending a colleague a quick message asking them to look something up
• Multi-CLI terminal = a dedicated team member fully immersed in their part of the project

The filesystem is the shared memory. The tasks directory becomes the project’s coordination bus.

Hands-On Example

Setting Up a 4-Terminal Feature Workflow

Terminal 1 --- Orchestrator:

You are the ORCHESTRATOR for this feature. Your job:
1. Read the requirements I give you
2. Break them into numbered task files in .tasks/
3. Each task file contains: what to implement, which files, acceptance criteria
4. Monitor .tasks/progress.md for updates
5. Do NOT write code yourself — only plan and review

Feature: Add user profile page with avatar upload

The orchestrator creates structured task files:

<!-- .tasks/task-01-schema.md -->
# Task 01: Database Schema

## What
Add user_profiles table with avatar_url column.

## Files
- prisma/schema.prisma (modify)
- prisma/migrations/ (new migration)

## Acceptance Criteria
- [ ] user_profiles table exists with foreign key to users
- [ ] avatar_url is nullable string
- [ ] Migration runs without errors

Terminal 2 --- Implementer:

You are the IMPLEMENTER. Read task files from .tasks/ in order.
Implement each task. Update .tasks/progress.md when done.
Do NOT run tests. Start with task-01-schema.md.

Terminal 3 --- Validator:

You are the VALIDATOR. Run: pnpm test && pnpm lint && pnpm typecheck
Write results to .tasks/errors.md with exact error messages.
Do NOT fix errors — just report them clearly.

Terminal 4 --- Fixer:

You are the FIXER. Watch .tasks/errors.md for new entries.
Read the error, find root cause, apply minimal fix.
Do NOT change the overall approach.

When to Use Multi-CLI vs. Single CLI

Use SINGLE CLI when:              Use MULTI-CLI when:
├── Task < 30 min                 ├── Task > 1 hour
├── Touches 1-3 files             ├── Touches many files across layers
├── Linear workflow                ├── Parallel work is possible
└── Same domain throughout         └── Context would overflow

Alternative Patterns:
  2-Terminal:  Plan + Execute
  3-Terminal:  Frontend + Backend + QA
  5-Terminal:  Orchestrator + Service A + Service B + Gateway + Tests

What Changed

Single CLI	Multi-CLI Workflow
One context window for everything	Full context per role
Sequential work only	Parallel execution
Context fills up on large tasks	Each terminal stays lean
One generalist session	Multiple specialist sessions
Subagents have limited context	Full sessions have full context

Next Session

Session 20 covers Error Recovery --- how to build retry logic, classify errors, and design fallback strategies so your agents handle failures gracefully instead of stopping dead.