What is Mainframe Mode?
Mainframe mode turns one Code CLI instance into a hub that coordinates other instances. The hub distributes tasks, monitors progress, and collects results — all from your terminal. Think of it as a control plane for AI-powered development.
Setup
You need two or more Code CLI terminals. Start the targets first, then the hub.
Step 1: Start Target Instances
Open a terminal in your project directory and start Code CLI:
bashpoly chat
Inside the session, connect as a target:
/mainframe-connect
The terminal registers itself for discovery and waits for instructions. Repeat in as many terminals as you want — each one becomes an available worker.
Step 2: Start the Hub
In a new terminal, start Code CLI and activate Mainframe:
/mainframe
The hub discovers connected targets via file-based discovery, establishes SSE (Server-Sent Events) connections for real-time communication, and the orchestrator agent takes over. You'll see a list of connected terminals with their status.
Three Orchestration Modes
Normal Mode
Describe what you want. The orchestrator analyzes your request, breaks it into subtasks, and distributes them across connected terminals.
Build a REST API for user management with authentication,
database migrations, and test coverage.
The orchestrator might assign one terminal to scaffold the database schema, another to implement the API routes, and a third to write tests — all running in parallel. It monitors progress and coordinates when tasks have dependencies.
Loop Mode
Set a goal and let the orchestrator iterate until it's achieved.
/mainframe loop "All tests pass and coverage is above 80%"
The orchestrator runs tests, identifies failures, assigns fixes to available terminals, re-runs tests, and repeats. Loop mode is useful for convergence tasks — linting, test coverage targets, performance optimization — where the definition of "done" is measurable.
Manual Mode
Directly interact with individual terminals from the hub. Send a prompt to a specific terminal, read its output, and steer the work.
/mainframe send terminal-1 "Refactor the auth middleware to use JWT"
/mainframe read terminal-1
Manual mode is useful when you need fine-grained control or want to debug what a specific terminal is doing.
Orchestrator Tools
The Mainframe hub has 9 tools for managing connected terminals:
| Tool | Purpose |
|---|---|
| List terminals | See all connected instances and their status |
| Check status | Get the current state of a specific terminal |
| Send prompt | Dispatch a task to a terminal |
| Read messages | Get the output from a terminal |
| Create session | Start a new session on a terminal |
| Change model | Switch the AI model a terminal is using |
| Change agent | Switch the agent type on a terminal |
| Abort task | Cancel a running task on a terminal |
| Collect results | Gather completed results from the async queue |
Practical Patterns
Parallel Feature Development
Connect 3 terminals. Send each a different feature:
Terminal 1: "Implement user registration with email verification"
Terminal 2: "Implement OAuth2 login with Google and GitHub"
Terminal 3: "Implement password reset flow with email tokens"
All three develop in parallel. The orchestrator monitors for conflicts — if two terminals modify the same file, it flags the collision and coordinates the merge.
Code Review Pipeline
Connect 2 terminals. One writes code, the other reviews:
Terminal 1: "Implement the payment processing module"
Terminal 2: "Review the changes in terminal 1 and suggest improvements"
The review terminal watches for completed work and provides feedback that the implementation terminal can act on.
Test-Fix Loop
Connect 2 terminals in loop mode:
Terminal 1: Runs tests continuously
Terminal 2: Fixes failing tests as they're reported
The loop continues until all tests pass.
Tips
- Start small. Two terminals is enough to see the benefit. Scale up as you learn the patterns.
- Name your terminals. Use descriptive session names so the orchestrator's output is easy to follow.
- Set agent types. Different terminals can run different agent types — use the
buildagent for implementation and theexploreagent for code review. - Watch the hub. The hub shows real-time progress from all terminals. Keep it visible as you work.
- Use session diff. Press
Ctrl+X, sin any terminal to see exactly what the agent modified during the session.
What's Next
Mainframe mode works locally today. We're building toward remote orchestration — connect terminals running on different machines, in CI environments, or in cloud workspaces. The protocol is SSE-based and designed to work across networks.
For the full Code CLI documentation, see docs.poly.inc/code-cli.