Maxxwell by Rindler
Writing

Setting up a control plane for coding agents

2026-10-23

By the end of this tutorial you’ll have a working control plane for your AI coding agents: Claude Code, Codex, Cursor’s agent, whatever you already run. You’ll.

By the end of this tutorial you’ll have a working control plane for your AI coding agents: Claude Code, Codex, Cursor’s agent, whatever you already run. You’ll use Maxxwell as the concrete example to connect agents, define goals, read session status, and set human checkpoints so parallel work doesn’t quietly go off the rails.

If you want the broader conceptual backdrop first, the pillar guide is here: AI coding agent orchestration: control planes that keep multi-agent work on track.

Prerequisites

Before step 1, you should have:

You do not need: a Maxxwell account, a hosted service, or to change how your agents sign in. Maxxwell runs locally and attaches to tools you already trust.

Common failure at this stage:

Step 1: Install Maxxwell and confirm the control plane comes up

Goal: get a local Maxxwell instance running and see the empty fleet window.

On macOS:

# Using Homebrew (example, adjust for actual tap)
brew tap rindler/maxxwell
brew install maxxwell

On Debian/Ubuntu:

# Example using a .deb
wget https://downloads.maxxwell.dev/maxxwell_latest_amd64.deb
sudo dpkg -i maxxwell_latest_amd64.deb

On Windows:

  1. Download the installer from https://docs.maxxwell.dev/.
  2. Run it with default options.

Then start the desktop app:

maxxwell-desktop

You should see:

Common failures and fixes:

Step 2: Connect your existing coding agents to Maxxwell

Goal: have Maxxwell manage real agent sessions instead of mock entries.

Maxxwell does not replace Claude Code, Codex, Cursor, etc. It opens worker seats by talking to the runtimes you already have, often via the terminal or local APIs.

Example: connect an OpenAI-based coding agent via CLI.

# Set your model key as an env var
export OPENAI_API_KEY="sk-your-key-here"

# Start a worker session from the Maxxwell CLI
maxxwell-cli worker start \
  --name api-refactor \
  --provider openai \
  --model gpt-4.1-mini \
  --workdir ~/code/your-repo

Example: connect Claude Code as a worker.

# Assuming Claude Code is installed and signed in
maxxwell-cli worker start \
  --name claude-ui \
  --provider claude-code \
  --attach-existing \
  --workdir ~/code/your-repo

Key points:

Common failures and fixes:

Step 3: Open an orchestrator seat and define a goal

Goal: stop talking to twelve terminals and start talking to one briefed orchestrator that coordinates them.

In the Maxxwell desktop app:

  1. Click New Orchestrator.
  2. Choose your model provider (e.g. Claude, OpenAI).
  3. Set the working directory to your repo.
  4. Paste a written brief.

Example orchestrator brief:

Project: add a feature flag system to the billing service.

Goal:
- Introduce a feature flag module in `billing/feature_flags.py`.
- Wrap the new discount calculation in a flag called `discount_v2`.
- Add tests in `tests/test_feature_flags.py`.
- Update docs in `docs/billing-flags.md`.

Constraints:
- No direct pushes to `main`.
- All changes must be covered by tests.
- Use existing logging patterns.

Use 2-3 worker sessions:
- One for code changes.
- One for tests.
- One for docs.

Report:
- What has landed (merged / committed).
- What is waiting on my approval.
- What is blocked.

Start the orchestrator session. You now have:

You can talk to the orchestrator in natural language instead of manually juggling every worker.

Common failures and fixes:

Step 4: Read the fleet at a glance

Goal: know which sessions are doing useful work and which are wasting cycles or waiting on you.

Maxxwell tracks a readable state per session. The typical states include:

When you glance at the fleet window:

Common failures and fixes:

Step 5: Establish explicit human checkpoints where the agent must stop

Goal: keep control of what lands on main by inserting deliberate pauses where the person has to press enter.

Maxxwell’s control surface uses drafts rather than acts:

You can turn this into explicit checkpoints.

Example: gate merges behind a “review required” step.

  1. In your orchestrator brief, add:
    Never run `git merge` or push commits without my explicit approval.
Instead, draft the exact command and wait for me to send it.
  1. When the orchestrator wants to merge test-passing work, it will:
    • Draft something like: git merge feature/flags -m "Add discount_v2 feature flag"
    • Leave it unsent in the composer.
  1. You review:
    • The command
    • The worker’s diff
    • The test status
  1. You press enter only if it’s correct.

Similarly, gate risky actions:

Concrete CLI example of a checkpointed action:

# Orchestrator proposes a command; Maxxwell drafts it
# You see this in the composer:
#   RUN: pytest -q tests/test_feature_flags.py

# You inspect the diff and only then send it:
pytest -q tests/test_feature_flags.py

Common failures and fixes:

Step 6: Run a parallel feature build and monitor it end-to-end

Goal: practice a full run where multiple agents work in parallel under the control plane, with clear visibility and checkpoints.

Let’s use a concrete scenario: add a rate limiter to an HTTP service.

6.1 Create worker sessions for code, tests, and docs

cd ~/code/http-service

maxxwell-cli worker start \
  --name rate-limit-code \
  --provider claude-code \
  --workdir .

maxxwell-cli worker start \
  --name rate-limit-tests \
  --provider openai \
  --model gpt-4.1-mini \
  --workdir .

maxxwell-cli worker start \
  --name rate-limit-docs \
  --provider claude-code \
  --workdir ./docs

6.2 Brief the orchestrator for the feature

In the Maxxwell app, create an orchestrator with:

Project: add a per-user rate limiter to the HTTP API.

Goal:
- Implement rate limiting middleware.
- Return HTTP 429 on limit exceeded.
- Add integration tests for normal and exceeded usage.
- Update `docs/rate-limits.md`.

Workers:
- `rate-limit-code` for implementation.
- `rate-limit-tests` for tests.
- `rate-limit-docs` for documentation.

Checkpoints:
- Draft all `pytest` commands instead of running them.
- Draft all `git commit` and `git push` commands.
- Report status: working / idle / waiting on me / blocked / done.

Start the orchestrator and give it the initial instruction:

Plan and start work across the three workers to implement the rate limiter.
When I ask, report what has landed and what is waiting on me.

6.3 Watch status and clear blockers in order

As work progresses, watch the fleet window:

Address blockers:

When everything is green:

Common failures and fixes:

Step 7: Use Maxxwell with a team without giving up local control

Goal: make the control plane useful when several developers are running agents at once.

Maxxwell is free forever for individuals and paid for teams, but the mechanism stays the same:

Team workflow patterns that work well:

Common failures and fixes:

FAQ / Troubleshooting

1. How is a control plane like Maxxwell different from just using tmux scripts?

Tmux gives you panes. A control plane gives you state and policy:

If you’re happy reading raw logs in ten panes and deciding everything manually, tmux is fine. Once you start asking “which of these is stuck?” or “what landed?”, a control plane answers that directly.

2. Does Maxxwell automatically correct agents that drift from the goal?

No. The conducting is real, the autopilot is not.

Maxxwell:

It does not automatically detect drift and re-aim a session for you. You stay responsible for course corrections.

3. What happens to sessions if I quit Maxxwell or close my laptop?

Work outlives the window:

Closing your laptop lid is not treated as “discard this work”.

4. Can I use Maxxwell if I’m only running one AI coding agent?

You can, but it’s probably overkill.

Maxxwell shines when:

If you only ever run a single copilot session, you won’t see much benefit from a control plane.

5. Does Maxxwell store my code or send it to a server?

No.

Your model traffic goes to whatever provider you already use (Anthropic, OpenAI, etc.), under your own keys and subscriptions.

No infographic charts are necessary for this tutorial; the value is in the concrete commands and workflows rather than in extra data visualization.