Skip to main content
The orchestrator is a special terminal that runs directly in your primary repository branch (often main, but it can be a dedicated feature hub). It doesn’t create a worktree; instead it gives you a control room for coordinating agents and managing complex workflows.
Any commands you run in the orchestrator’s terminals modify that branch immediately. Use isolated sessions when you want a disposable sandbox.

​
What Makes the Orchestrator Special?

Primary Branch Access

Works directly on your primary branch (main or a feature hub)No isolated worktree - full repo access

Planning Hub

Create and manage multiple specsDraft complex features before execution

Agent Coordination

Launch multiple agents in parallelMonitor progress across sessions

MCP Automation

Programmatic session managementExternal tool integration via REST API

​
Core Capabilities

​
1. Plan and Create Specs

Draft multiple specs for complex features:
1

Open orchestrator

Press ⌘1 to switch to orchestrator
2

Create specs

Use ⌘⇧N to create planning documents:
  • Feature requirements
  • Implementation approach
  • Acceptance criteria
  • Dependencies
3

Refine specs

Press ⌘⇧R on a spec to enter Refine Mode:
  • Switches to the orchestrator session
  • Opens the spec in the right panel for live preview
  • Inserts spec reference in agent terminal (requires MCP enabled)
  • Agent can read and update the spec iteratively
Add context, constraints, examples before launching agents
4

Organize specs

Group related specs togetherPlan parallel work streams

​
Refine Mode: Iterative Spec Development

Requires MCP: The orchestrator agent must be able to call schaltwerk_current_spec_update to edit specs. Enable MCP in Settings → Agent Configuration for your agent (Claude Code, Codex, OpenCode, or Gemini).
Refine Mode enables iterative spec development by switching to the orchestrator while keeping the spec visible for live updates:
1

Enter Refine Mode

Select a spec in the sidebar and press ⌘⇧RWhat happens:
  • Session switches to the orchestrator
  • Spec opens in the right panel (live preview)
  • Agent terminal receives spec reference (e.g., “Refine spec: my-feature (abc123)”)
2

Iterative refinement

The agent can now:
  • Read the current spec content via MCP
  • Ask clarifying questions
  • Update the spec with schaltwerk_current_spec_update
  • Preview changes in real-time on the right panel
You watch the spec evolve in the right panel while collaborating with the agent in the terminal.
3

Exit Refine Mode

Press Esc or switch to another session when doneThe refined spec is ready to start with ⌘N
Without MCP enabled, the agent terminal receives the spec reference text but cannot read or update the spec. The agent will need manual copy-paste of spec content.

​
2. Launch Agents in Parallel

Start multiple agents working on different specs simultaneously:
  • Manual Launch
  • MCP Automation
  1. Select first spec
  2. Press ⌘N to start session
  3. Select next spec
  4. Press ⌘N to start another session
  5. Switch between sessions with ⌘1-9

​
3. Review Agent Work

Check diffs, run tests, provide feedback:
  • Switch to session with ⌘2-9
  • View diffs in right panel
  • Check git status in bottom terminal
  • Review file changes
  • Focus bottom terminal with ⌘/
  • Execute test suite
  • Or use Run Mode with ⌘E
  • Verify all tests pass
  • Focus agent terminal with ⌘T
  • Send instructions or corrections
  • Agent receives feedback and continues
  • Press ⌘R when satisfied
  • Session moves to Reviewed filter
  • Ready for merge

​
4. Integrate Changes

Merge approved sessions back to main branch:
1

Filter reviewed sessions

Click Reviewed tab to see approved sessions
2

Verify each session

  • Tests pass
  • No merge conflicts
  • Changes are correct
3

Merge to main

From session header actions:
  • Create GitHub PR
  • Merge directly
  • Cherry-pick specific commits
4

Clean up

After successful merge, press ⌘D to cancel session

​
5. Coordinate Workflows

Chain tasks together for complex automation: 
Orchestrator receives: "Build complete authentication system"

1. Break into specs:
   - Spec 1: User registration with email validation
   - Spec 2: Login with JWT tokens
   - Spec 3: Password reset via email
   - Spec 4: Session management

2. Launch agents on each spec in parallel

3. Monitor progress:
   - Check which sessions are complete
   - Identify any blocked sessions
   - Provide additional context if needed

4. Review completed work:
   - Run integration tests
   - Check for conflicts between sessions
   - Verify all acceptance criteria met

5. Integrate in order:
   - Merge dependencies first (e.g., session management)
   - Then merge features (registration, login, reset)
   - Run full test suite after each merge

​
Automated Workflows via MCP

The orchestrator supports MCP (Model Context Protocol), enabling programmatic session management.

​
What MCP Enables

Session Creation

External tools create sessions via REST APINo manual UI interaction needed

Status Monitoring

Query session states programmaticallyTrack completion and review status

Workflow Automation

Chain operations togetherBuild complex multi-agent pipelines

​
Customization Options

​
Claude Slash Commands

Create custom commands that execute orchestrator actions:
Documentation for custom slash commands coming soon. This feature enables you to define shortcuts for common orchestrator workflows.

​
Action Buttons (F1-F6)

Configure function keys with prompts for common workflows:
Action button configuration coming soon. Map F1-F6 to frequently-used orchestrator commands.

​
Prompt Templates

Save and reuse complex orchestration patterns: 
# Feature: [FEATURE_NAME]

## Goal
[Describe the feature]

## Breakdown
Create the following sessions:
1. [Component 1] - [Description]
2. [Component 2] - [Description]
3. [Component 3] - [Description]

## Dependencies
- [Component 1] must complete before [Component 2]
- All components use [shared dependency]

## Testing Strategy
- Integration tests after each component
- Full E2E tests after all merges

​
Terminal Layout

The orchestrator has the same dual-terminal layout as regular sessions:
  • Top Terminal
  • Bottom Terminal

Agent TerminalRun AI assistants that can:
  • Create and manage specs
  • Launch sessions programmatically
  • Monitor session progress
  • Coordinate multi-agent workflows

​
Best Practices

  • Draft all specs first
  • Identify dependencies
  • Determine execution order
  • Consider resource constraints (don’t run 20 agents at once)
Use descriptive names that indicate:
  • What the session does
  • Which component it affects
  • Relationship to other sessions
Examples:
  • auth-login-implementation
  • api-user-endpoints
  • fix-email-validation-bug
Each session creates 3 OS processes:
  • Shell process
  • Agent process
  • Terminal backend
Don’t run too many sessions simultaneously
Don’t let reviewed sessions pile up:
  • Review daily if possible
  • Merge or provide feedback
  • Keep the pipeline moving
Create prompt templates for:
  • Common feature patterns
  • Bug fix procedures
  • Review checklists
  • Integration strategies

​
Common Orchestrator Workflows

​
Feature Development

1

Receive feature request

User describes desired functionality
2

Break into components

Create specs for each component:
  • Backend API
  • Frontend UI
  • Database migrations
  • Tests
3

Launch agents

Start sessions for each componentAgents work in parallel
4

Monitor progress

Check which sessions are completeProvide feedback as needed
5

Integrate

Merge components in dependency orderRun integration tests
6

Final review

Test complete featureVerify all requirements met

​
Bug Fixing

1

Identify bugs

Run test suite or review issue tracker
2

Create bug specs

One spec per bug with:
  • Reproduction steps
  • Expected behavior
  • Error messages
  • Related files
3

Assign agents

Start sessions for each bugAgents investigate and fix
4

Verify fixes

Run tests for each fixCheck for regressions
5

Merge fixes

Integrate passing fixesRe-run full test suite

​
Refactoring

1

Identify refactoring needs

Code smell, performance issue, or architectural change
2

Plan refactoring

Break into safe, incremental steps:
  • Extract methods
  • Rename variables
  • Restructure modules
  • Update tests
3

Create specs for each step

Small, focused changesEach step maintains functionality
4

Execute incrementally

Complete one step at a timeVerify tests pass after each
5

Final verification

Run full test suiteCheck performance metrics

​
Tips and Tricks

Use Filters Effectively

  • Specs: Planning queue
  • Running: Active work
  • Reviewed: Ready for merge
Switch between views with ⌘←/→

Leverage Keyboard Shortcuts

  • ⌘1 - Back to orchestrator
  • ⌘2-9 - Jump to sessions
  • ⌘↑/↓ - Cycle through sessions
  • ⌘⇧R - Refine spec in orchestrator
  • ⌘N - Start selected spec

Keep Main Clean

Orchestrator works on main branchDon’t make direct changes - use sessions

Document Decisions

Use orchestrator’s bottom terminal to:
  • Record design decisions
  • Document workflow patterns
  • Save useful commands

​
Limitations

Be aware of these orchestrator limitations:
  • No Worktree - Orchestrator runs on main branch, not in isolation
  • Resource Usage - Each session consumes system resources (3 processes)
  • Concurrent Agents - Don’t run too many agents simultaneously
  • Manual Merge - Merging sessions still requires manual review and approval

​
Next Steps

MCP Server Setup

Set up programmatic session management

Using Schaltwerk

Learn the day-to-day workflow