Writing

Consolidating scattered agent sessions in one pane

2026-10-12

By the end of this tutorial you’ll have your existing Claude, Codex, Cursor-agent, and other coding agents registered into Maxxwell, all visible in one pane.

By the end of this tutorial you’ll have your existing Claude, Codex, Cursor-agent, and other coding agents registered into Maxxwell, all visible in one pane, tagged by repo/feature, and marked when they’re stalled or quietly building the wrong thing.

You keep your agents and terminal workflow. Maxxwell just becomes the place you look first.

Prerequisites

Before step 1, make sure you have:

A machine running macOS, Linux, or Windows
At least two existing coding-agent workflows (e.g. Claude Code in a browser, Codex in a terminal, Cursor-agent in VS Code)
Your own model access: Claude or OpenAI API key / subscriptions
Git installed and a couple of active repos
Comfort with a terminal and basic shell commands

If you’re also comparing other orchestration tools (Herd, Helmor, ctx, etc.), the related deep-dive is here: Maxxwell workflow comparison: herding coding agents without adding more noise.

1. Install Maxxwell and Run the First Empty Pane

You start by getting Maxxwell running locally with no agents attached yet.

Desktop app

On macOS / Windows / mainstream Linux distros:

Download the desktop app from maxxwell.dev.
Install as you would any native app.
Launch it. You’ll see an empty fleet pane and an option to start an orchestrator.

CLI

If you prefer the terminal, install the CLI (macOS / Linux):

# macOS (homebrew)
brew tap rindler/maxxwell
brew install maxxwell

# Linux (example for Debian/Ubuntu via curl script)
curl -sSL https://maxxwell.dev/install.sh | bash

# Verify
maxxwell --help

Run the CLI once to create the local config:

maxxwell pane

Common failure:

Problem: CLI exits with “command not found”.
Fix: Confirm install path is on $PATH (or reload shell), then rerun maxxwell pane.

At this point Maxxwell is running and showing a blank fleet. No agents yet.

2. Wire in Your Existing Model Access (Claude / OpenAI)

Maxxwell doesn’t replace Claude, Codex, or Cursor; it talks to them using your existing credentials.

You configure this once.

Configure Claude

If you use Claude Code or Claude API:

# Set Claude API key in Maxxwell config
maxxwell config set claude.api_key YOUR_CLAUDE_KEY

# Optional: set default model
maxxwell config set claude.model claude-3-5-sonnet

Configure OpenAI / Codex

For OpenAI-based agents or Codex:

# Set OpenAI key
maxxwell config set openai.api_key YOUR_OPENAI_KEY

# Example: default code model
maxxwell config set openai.model gpt-4.1

In the desktop app this is the same, just via the Settings panel: paste keys, pick defaults.

Common failure:

Problem: Agents show as needs sign-in in the pane.
Fix: Check the key (typo / expired), re-run maxxwell config set …, and restart the pane. Maxxwell will flip the state to not started once the key is valid.

Maxxwell now can start agent workers using the same models you already use elsewhere.

3. Register Existing Repos and Create Fleet Tags

To keep the pane readable, start by teaching Maxxwell about your repos and how you want to group agents.

Register repos

From your terminal, in each repo root:

cd ~/work/service-a
maxxwell repo register . --name service-a

cd ~/work/frontend-app
maxxwell repo register . --name frontend-app

Each repo register call adds a local record Maxxwell uses when you tag sessions.

Define feature tags

Next, create tags for features or workstreams:

maxxwell tag create service-a:auth
maxxwell tag create service-a:billing
maxxwell tag create frontend-app:dashboard
maxxwell tag create frontend-app:design-system

You’ll see these appear in the desktop app as filters and tag options when you create or edit a lane.

Common failure:

Problem: A repo shows as unknown in the pane.
Fix: Run maxxwell repo register from that repo’s root, not a subdirectory, and give it a stable --name. Maxxwell keys lanes off that mapping.

Now you’ve got the scaffolding to categorize your agents by repo and feature.

4. Spawn Worker Agents as Real Sessions Under Maxxwell

With repos and tags in place, you start moving your agent herd into Maxxwell. The key point: these are still real terminal sessions you can attach to.

Start a worker for a backend feature

In the service-a repo:

cd ~/work/service-a

# Start a Claude Code worker for auth
maxxwell worker start \
  --name service-a-auth-claude \
  --model claude-3-5-sonnet \
  --tag service-a:auth

This does three things:

Spawns a real coding-agent session attached to the repo
Registers it in the pane with state not started
Marks it with service-a:auth so you can filter by feature

Workers are your own unmodified tools — claude, codex, cursor-agent — running in real terminal sessions. Attach to one directly if you want to see the raw terminal:

maxxwell worker attach service-a-auth-claude

Start another worker for the frontend

cd ~/work/frontend-app

maxxwell worker start \
  --name frontend-dashboard-codex \
  --model gpt-4.1 \
  --tag frontend-app:dashboard

Open the desktop app: you should now see two lanes, each with its repo, current model, tag, and a state like not started or working once you give them a brief.

Common failure:

Problem: Worker exits immediately, lane marked dead.
Fix: Attach with maxxwell worker attach … and scroll the logs. It’s almost always a missing dependency (e.g. your local Claude runtime not installed) or an invalid model name.

At this point, some of your “herd” is under Maxxwell’s control pane instead of scattered across tabs and terminals.

5. Bring External Browser-Based Agents Into the Pane

You probably have Claude Code or Cursor-agent running in a browser or IDE. Maxxwell doesn’t own those processes, but it can still track them as lanes with states.

The pattern is: you create a “manual” lane that represents that external agent, and keep its state in sync by talking to the orchestrator.

Create a manual lane for a Claude Code browser session

In Maxxwell’s desktop app:

Click Add lane → Manual session.
Set:
- Name: service-a-auth-claude-browser
- Repo: service-a
- Tags: service-a:auth
- Source: external (browser)
Initial state: working if it’s already mid-task.

Alternatively via CLI:

maxxwell lane add \
  --name service-a-auth-claude-browser \
  --repo service-a \
  --tag service-a:auth \
  --source external \
  --state working

Whenever you pause or resume that browser session, you tell the orchestrator to update the lane state. Example:

“Set service-a-auth-claude-browser to idle, I’m not answering it for the next hour.”

The orchestrator drafts the state change and you confirm it; you always press enter.

Common failure:

Problem: Manual lane never updates and looks stale.
Fix: Treat the orchestrator as the source of truth: when the external agent changes phase (working → blocked → done), state it in language and let the orchestrator update the lane.

Now both local workers and external agents are visible in one pane.

6. Use the Orchestrator Seat Instead of Twelve Terminals

The orchestrator seat is just another coding-agent session, briefed to manage the others. You talk to it instead of juggling individual terminals.

Start the orchestrator

From any repo (or a neutral workspace):

maxxwell orchestrator start \
  --name main-orchestrator \
  --model claude-3-5-sonnet

Give it a written brief that matches how you think about your fleet. Example:

You are the orchestrator for my agent fleet.

Sessions represent feature work across these repos:
- service-a: auth, billing
- frontend-app: dashboard, design-system

Your job:
- Track which lanes are working, idle, waiting-on-me, blocked, done, or dead.
- Ask for my decision when multiple sessions conflict.
- Draft, but never send, commands or messages that would change the fleet.
- Always separate:
  - What has landed in git
  - What is still drafts / unmerged
  - What is waiting on my input

Once this lands, you can say things like:

“Summarize service-a:auth work across all lanes and tell me which ones are waiting on me.”

The orchestrator replies with a clear report: which lanes are working, which are waiting on you, which are blocked, and what they’ve done so far.

Common failure:

Problem: Orchestrator starts issuing commands directly to workers.
Fix: Re-emphasize in the brief: it drafts rather than acts. If it suggests a message or command, it must write it into the composer unsent. You stay the one who presses enter.

This is where you start feeling the attention relief: one seat that knows the state of the herd.

7. Tag, Filter, and Read Agent States to Spot Stalls

Now that everything is visible, you need to see at a glance which agents are productive, idle, or going off-track.

Maxxwell exposes lane states like:

working
idle
waiting on you
blocked
needs sign-in
not started
done
dead
not heard from

Filter by repo and feature

In the desktop pane:

Filter by repo = service-a and tag = service-a:auth to see only auth-related agents.
Sort by state to bring blocked or waiting on you lanes to the top.

CLI example:

maxxwell fleet list --repo service-a --tag service-a:auth --sort state

Maxxwell’s context-pressure readout shows how full a session’s context is, with tiered warnings. When you see warnings:

Hit one-click compact on the worker
Or tell the orchestrator: “Compact context for service-a-auth-claude and restate its goal in one paragraph.”

Common failure:

Problem: Lane shows working but hasn’t produced anything useful.
Fix: Attach to the session, skim the last exchange, and either adjust the brief or mark it dead and spin up a fresh worker with a clearer goal.

At this point you can answer “which of these is stuck and which is just slow?” by glancing at one pane.

8. Surface Agents Quietly Building the Wrong Thing

The silent failure mode is the agent confidently implementing the wrong requirement. Maxxwell doesn’t auto-correct drift, but it gives you enough visibility to catch it early.

Create goal notes per lane

For each lane, record the goal in a short, explicit note. Example via CLI:

maxxwell lane note set service-a-auth-claude \
  "Goal: add MFA to login flow using TOTP, no changes to signup."

In the app, that note sits at the top of the lane.

When reviewing a session, ask the orchestrator:

“Compare the last 10 messages in service-a-auth-claude with its goal note. Is it still building MFA for login only?”

The orchestrator will:

Read the goal note
Read the recent transcript
Tell you explicitly if the agent seems to be implementing something else (e.g. refactoring signup instead of login)

Remember: it does not automatically re-aim the session. It only surfaces the mismatch so you decide.

Common failure:

Problem: Wrong work lands in git before you notice.
Fix: Use a simple discipline:
- Before merging, ask the orchestrator: “Summarize what landed in the last commits from service-a-auth-claude vs its goal note.”
- If they differ, keep the branch, but block the merge and restate the goal in a new lane.

This is where Maxxwell earns its “agent-of-agents” posture: it doesn’t try to be smarter than you; it just keeps the work visible and comparable to stated goals.

9. Respect That Work Outlives the Window

One last operational detail: Maxxwell doesn’t kill sessions when you quit.

Quitting the app detaches; it doesn’t terminate workers.
Closing your laptop is not a decision to throw away an hour of agent work.

When you reopen the app or pane later:

Existing workers are still running, and you can attach to them again
Anything Maxxwell couldn’t confirm shows as not heard from instead of pretending it’s working

Common failure:

Problem: You assume a closed app killed the agent, start a duplicate worker.
Fix: On reopen, run:
```
maxxwell fleet list
```

If a lane is still working, attach instead of spawning a new one.

With that, you’ve effectively turned a chaotic herd of agent tabs, browser windows, and terminals into a single Maxxwell control pane, with repo/feature categorization and legible states.

FAQ / Troubleshooting

How do I onboard existing AI agents into Maxxwell without rewriting them?

You don’t modify the agents at all. For local ones, start them via maxxwell worker start so Maxxwell owns the session lifecycle and repo attachment. For browser/IDE agents, create manual lanes that represent them and keep their state updated via the orchestrator. All workers remain your existing tools: Claude, Codex, Cursor-agent, or your custom scripts.

Can Maxxwell detect agent drift or misdirected work automatically?

No. Maxxwell does not automatically detect drift, re-aim sessions, recycle context, or restart stopped work. What it does is:

Keep a goal note per lane
Expose clear states (working, blocked, waiting on you, etc.)
Give you a live transcript and context-pressure readout

You can ask the orchestrator to compare recent work to the goal and tell you if it looks wrong, but you choose how to correct it.

How do I categorize agents by repo or feature in Maxxwell?

Use maxxwell repo register in each repo root to give Maxxwell a stable name for that codebase. Then create tags with maxxwell tag create repo:feature, and apply them when starting workers (--tag) or adding lanes. In the pane, filter by repo and tag to see all agents touching a single feature across multiple tools.

What states should I care about when reducing my own bottleneck?

Watch these first:

waiting on you - agents blocked on answers you haven’t given
blocked - agents stuck on missing deps or failing tests
not heard from - agents that looked working but whose state Maxxwell can no longer confirm

Deal with these before spinning up new sessions. That alone drops the “I have eight sessions open and I am the slowest part of this” feeling.

How does Maxxwell compare to Herd, Helmor, or similar orchestration tools?

Tools like Herd, Helmor, and ctx wrap agents inside their own IDE-style workspace and often introduce hosted control planes or opinionated landing flows. Maxxwell takes a different stance:

It runs locally, with no required server or sign-up for individual use.
It treats your agents as workers in real terminal sessions you can attach to directly.
It focuses on readable states, an orchestrator seat you brief in language, and fleet controls that draft rather than act.

If you care about keeping your existing agent setup and just want to stop being the bottleneck, Maxxwell sits above your tools instead of replacing them.