CLI Agent Orchestrator: When One AI Agent Isn't Enough

Wed, 05 Nov 2025 00:00:00 +0000

You’ve hit this wall before. You’re working on some complex modernization project with Claude Code or Amazon Q Developer CLI, and the agent starts losing coherence. Too much context. Too many domains. Architecture bleeding into security bleeding into performance optimization. The agent can’t maintain focus.

Your options have been to manually coordinate between separate agent sessions, copying context around like it’s 2010. Or overload one agent with everything and watch quality degrade as the context window fills up.

AWS to the rescue; they just released CLI Agent Orchestrator (CAO): multiple specialized agents working together under a supervisor. Hierarchical orchestration for your AI CLI tools.

It’s early, opinionated, and requires AWS infrastructure. But it shows where developer AI tooling is headed when single agents aren’t enough.

The Problem
#

Single agents work great for focused tasks. Refactoring? Boilerplate? Debugging? Claude Code or Amazon Q handles it.

But try modernizing a legacy mainframe application. Architecture design, security review, performance optimization, testing, data migration. That’s a project spanning multiple disciplines. Load all that context into one agent and watch quality degrade. The agent contradicts itself, forgets earlier decisions, outputs get generic.

The alternative is running separate agents manually. One for architecture. Another for security. Another for performance. Now you’re copying context between them, manually synthesizing outputs, spending more time coordinating than working. You’ve become the orchestration layer.

CAO is AWS’s answer: a supervisor agent manages specialized workers. Each focuses on its domain. The supervisor handles coordination. Configure the team once, let them collaborate.

How It Works
#

A supervisor agent delegates to specialized workers. One for architecture. One for security. One for performance. The supervisor manages sequencing and maintains context. Workers focus on their specialty and report back.

Each agent runs in its own isolated tmux session. No context pollution. The architecture agent’s history doesn’t leak into the security agent’s work. Sessions communicate through Model Context Protocol (MCP) servers, which handle local communication between the isolated sessions, running entirely on your machine.

CAO supports three patterns. Handoff (synchronous): supervisor waits for completion before proceeding. Assign (asynchronous): supervisor delegates and moves on. Send Message: supervisor checks status without blocking. All implemented through Amazon Bedrock action groups.

Example: Mainframe Modernization
#

The supervisor receives “Create a modernization plan for this COBOL banking system.” It hands off sequentially: architecture agent designs the structure, security agent reviews it, then performance and test agents work in parallel. The supervisor synthesizes outputs into a unified plan.

You could apply this to building microservices applications or migrating monoliths. In practice, you’ll iterate on prompts and intervene when agents drift. But the pattern works when configured well.

The Reality Check
#

CAO only works with Amazon Q Developer CLI and Claude Code. Nothing else has shipped despite “future plans” for other tools.

The supervisor runs on Amazon Bedrock, AWS’s managed service for foundation models. You need AWS credentials, Bedrock access, and an AWS account. It’s open source code you can’t run without AWS infrastructure. This is lock-in you should choose consciously.

Everything runs in tmux sessions. Great for transparency, but it’s another dependency with a learning curve. Running this in CI/CD adds complexity.

Multiple agents mean multiple API calls, more token usage, higher latency. For simple tasks, this is wasteful overkill. You need to be selective about when orchestration overhead is worth it.

This is infrastructure for developers comfortable with AWS, tmux, and orchestration concepts. It’s not polished. Limited early reactions on social media praise the privacy focus but flag AWS lock-in and tmux hurdles as barriers to adoption.

Why It Matters
#

The interesting part isn’t CAO specifically. It’s the shift from “AI tool as standalone assistant” to “AI tools as orchestrated teams.”

Single-agent tools hit walls. Context windows don’t solve everything. At some point, more context just means more noise. Multi-agent architectures divide cognitive labor. Each agent has a focused job. The supervisor ensures pieces fit together.

We’re seeing this everywhere. OpenAI’s Swarm. LangGraph. CrewAI. AutoGPT. The underlying idea is the same: complex tasks need coordination, not just more context. Specialization plus orchestration beats generalization with bigger context windows.

The question: does this remain infrastructure developers explicitly configure, or does it become invisible? CAO is clearly “you configure this.” But the long-term direction is probably toward tools that orchestrate automatically, with developers intervening only when defaults fail.

Getting Started
#

If you want to experiment with CAO:

You need an AWS account with Bedrock access and permissions to use Claude models. Install Amazon Q Developer CLI or Claude Code. Install tmux (brew install tmux on macOS). Clone the repo: git clone https://github.com/awslabs/cli-agent-orchestrator. The README has configuration examples and workflows.

Realistically, plan to spend an afternoon getting this working. This isn’t a tool you spin up in 10 minutes.

Should You Use This?
#

Use CAO if you’re handling complex, multi-disciplinary tasks where single agents struggle. If you’re already on AWS and Bedrock, integration is straightforward. You need comfort with tmux and orchestration concepts.

Skip it if your tasks are straightforward. If you’re not on AWS or want to avoid lock-in, skip it. If you need something polished, this isn’t it.

For most developers, single-agent tools remain the right choice. For teams tackling large-scale modernizations or complex migrations, CAO offers a pattern worth exploring.

Check out the GitHub repository and the AWS blog post.

The future of AI tooling is coordination, not just capability. CAO is AWS’s bet on how that works. Whether it becomes standard or just one experiment, the pattern it represents is where things are headed.

Amazon Bedrock · PiniShv

CLI Agent Orchestrator: When One AI Agent Isn't Enough

The Problem #

How It Works #

Example: Mainframe Modernization #

The Reality Check #

Why It Matters #

Getting Started #