By the end of this tutorial you will have:
By the end of this tutorial you will have:
This is aimed at developers who already run agents like Claude Code or Codex and now want multi-agent orchestration with visibility instead of a black box.
If you want the architectural big picture of planner-style agents before you build, the companion guide is here: Gremor-powered coding agents: where Maxxwell fits above autonomous planners.
You should have the following in place before step 1.
git, node or python (for your sample project), tmux optional but helpful.https://maxxwell.dev and install.brew tap rindler/maxxwell
brew install maxxwellgit clone https://github.com/your-org/sample-api.git
cd sample-apiBefore wiring anything into Maxxwell, pin down the exact loop you want it to supervise. This makes it obvious how many agent sessions you need and what each one is for.
A concrete starter loop:
Write it down in the repo as maxxwell-plan.md so it stays real:
# Maxxwell demo workflow
1. Planner reads this file and the repo.
2. Planner proposes a step-by-step implementation plan.
3. Planner asks for confirmation on the plan.
4. Once confirmed, planner calls cogagent workers to:
- Modify code under `src/`
- Add or update tests under `tests/`
- Run `npm test` after each logical chunk.
5. Planner reports status and waits for human decisions on:
- Risky refactors
- Schema changes
- API surface changes
Common failure here: being vague. If your planner brief is just “build feature X”, Maxxwell will show you a bunch of sessions thrashing. Write the checkpoints where you actually want to be consulted.
Maxxwell works with real processes, not SDK hooks. Your Gremor-style planner should be a CLI program you can run directly.
Example planner script planner.js (Node, simplified):
npm init -y
npm install openai # or your model client
// planner.js
import fs from 'node:fs';
async function main() {
const brief = fs.readFileSync('maxxwell-plan.md', 'utf8');
const repoSummary = 'src/ and tests/ contain the main logic';
console.log('=== GREMOR-STYLE PLAN ===');
console.log('Brief summary:');
console.log(brief.split('\n').slice(0, 10).join('\n'));
// Call your model here to generate steps (omitted for brevity)
const steps = [
'Add endpoint /healthz returning app version',
'Add tests for /healthz',
'Wire endpoint into existing router',
];
console.log('\nPlanned steps:');
steps.forEach((s, i) => console.log(` ${i + 1}. ${s}`));
console.log('\nNext: call cogagent workers for each step.');
}
main().catch(err => {
console.error(err);
process.exit(1);
});
Run it once directly:
node planner.js
If this doesn’t print a clear plan to stdout, fix that first. Maxxwell will show you whatever this prints; you want that stream to be readable.
Common failure: planner only logs JSON or uses a GUI. Make it a plain CLI that prints text.
Next you want cogagent (or your cog-style agents) to run as independent worker sessions. Maxxwell will treat each as a lane.
At minimum, define a shell entrypoint per worker. Example worker-cogagent.sh:
#!/usr/bin/env bash
set -euo pipefail
# Example: wrap a cogagent binary or Python script
# This should drop into an interactive prompt that accepts tasks.
cd "$(git rev-parse --show-toplevel)"
echo "[worker] Starting cogagent in $(pwd)" >&2
# Replace this with your actual cogagent invocation
cogagent --repo . --mode interactive
Make it executable:
chmod +x worker-cogagent.sh
Test it standalone:
./worker-cogagent.sh
# You should see a prompt where you can type instructions like:
# Implement /healthz endpoint with tests.
Common failure: worker script exits immediately after one command. To work well with Maxxwell, the worker should stay running and accept multiple tasks.
Now bring Maxxwell in as the supervision layer.
Desktop app:
CLI:
cd /path/to/sample-api
maxxwell up
The workspace opens with an empty orchestrator seat and no workers yet.
In Maxxwell, the orchestrator is itself a coding-agent session, but here you want it to be the Gremor-style planner.
Desktop:
node planner.jsCLI:
maxxwell session add \
--name planner \
--command 'node planner.js' \
--role orchestrator
Maxxwell treats this as a first-class session: you can see logs, attach a terminal, and mark its state.
Common failure: pointing the orchestrator seat at a one-shot script that exits in 2 seconds. For a richer workflow, have your planner enter a REPL or at least wait for confirmation before exiting.
Desktop:
./worker-cogagent.shCLI:
maxxwell session add \
--name worker-1 \
--command './worker-cogagent.sh' \
--role worker
maxxwell session add \
--name worker-2 \
--command './worker-cogagent.sh' \
--role worker
You now have:
planner).worker-1, worker-2) running cogagent.Each lane in Maxxwell shows a readable state, for example:
workingidlewaiting on youblockedneeds sign-indone or deadnot heard from (Maxxwell refuses to guess)If a lane looks suspicious, click attach (desktop) or:
maxxwell session attach worker-1
and you’re in a real terminal inside that agent session.
Maxxwell’s orchestrator seat is still a coding agent under the hood. You interact with it using language, not buttons.
Create a brief file orchestrator-brief.md:
# Orchestrator brief
You are a planner agent coordinating cogagent workers in this repo.
- Read maxxwell-plan.md and this file.
- Produce a 5-10 step implementation plan.
- Mark each step with an owner: `worker-1` or `worker-2`.
- For each step, draft a concrete instruction in one sentence that can be sent
directly to the worker.
- Ask for my confirmation before contacting workers.
- After each batch of steps, report:
- What landed (files changed, tests run)
- What you decided locally
- What still needs my decision
Update your planner.js to read this brief and to print worker instructions as plain sentences, e.g.
[TO worker-1] Add /healthz endpoint in src/server.js returning app version.
This is what you will feed into cogagent workers via Maxxwell’s composer.
Common failure: planner emits huge paragraphs with three different tasks. Workers respond better to one concrete instruction per line.
Now run the actual end-to-end loop with Maxxwell as the conductor.
Desktop:
CLI:
maxxwell session start planner
Wait until the plan and worker-targeted lines appear in the planner log.
In Maxxwell, fleet controls draft rather than act. A control that would send a message to a worker writes a sentence into the composer; you still press Enter.
Example flow:
[TO worker-1] Add /healthz endpoint in src/server.js returning app version.worker-1 and hit Send to worker.worker-1 composer:Implement a /healthz endpoint in src/server.js returning the app version, with minimal changes.You remain the person who approves every command. This matters when your planner mis-aims a task; Maxxwell does not silently blast instructions across the fleet.
As workers run, Maxxwell shows their state and context pressure (how close they are to running out of context).
working but context pressure is high, you can:waiting on you, click in and answer its question or re-aim it.Common failure: ignoring context pressure. A worker with 10k tokens of context and 142 tool calls since the last file write is almost certainly stuck; compact or restart it on a narrower task.
You now have:
Use that to manage the last mile.
From the planner, emit lines like:
[TO worker-1] Run `npm test` and report any failing tests related to /healthz.
Route them through Maxxwell to the worker. Watch for:
npm test output in the worker lane.working to waiting on you when it asks something.If tests start failing across multiple lanes, you can:
When you pause work, ask the orchestrator seat for a return report. In practice that means prompting your planner:
Summarize:
- What landed in the repo (files and tests added or changed)
- What decisions you took locally
- What you are still waiting on me to decide
Maxxwell keeps this in the orchestrator lane, clearly separated from the worker logs. You can scan one window and see:
At that point you decide what lands on main. Maxxwell does not auto-merge.
Once this is working, make it repeatable.
Maxxwell sessions outlive the app:
CLI:
maxxwell sessions list
# See existing planner and worker sessions
maxxwell session attach worker-1
Check in:
planner.jsworker-cogagent.shmaxxwell-plan.mdorchestrator-brief.mdThis turns your once-off experiment into a documented, versioned agent stack other team members can run.
Common failure: leaving all this in shell history and ad-hoc terminals. The next person then “re-discovers” wiring instead of iterating it.
Q1: Maxxwell shows a session as not heard from. Did it crash?
not heard from means Maxxwell cannot confirm the state. The underlying process might be running but not emitting output.
maxxwell session attach <name> to attach a terminal.ps or hit Enter to see if the process responds.This is deliberate: a vague “working” badge on a dead process is worse than an honest “no signal”.
Q2: My planner keeps sending huge, ambiguous tasks to workers. How do I tame it?
Constrain it in the brief:
Example good instruction:
[TO worker-1] Add test case for /healthz returning 500 when dependency is down.
Example bad instruction:
[TO worker-1] Implement /healthz and refactor server plus add monitoring.Then enforce the gate in Maxxwell by editing the drafted messages before you press Enter.
Q3: Cogagent is stuck with high context pressure. What should I do?
When a worker lane shows high context pressure and little progress:
Maxxwell does not automatically recycle context; this is your call.
Q4: How is this different from running everything inside The Cog or Helmor?
Tools like The Cog, Helmor, Herd, or Acepe give you their own orchestration environments, sometimes with built-in planners.
Maxxwell instead:
If you already have cogagent and a Gremor-style planner you like, Maxxwell lets you supervise them without migrating into a new IDE.
Q5: Can Maxxwell automatically detect when my planner drifts off the brief and correct it?
No. Today Maxxwell:
It does not:
The conducting is real. The autopilot is still you.