Maxxwell by Rindler
Writing

Herding coding agents across multiple repos

2026-10-15

By the end of this tutorial, you will have a single Maxxwell herd orchestrating multiple coding agents across several repos for one feature. You’ll see.

By the end of this tutorial, you will have a single Maxxwell herd orchestrating multiple coding agents across several repos for one feature. You’ll see end-to-end status in one view instead of babysitting a half-dozen terminals.

You’ll:

This isn’t about theory. It’s the concrete workflow you’d use for “Add SSO across web + API + auth-service” or any other multi-repo feature.

Prerequisites

Before step 1, you should have:

Common failure here: trying to drive a remote SaaS agent that only exists in a browser tab. Maxxwell orchestrates real terminal-based sessions; your workers must be callable from a shell.

1. Create feature branches and worktrees for each repo

First, give each repo a clean working tree dedicated to this feature. This keeps your agent sessions isolated and lets Maxxwell map “one lane per repo” without stepping on existing work.

From a parent directory:

# 1) Clone or ensure repos exist
cd ~/dev

git clone [email protected]:acme/company-api.git
git clone [email protected]:acme/company-web.git

# 2) Create feature branches
cd company-api
git checkout -b feature/sso-login

cd ../company-web
git checkout -b feature/sso-login

If you prefer git worktree for parallel branches (recommended for multi-repo features):

cd ~/dev/company-api

git worktree add ../company-api-sso feature/sso-login

cd ~/dev/company-web

git worktree add ../company-web-sso feature/sso-login

You now have a dedicated directory per feature branch:

Maxxwell will later attach one agent session per repo pointing at these directories.

Common failure: mixing feature work into your main working copy. That makes it harder to tell which terminals belong to the feature and which are doing something else.

2. Start Maxxwell and define a single feature goal

The “herded” part of the workflow starts with a single written goal. Everything else is just sessions attached to that goal.

Launch Maxxwell:

In the desktop app, create a new orchestrator seat with a clear brief:

Goal: Implement SSO for Acme web and API

Scope:
- Add OAuth2 login for the company-web frontend using our existing identity provider
- Update company-api to validate tokens from the IdP and add user context to requests
- Ensure existing local login continues to work
- Tests and integration checks must pass in each repo

Constraints:
- Do not commit directly to main
- Prefer minimal dependency changes

This orchestrator is itself a real coding-agent session, started from this brief. You’ll talk to it instead of juggling a dozen terminals.

Common failure: vague goals like “Improve auth.” The orchestrator will still run, but your herd view will be noisy and you’ll spend more time redirecting agents.

3. Attach per-repo worker sessions under that goal

Now wire in the workers: your existing coding agents, one per repo, all tied back to the same goal.

In Maxxwell’s fleet view:

  1. Add a new worker session.
  2. Point it at the company-api feature directory.
  3. Point another at company-web.

Example via CLI (names are illustrative, adapt to your own agent commands):

# API worker session
maxxwell session open \
  --name api-sso \
  --goal "Implement SSO feature across web and API" \
  --cwd ~/dev/company-api-sso \
  --cmd "claude-code --project company-api-sso"

# Web worker session
maxxwell session open \
  --name web-sso \
  --goal "Implement SSO feature across web and API" \
  --cwd ~/dev/company-web-sso \
  --cmd "cursor-agent --project company-web-sso"

In the desktop app, this corresponds to:

Maxxwell now tracks each worker as a lane under that goal. Each lane has a status label:

There’s also a "possibly stalled" overlay if a session sits in one state for too long.

Common failure: reusing one session to hop between repos. Maxxwell will still track it, but you lose clear per-repo context, and it’s harder to debug when something drifts.

4. Group agents by repo in the herd view

With sessions running, make the herd view readable per repo. The goal is: you glance once and know where each repo stands.

In Maxxwell’s herd view (desktop):

  1. Create repo groups
    • Add a group called company-api.
    • Add another called company-web.
  2. Assign sessions to groups
    • Drag api-sso session into the company-api group.
    • Drag web-sso session into the company-web group.

Each group now shows:

If you’re using CLI only, you can still get group-like context by naming sessions consistently:

# Naming pattern: <repo>-<feature>-<role>
maxxwell session list

# Example output (simplified)
# [company-api] api-sso-worker        working
# [company-web] web-sso-worker        waiting-on-you

You can then filter by prefix:

maxxwell session list --filter repo=company-api

Common failure: dumping all sessions into one default group. That recreates the “pile of terminals” problem that Maxxwell is meant to relieve.

5. Configure cross-repo status so the herd shows end-to-end progress

The herd view becomes useful when it tells you how close the feature is, not just each repo in isolation. You’ll set up status signals that reflect cross-repo dependencies.

A minimal pattern that works well:

Step 5.1: Define explicit done/blocked criteria per repo

Capture this in the orchestrator brief or a short status.md file in each repo.

company-api/status.md:

# SSO feature status - API

Done when:
- /auth/login and /auth/callback endpoints implemented
- Token validation middleware present and tested
- Integration tests covering login and token validation pass

Blocked when:
- Identity provider config not available
- Database migration for user table not applied

company-web/status.md:

# SSO feature status - Web

Done when:
- Login page supports "Continue with SSO" button
- OAuth2 redirect flow integrated with /auth/login
- End-to-end tests passing in CI

Blocked when:
- API SSO endpoints not reachable
- API returns invalid or missing user context

Now instruct each agent session explicitly via the orchestrator:

Orchestrator to API worker:
- Implement everything in company-api/status.md until all "Done when" items are satisfied.
- Mark yourself as "waiting on you" when tests need my sign-off.

Orchestrator to Web worker:
- Treat API SSO endpoints as a dependency.
- Pause and set status to "blocked" if the API lane reports blocked.

You send those instructions as messages from the orchestrator seat to each worker. Maxxwell will show in the herd view which lane is blocked versus waiting on you.

Common failure: relying on implicit understanding. If you don’t encode what “done” means per repo, your herd status collapses into vague “still working”.

6. Use fleet controls that draft rather than act

Maxxwell’s fleet controls have one important property: they draft commands and messages instead of executing them. Nothing happens until you press Enter.

Example: pausing all web-related agents while the API refactors.

From the orchestrator seat:

  1. Choose Pause web group (or equivalent fleet control) in the Maxxwell UI.
  2. Maxxwell drafts a message in the composer:
    Pause work on web-sso until API SSO endpoints are stable. Focus only on test and doc updates.
  1. You can edit this message.
  2. You press Enter to actually send it.

Similarly, a fleet control that would run git status in all sessions writes a composed command into the terminal composer but does not run it until you send it.

This matches what most teams want: orchestration without surprise commits. The person still presses Enter.

Common failure: expecting autopilot. Maxxwell does not automatically correct drift, recycle context, restart stopped work, or run goal checks on its own schedule. It gives you controls and visibility; you remain the operator.

7. Monitor context pressure and compact when needed

Multi-repo work usually involves long chats and big diffs, which hit context limits quickly. Maxxwell exposes context pressure per session with tiered warnings.

In the herd view you’ll see, per lane:

When a lane turns yellow or red:

  1. Click Compact on that lane.
  2. Maxxwell runs the compact for that session.
  3. Continue the session without losing the thread.

Common failure: ignoring context pressure and letting agents thrash. That’s how you end up with two sessions rebuilding the same area from scratch.

8. Read the return report instead of polling each session

Once the feature is mostly done, you want a direct answer: what landed, what did the agents decide, and what still needs you?

Maxxwell’s orchestrator seat provides a return report summarizing:

Use this to drive your final review:

  1. Read the report.
  2. Attach to any worker session directly from Maxxwell to inspect changes:
    maxxwell session attach api-sso
  1. Run tests and review diffs:
    cd ~/dev/company-api-sso
npm test
git diff
  1. Once satisfied, push feature branches and open PRs per repo.

This is where Maxxwell earns its keep: instead of walking each session asking “what’s going on?”, you get one structured summary.

Common failure: closing the app and assuming work is gone. Maxxwell detaches from sessions; it doesn’t kill them. Your agents continue running in those terminals.

9. Compare this herded workflow to your tmux scripts

If you’re already orchestrating agents with tmux, shell aliases, or custom scripts, you should evaluate this against that baseline.

Maxxwell gives you:

Other multi-agent tools give their own flavors of orchestration, often with more automation. Maxxwell is opinionated in the other direction: your tools stay yours, the person presses Enter, and the focus is visibility over autopilot.

FAQ / Troubleshooting

How do I know if a session is actually stuck or just slow?

Maxxwell shows per-session states with a "possibly stalled" overlay when a session has stayed in the same state for longer than expected. Combine that with context pressure and recent output:

You can attach to any session directly to inspect what it’s doing.

What if one repo doesn’t need a dedicated agent?

You don’t have to assign a worker to every repo. For simple infra or config repos:

The herd view is still useful; those repos just show as manual lanes.

Can I run different agents in the same herd (e.g., Claude + Codex)?

Yes. Maxxwell treats workers as unmodified tools. You can have:

Each runs as its own terminal session; Maxxwell just orchestrates them. You bring the models and subscriptions you prefer.

How does this help with trust and safety concerns?

Maxxwell doesn’t hide what agents do:

The point is to make agent behavior inspectable, so you can keep using the tools you trust instead of pushing them behind another opaque layer.

What’s the common mistake when teams first try multi-repo herds?

Two, usually:

  1. No single goal. Each session gets its own vague prompt and quickly drifts. Always start from one orchestrator brief.
  2. No explicit done criteria per repo. Without concrete done/blocked definitions, every lane says "working" and you become the bottleneck again.

Solve those, and the herd view starts to show real end-to-end progress instead of noise.