I Hit Claude Code's Limits. So I Gave It Workers.
Claude Code is my primary coding tool. I upgraded to the $100/month Max plan because the $20 Pro plan wasn’t enough to do serious work with Opus. But even at that tier, I started hitting rate limits. Running multiple projects in parallel, using Playwright MCP for visual testing, juggling several conversations at once. When you’re deep in a flow and the rate limit kicks in, it breaks your momentum completely.
I use ChatGPT daily as a general-purpose chatbot, but all my coding happens in Claude Code. That meant the Codex capacity bundled with my ChatGPT subscription was going completely untapped. I didn’t want to switch to Codex CLI and manage a separate workflow. What I wanted was for Claude Code to delegate tasks to Codex in the background, without me ever leaving Claude Code.
That’s the idea behind claude-ringleader. Claude stays the ringleader. It plans, decomposes, and reviews. Codex and Gemini handle the scoped implementation work. Shell scripts and file-based handoff keep the whole thing transparent. No framework, no dependencies beyond the CLIs.
The Problem
Claude Code is the best planning and orchestration interface I’ve used for coding. It understands full project context, it reviews well, it makes good architectural decisions. But when you’re running multiple projects and pushing the limits of your plan, every token you can save matters.
Not every task needs Claude’s full attention. Writing a utility function, fixing a failing test, reviewing a diff: these are scoped tasks with clear inputs and expected outputs. They’re perfect candidates for delegation to a different model.
The manual alternative is painful. You open a second terminal, fire up Codex CLI, paste in the context, wait for the result, copy it back, and then have Claude review it. That workflow is slow and fragile. You lose context switching between tools, you lose momentum, and you end up spending more time managing the process than doing the actual work.
What I wanted was simple. Claude stays in charge. It decides what to delegate, dispatches the task to the right worker, gets the result back, reviews it, and keeps going. I never leave Claude Code.
How It Works
The architecture is intentionally straightforward:
You <──> Claude Code (foreman: plans, reviews, decides)
│
├── delegate.sh ──> codex exec ──┐
│ ├── artifacts/{task-id}/
├── delegate.sh ──> gemini -p ──┘ task.md, result.md,
│ status, meta.json
├── workflow.sh ──> multi-step plans (parallel, mixed providers)
├── poll.sh ──────> checks task status
├── result.sh ────> reads task output
├── cost.sh ──────> aggregates token usage
└── worker-status.sh ──> rate limit monitoringClaude Code calls shell scripts to hand off work. Workers execute in the background and write results to artifact directories. Claude reads the results back and continues. Everything flows through plain files.
A basic delegation looks like this:
delegate.sh -d /path/to/project "Implement input validation in src/api/users.ts"That sends the task to Codex by default. If you want Gemini instead, you add -w gemini. If you want to fire it asynchronously and check later, you grab the task ID and poll for completion:
delegate.sh -d /path/to/project "Fix the failing tests"
poll.sh $(cat .last-task-id) # check status
result.sh $(cat .last-task-id) # read outputWhere things get more interesting is cross-provider QA. You can have one model implement and a different one review:
TASK=$(delegate.sh -w codex -d /project "Implement auth middleware")
delegate.sh -w gemini -d /project -c artifacts/$TASK/result.md "Review this implementation"Different models catch different things. A review from a different provider is more valuable than a second review from the same one, because each model has different blind spots and different strengths. This ended up being one of the features I use the most.
For larger tasks, you define a workflow plan with dependencies between steps. Steps without dependencies run in parallel (wave-based execution), and each step can specify its own worker and model:
# Plan: Add user auth
working_dir: /path/to/project
## step: schema
worker: codex
task: Create the users table migration
## step: middleware
worker: gemini
depends_on: schema
task: Implement JWT auth middleware
## step: review
worker: codex
depends_on: middleware
task: Review the auth middleware implementationworkflow.sh plan.md # execute (parallel when possible)
workflow.sh --dry-run plan.md # preview wave assignmentsIn this example, the schema step runs first. Once it completes, the middleware step runs. Then the review step. If the plan had multiple independent steps, they’d run in the same wave, in parallel. When you have a complex plan with ten steps where six of them are independent, you want those six running simultaneously, not one at a time.
Why Bash
I considered building this in Python or TypeScript. I went with bash instead, and it turned out to be the right call.
The main reason is debuggability. When something fails, the most important thing is understanding exactly what happened. With file-based artifacts, everything is sitting in a directory you can browse: the prompt that was sent, the response that came back, the exit code, any error output. There’s no database to query, no hidden state, no abstraction layers to dig through.
The whole system is just shell scripts and the three CLIs, plus the python3 that already ships on your machine for parsing JSON. No package manager, no virtual environments, no framework updates. You clone it and it works. Each script is short enough to read in a couple of minutes. There are no background processes or persistent services to manage. Every invocation is independent, which keeps the system predictable and easy to reason about.
That simplicity turned out to be one of the most valuable design decisions. When you’re coordinating work across multiple AI providers, the last thing you want is complexity in the coordination layer itself.
What Else It Does
Beyond basic delegation and workflows, a few other capabilities ended up being important in practice.
Rate limit detection connects directly to why I built this in the first place. When a worker hits a rate limit, the system detects it and fails fast instead of wasting time on retries. When Codex is throttled, you route work to Gemini. When Gemini is throttled, you route to Codex. Having multiple providers isn’t just about getting different perspectives on a problem. It’s practical resilience.
Every task produces a structured artifact directory with the original task, the full prompt, the result, timing and token metadata, and any error output. You can see exactly what was asked and what came back, which matters when you’re delegating work to models and want to understand how they interpreted your instructions.
Cost and token tracking aggregates usage across workers, so you can see what you’re actually consuming. Tasks can also be retried with error context automatically included, so the worker knows what went wrong on the previous attempt. And each step in a workflow plan can specify not just which worker to use, but which model, so you can use a more capable model for complex tasks and a faster one for simple fixes.
Getting Started
Prerequisites
- Claude Code (installed and authenticated)
- Codex CLI (installed and authenticated)
- Gemini CLI (optional, installed and authenticated)
- Bash 4+ and Python 3 (Python is only used for JSON parsing inside the scripts)
One practical note on keeping Codex authenticated: like any Codex CLI use, the login lapses now and then, so for long unattended runs you will occasionally re-run codex login to refresh it. That is the CLI’s normal auth lifecycle, not anything ringleader adds.
One-command install
curl -fsSL https://raw.githubusercontent.com/StanShyshkin/claude-ringleader/main/install.sh | bashThe installer adds the scripts to your PATH and configures Claude Code automatically.
Manual install
git clone https://github.com/StanShyshkin/claude-ringleader.git ~/.claude-ringleader
export PATH="$HOME/.claude-ringleader/bin:$PATH"For manual installs, add this line to your project’s CLAUDE.md so Claude Code knows about the delegation system:
For task delegation to Codex/Gemini, see ~/.claude-ringleader/CLAUDE.mdHow It Compares
There are about half a dozen tools in this space, including OpenAI’s official codex-plugin-cc, which has tens of thousands of stars. Most of these focus on single-task delegation: send a task to Codex, get a result back. That’s useful, and if that’s all you need, any of them will work.
What I was looking for was different. I needed workflow orchestration with dependency graphs, so I could break a large task into steps that run in the right order with parallel execution where possible. I needed cross-provider support, so I could use Codex and Gemini as interchangeable workers and get different perspectives on the same problem. And I wanted Claude to own the full lifecycle: planning, decomposition, delegation, review, and the final decision on whether the work is good enough.
The other major difference is the implementation philosophy. claude-ringleader is pure bash with file-based handoff. Every script is readable, every artifact is inspectable, and there’s nothing running in the background that you can’t see. When something fails, the debugging process is cat artifacts/{task-id}/stderr.log. That transparency matters when you’re orchestrating multiple AI models and need to understand exactly what happened.
These tools solve overlapping problems in different ways. This is the one I built because it matched how I actually work.
Looking Ahead
I built claude-ringleader for my own workflow. It solved a problem I was running into daily: getting more out of the AI subscriptions I was already paying for, without switching between tools or changing how I work. Once it was stable enough that I was relying on it for real projects, I figured anyone else hitting similar rate limits, or sitting on unused Codex or Gemini capacity from subscriptions they already have, might find it useful too.
The project is MIT licensed and available on GitHub. If you’re using Claude Code as your primary tool and want to stretch your usage by putting your other subscriptions to work, give it a try.
If you’re exploring similar setups or have thoughts on multi-agent workflows, I’d love to hear about it. Feel free to use the contact form below or reach out on LinkedIn.