Maxxwell by Rindler
Writing

Running a small coding-agent swarm in one window

2026-10-10

By the end of this tutorial, you’ll have a small swarm of coding agents working on one feature, all visible in a single Maxxwell window. You’ll:

By the end of this tutorial, you’ll have a small swarm of coding agents working on one feature, all visible in a single Maxxwell window. You’ll:

This is about attention, not more automation. Your agents already write code fast; this is how to stop being the bottleneck.

Prerequisites

You need a few things ready before step 1:

1. Define a single feature goal the swarm will work around

The first failure mode with multiple agents is vagueness. "Improve search" is how you get three sessions building three different things.

Define one feature and write it down as a brief Maxxwell will use.

Example goal

Write the brief as a short spec

Put this in a scratchpad file that you’ll paste into Maxxwell later, e.g. maxxwell-brief.md:

Feature: Add IP-based rate limiting to public /search endpoint in service-search.

Constraints:
- Keep existing behaviour for /search/internal callers.
- Do not change response schema for public /search.
- Add unit tests under tests/rate_limit/, plus integration tests hitting /search.
- Configurable limits per environment via env vars: SEARCH_RATE_LIMIT_PER_MINUTE.

Deliverables:
- Implementation in service/search_rate_limit.py (or equivalent module).
- Wiring into the HTTP handler for /search.
- Tests passing under `pytest`.
- Short docs note in docs/search.md.

Common failure

2. Start Maxxwell and create your orchestrator session

Maxxwell’s orchestrator is itself a coding-agent session, but with a different job: keep the swarm aimed and report back what landed.

You talk to the orchestrator instead of to twelve terminals.

Desktop app

  1. Launch Maxxwell.
  2. Click “New Orchestrator” (or equivalent button).
  3. Choose your model runtime, e.g.:
    • "Claude Code (local)"
    • "Codex CLI"
  4. Paste the brief from maxxwell-brief.md into the orchestrator composer.
  5. Add explicit instructions:
You are the orchestrator for a small swarm of coding agents.
Your job:
- Break down the feature into concrete tasks.
- Assign tasks to worker sessions.
- Track which worker is working, idle, or blocked.
- Bring me only decisions, blockers, and review requests.

Do NOT run commands yourself; propose changes in natural language.
  1. Hit Send.

CLI example

If you prefer the CLI:

maxxwell orchestrator \
  --name search-rate-limit-orchestrator \
  --runtime claude-code \
  --brief ./maxxwell-brief.md

This starts a real agent session that Maxxwell treats as the orchestrator seat.

Common failure

3. Wire your existing coding agents in as workers

Your agents stay your agents. Maxxwell attaches to unmodified terminal sessions; it doesn’t replace Claude Code, Codex, Cursor, or whatever scripts you already trust.

Pick 2-4 workers for your first swarm.

Start workers in terminals

Example: two Claude Code terminals and one Cursor agent.

# Worker 1: Claude Code on backend implementation
claude-code --session search-rate-limit-impl

# Worker 2: Claude Code on tests
claude-code --session search-rate-limit-tests

# Worker 3: Cursor agent on docs
cursor-agent --session search-rate-limit-docs

Each of these is a normal agent session you could run without Maxxwell.

Attach workers in Maxxwell

In the Maxxwell window:

  1. Click “Add Worker Session”.
  2. Choose Attach to existing terminal session.
  3. Select search-rate-limit-impl.
  4. Repeat for search-rate-limit-tests and search-rate-limit-docs.

Now you have one orchestrator and three workers, all visible in a single window.

What Maxxwell does here

Quitting Maxxwell simply detaches. It does not kill your workers.

Common failure

4. Set explicit roles and initial tasks for each worker

Now that the sessions are wired in, give them distinct jobs. This is how you reduce overlap.

Go back to the orchestrator seat in Maxxwell and spell out the plan.

Example orchestrator message

We have three workers:

- Worker 1 (search-rate-limit-impl): owns backend implementation.
- Worker 2 (search-rate-limit-tests): owns unit + integration tests.
- Worker 3 (search-rate-limit-docs): owns docs/search.md updates.

Plan the tasks as:

1. Impl: design a small rate limiting module with env-configurable limits.
2. Impl: wire it into the /search handler, preserving /search/internal.
3. Tests: add unit tests for the rate limiter module.
4. Tests: add integration tests for /search under rate limiting.
5. Docs: add a section documenting limits and error responses.

Assign specific tasks to each worker and ask them to confirm before starting.
Bring me back a short summary of assignments.

The orchestrator replies with something like:

Assignments:
- Worker 1: Tasks 1-2.
- Worker 2: Tasks 3-4.
- Worker 3: Task 5.

I will prompt each worker with their task list and ask for confirmation.
I will mark their state as working/idle/blocked based on their responses.

Maxxwell’s role

Common failure

5. Use session statuses to triage attention in one window

Once work starts, the value is in the dashboard: states per session, not just scrolling logs.

Maxxwell tracks each worker session in a simple state machine:

In practice:

GitHub’s Copilot studies talk a lot about output speed (up to 55% faster coding in one Accenture study), but less about the overhead of babysitting multiple sessions. The Maxxwell statuses are there specifically to cut that overhead.

Maxxwell’s session states turn a swarm of agents into a readable queue of work, with blocked and waiting-on-you sessions surfaced ahead of quietly working ones.

Common failure

6. Keep context tight with Maxxwell’s pressure readout and one-click compact

With several agents on one feature, context is next: long histories turn into expensive, slow, and confused sessions.

Maxxwell exposes a live context-pressure readout per session:

When a worker’s context meter is high:

  1. Click the compact control in that worker lane.
  2. Maxxwell drafts a compacting instruction into the composer, like:
Summarize the last 50 turns of this conversation into a concise plan and state.
Keep:
- Current task list
- Key decisions already made
- Links to relevant files and modules

Drop:
- Back-and-forth that does not change the plan
- Old clarifications and now-resolved questions
  1. You review the drafted instruction.
  2. You press Enter. The agent compacts its own context.

Maxxwell does not automatically compact or recycle context on its own schedule; it tells you when pressure is high and gives you a safe, drafted action. You stay in control.

Common failure

7. Review what landed, resolve blockers, and park the swarm safely

After an hour, your swarm will have produced a mix of code, tests, and questions. The last step is to get a clean return report and leave the system in a stable state.

Ask the orchestrator for a return report

In the orchestrator lane:

Give me a concise return report:
- What has landed (code, tests, docs) and in which branches/files.
- What is currently blocked and why.
- What is waiting on me specifically.
- What is still in progress but not blocked.

Limit to bullet points. I will use this to review and merge.

You’ll get something like:

Landed:
- Rate limiter module in service/search_rate_limit.py (Worker 1).
- Unit tests in tests/rate_limit/test_rate_limiter.py (Worker 2).

Blocked:
- Integration tests for /search blocked on missing test fixture for IP address (Worker 2).

Waiting on you:
- Decision: HTTP 429 body format for rate-limited responses.

In progress:
- Docs section describing rate limits in docs/search.md (Worker 3).

From here:

When you close Maxxwell:

Common failure

FAQ: Troubleshooting Your First Maxxwell Agent Swarm

1. One worker shows "needs sign-in" and never becomes working

Cause: The runtime (Claude, Codex, Cursor, etc.) isn’t authenticated.

Fix:

If it stays stuck, end that worker's terminal session and start a fresh one.

2. A session sits on "possibly stalled" without errors

Cause: The agent stopped emitting tokens but didn’t crash. Could be thinking, could be stuck.

Fix:

You seem to be stalled. Summarize what you were doing and your current plan in 3 bullets.

Maxxwell says "not heard from" when it cannot confirm activity; it doesn’t guess "working".

3. The orchestrator keeps trying to write code instead of coordinating

Cause: The initial brief wasn’t strict enough about its role.

Fix:

You are the orchestrator. Do NOT write code or propose diffs yourself.
Your job is to:
- Assign tasks to workers.
- Track their state.
- Bring me decisions and blockers.

Acknowledge this change in role.

4. Two workers edited the same file in conflicting ways

Cause: Task boundaries were fuzzy; roles overlapped.

Fix:

Worker 1 owns service/search_rate_limit.py only.
Worker 2 owns tests/rate_limit/ only.
Do not assign overlapping file edits.

5. Context meters are red for multiple sessions and responses feel off

Cause: Too much history in each worker; important details are getting pushed out of context.

Fix:

You have just summarized the past context.
Restate your current task and constraints before continuing:
- Task: …
- Constraints: …

This keeps the agent anchored after a compact.

You now have a working pattern for herding a small agent swarm around a single feature without losing context. From here you can scale up - more workers per feature, or multiple features at once - but the recipe stays the same: one written goal, one orchestrator seat, one window, and clear states so you only pay attention where it’s actually needed.