The foreman for your coding agents.
A Claude Code plugin that lets your session lead Codex, ZCode and Antigravity workers: it plans the goal, dispatches tasks to sandboxed workers, reviews every result, and lands each one as a guarded local commit. It never pushes.
Read Before you start first. Every worker runs in a sandbox, its tool's own for Codex and Antigravity and a
sandbox-execprofile from mandor for ZCode, and mandor's own writes into a worktree (checkout, clean, apply and removal) run undersandbox-exectoo, so it runs on macOS only. The Claude Code session that leads must have its own Bash sandbox turned off.
git clone https://github.com/rmyndharis/mandor.git ~/mandor
~/mandor/bin/mandor init # once: sets up ~/.mandor and reads the Codex model list
cd ~/your-project
claude --plugin-dir ~/mandor # then ask Claude to lead the workMandor is Indonesian for foreman. The session you talk to is the foreman: it plans the goal, hands the coding to Codex, ZCode and Antigravity workers that run in parallel, each in its own git worktree inside a sandbox, reads what comes back, and accepts it as one local commit on a goal branch. You push when you are satisfied.
Leading AI coding workers by hand comes down to three chores: keep each worker inside its task, read what it wrote before it reaches your branch, and pick the work back up when a quota runs out or you switch accounts. Skip one and a stray file, a deleted test or a leaked credential ends up in your history.
mandor turns the chores into a loop the lead follows, and enforces the parts that must not depend on anyone's attention. A worker's sandbox limits its writes to its worktree, a temporary directory of its own for the job (the shared ones are closed to a Codex or a ZCode worker, unless the project opens them with --shared-temp) and the cache directories the project opens (--worker-add-dir), and for a ZCode worker its own home. The lead cannot accept a result it has not reviewed, and the commit holds exactly the tree that review showed. Nothing is pushed. State lives on disk, so a quota wall or an account switch pauses the work instead of losing it.
The Claude Code session you are in is the lead. It plans the goal and decides every outcome. Workers are Codex, ZCode or Antigravity CLI processes, one per task, each in its own git worktree, writing code and running the proof commands the lead gave them. Each is confined by a sandbox: the tool's own around the commands the model runs for Codex and Antigravity, and a sandbox-exec profile from mandor around the whole process for ZCode. The mandor CLI sits between them: it keeps the state on disk, launches the workers, builds the review pack and enforces the guards. Independent tasks run in parallel, up to maxParallel workers per tool (two by default).
flowchart TD
ASK([You ask Claude to lead the work]) --> PLAN["Plan<br/>goal branch, integration worktree,<br/>tasks with scope, tier and proofs"]
PLAN --> DISPATCH["Dispatch<br/>one sandboxed worker per task,<br/>each in its own worktree"]
DISPATCH --> WAIT["Wait<br/>returns when a task needs the lead"]
WAIT --> REVIEW["Review<br/>diff, red flags and violations.<br/>The lead reads the files and runs the proofs"]
REVIEW -->|accept| COMMIT["One local commit<br/>of exactly the reviewed tree"]
REVIEW -->|fix| ROUND["Worker round<br/>with the lead's notes"]
REVIEW -->|takeover| OWN["The lead edits<br/>the task worktree"]
ROUND --> WAIT
OWN --> REVIEW
COMMIT --> PROOF{"Proofs pass in the<br/>integration worktree?"}
PROOF -->|confirm| DONE([Task accepted])
PROOF -->|drop| ROUND
WAIT -.->|quota, limit or failure| STALL["Stalled<br/>next candidate, or you choose:<br/>switch account, wait or takeover"]
STALL -->|reassign or ready| WAIT
STALL -->|takeover| OWN
classDef entry fill:#f8fafc,stroke:#94a3b8,color:#0f172a,stroke-width:1.5px
classDef step fill:#eef2ff,stroke:#6366f1,color:#312e81,stroke-width:2px
classDef ok fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1.5px
classDef warn fill:#fff7ed,stroke:#f97316,color:#7c2d12,stroke-width:2px
class ASK entry
class PLAN,DISPATCH,WAIT,REVIEW,COMMIT,ROUND,OWN,PROOF step
class DONE ok
class STALL warn
- Plan.
goal start <branch>creates the goal branch and an integration worktree for it. The lead splits the goal into tasks, each with scope globs, a tier and proof commands, and writes a brief for every task. - Work.
dispatchmakes a task worktree from the goal tip and starts a worker on it. The tier (light,mediumorheavy) picks a model from its list of candidates, in order.--usepins one.waitreturns when a task needs the lead. - Review.
review <slug>prints the diff stat, the changed files, the red flags and the violations, and records the tree it showed. The lead reads every changed file and runs the proof commands itself. The worker's report is not evidence. - Decide.
acceptmakes one local commit in the integration worktree.fixsends specific notes back to the same worker, for three rounds by default. When the worker's report is blocked, partial or asks questions,answerresumes it with the lead's answer, and no fix round is counted.takeoverlets the lead make the change itself; after every candidate is exhausted or the fix rounds run out, it needs your approval. - Confirm. The lead reruns the proofs in the integration worktree.
confirmcloses the task.dropremoves the commit and sends the notes back to the worker as a fix round.
When a worker hits a quota, a model limit or an account mismatch, the task moves to the next candidate for its tier. When every candidate is exhausted the lead asks you to choose: switch the worker account and run mandor ready codex, wait for the reset time that mandor status shows, or approve a takeover; with ZCode or Antigravity switched on, allowing worker network lets routing use it. A goal that moved while a task was in flight gets the change merged onto its new tip first, and the lead reviews again.
mandor registers two Claude Code hooks. Both do nothing outside a repository that already has a goal, with one exception below, and neither can break a session: a failure goes to ~/.mandor/logs/hooks.log instead of reaching you. The exception is a Node the hooks cannot use. With no Node 22.18 or newer on the PATH the hooks run with, they do nothing and write nothing, as they cannot tell which directories have a goal. That PATH can differ from the one of Claude Code's Bash tool, for instance when an editor starts Claude Code. If you already have mandor state under ~/.mandor, SessionStart then says in the session, in any directory, that the hooks are off.
- SessionStart prints a short summary of the goals with their integration worktrees (and an accept that was killed and not yet settled), the tasks with their status, stall reason and next action, any exhausted tool, and the warnings of the tools that are switched on, so a new, resumed or compacted session can pick the work up. It also refreshes the Codex model list in the background.
- Stop blocks Claude from ending its turn, once, with a reminder to run
mandor waitin the background, when this session has been leading, jobs are still running or waiting to start and nowaitis watching them.
| Concern | What mandor does |
|---|---|
| A worker reaching beyond its task | Each worker runs in a sandbox (its tool's own for Codex and Antigravity, a sandbox-exec profile from mandor for ZCode) that limits its writes to its worktree, a temporary directory of its own for the job (Codex and ZCode; the shared ones are closed to them, unless --shared-temp opens them) and the cache directories the project opens, and for ZCode its own home. Each task carries scope globs, and the review flags files outside them. Denied paths make accept refuse: .env files other than their templates, keystores, signing properties, agent instruction files and _docs/. The commit message is held to the same list, except that it may name the secret files themselves, such as .env or a keystore. Before a fix, an answer, a drop or a reassign is recorded, and again before each job starts, the root of the task worktree is checked, and nothing starts over an agent path (an instruction file or a tool's settings directory, ignored by git or not) that the repository does not hold as it is: Codex starts the tool servers that a .codex/config.toml names outside its sandbox, and a round of another tool can write one. An entry the base lacks counts by its name, a directory that cannot be read counts, and the executable bit does not. A process that an earlier round left running can still write one after the check. |
| Credentials | A worker's environment is an allowlist: no API keys, agent sockets or tokens, and a git and gh that cannot prompt or reach credentials. The network is closed unless the project allows it, and an Antigravity job is refused in a project that has not, as its sandbox's proxy decides what its commands reach. Files your account can read are not hidden from a worker: see Before you start. |
| Unreviewed code | Accept commits only the tree the last review showed. An edit, a worker round, a rebase or a process left in the worktree changes that tree, and accept refuses until the lead reviews again. A commit made by hand on a goal branch passed no review either, so accept refuses while the branch ends in one, and status names it, until you remove it or run mandor goal adopt <branch>. |
| A hostile repository config | A repository is refused when the git configuration that applies to it, your global and system files included, defines a filter or merge driver, because such a command would run in the directory the worker writes to. A change under a relative core.hooksPath is refused too. The repository's own hooks still run, with your privileges and no sandbox, in two places: its commit hooks at accept, which can run project scripts that the change you reviewed altered (a tracked hook such as one that husky installs does), and its reference-transaction hook when mandor creates, resets or deletes a branch. A commit that a hook changes is rolled back, so a repository whose hooks always rewrite the commit cannot be integrated, and a commit that runs for more than ten minutes is stopped, with what its hooks started, and the accept is undone. The commit has a process group of its own, so a command that is interrupted does not stop it: wait and status settle what it made, and the next accept or settle stops one that is past the limit. A hook that starts a session of its own escapes the stop. Every other git call that mandor makes in a worktree runs with hooks off, those that your git configuration defines included, and the checkout of a new worktree runs confined and runs none. A signing program, or a default ssh key command, that is a path relative to the worktree is refused at accept. |
| Traces of tooling in your history | The diff guards and the commit-message check refuse agent instruction files and directories (CLAUDE.md, AGENTS.md, .claude/, .cursor/ and the like), symlinks that lead to denied paths, attribution to a tool or model (credits, author tags, trailers, the robot emoji), the dash glyphs U+2014, U+2013 and U+2015, and mandor's own forms of its name: the .mandor home path, the three MANDOR_ variables, a command such as mandor wait, and the skill ids. The bare word mandor passes. Accept has no override. A repository about foremen says so once, with --name-is-a-word at project setup. |
| Pushing | mandor never pushes, and starts no git command that names a remote. It commits locally with the repository's own identity and refuses a placeholder identity (example.com, localhost, .invalid). |
Violations block accept. Red flags are for the lead to weigh: deleted or skipped tests, removed assertions, files outside the task's scope or on shared paths, added TODOs, commands the report claims but the worker never ran, generated inputs that went stale, and advisory attribution hints.
- macOS. mandor's own writes into a worktree (checkout, clean, apply and removal) and its ZCode workers run under
sandbox-exec, which exists only there. The Codex and Antigravity CLIs confine their workers themselves. - Node 22.18 or newer. The CLI is TypeScript run directly through Node's type stripping: no build step and no runtime dependency.
- Codex CLI (
codex) on yourPATH, logged in. Tested with 0.166.0;mandor initwarns about any other version. - ZCode (optional): the ZCode app in
/Applications. Tested with its CLI 0.17.1. Its workers sign in on their own: see ZCode workers. - Antigravity (optional): the
agyCLI on yourPATH, signed in. Tested with 1.5.2. Read Antigravity workers before you switch it on. - Claude Code with plugin support. The plugin loads and its skills run on 2.1.319.
git clone https://github.com/rmyndharis/mandor.git ~/mandor
cd ~/your-project
claude --plugin-dir ~/mandorRun /mandor:status to check it: outside a repository with a goal it prints that there is no project here, and the hooks stay silent.
This repository does not ship a marketplace listing yet, so --plugin-dir is how mandor is loaded today. The plugin puts bin/ on the PATH of Claude Code's Bash tool, so Claude calls mandor directly. From a terminal, call ~/mandor/bin/mandor or add that directory to your PATH.
- Set up the home.
mandor initcreates~/.mandorand itsconfig.json, reads the Codex model list, and prints warnings: that Codex has no switch to keep a worker off paid credits, an untested version of a worker tool, secret-like variables exported by your login shell, a sandbox that cannot be applied, a tier candidate the model list cannot run, a tool whose models cannot be read, that mandor does not switch billing off for ZCode or detect billed usage while ZCode is on, and Google's terms while Antigravity is on, and that Antigravity is switched on but not acknowledged. - Describe the repository (optional).
mandor project setup, run in the repository, records what workers need. Without it every list is empty and workers get no network, and ZCode and Antigravity jobs are refused, as their commands reach the network whatever the project says. Each run states the whole configuration:--clone <path>: an ignored path copied from the main checkout into each worktree (build caches, downloaded SDKs). Denied and agent paths inside it are skipped. The copy is an APFS clone, so~/.mandor(orMANDOR_HOME) must be on the same volume as the repository.--setup "<command>": run once in each new worktree, with the worker's environment variables but without a sandbox, so it can write and reach the network like any command you run yourself. Give it only a command you trust. It must not write an agent path (AGENTS.md,.codex/and the like, ignored or not) that the repository does not hold, as every job is then refused over it.--shared <path or glob>: paths more than one task touches (a changelog, a lockfile). The review flags changes to them.--deny <glob>: paths no task may change, on top of the defaults. An entry that names a directory, with or without a trailing slash, covers everything under it.--generator <clone path>=<glob>: scripts whose change makes a cloned path stale, which a review reports as astale-inputred flag. Worktrees clone the main checkout, so after a task that changed one of them is confirmed, a later worktree of the goal still gets the older copy that the main checkout holds, until it is rebuilt there from the goal's version of the script.--worker-network: lets workers reach the network. Off by default. A worker can read any file your account can read, so with the network on it can also send one out: see Before you start.--worker-add-dir <dir>: a Gradle or Android cache directory workers may write.--worker-deny-read <path>: a file or directory, by an absolute path or one that starts with~/, that the commands of a ZCode worker may not read, on top of the credential directories its profile always closes. Name what else holds a secret on your machine, such as~/.git-credentials, a keystore, or an.envfile inside the checkout. The path must exist. It may not hold or lie inside the repository's.gitdirectory, which the git commands of every task worktree read, and may not lie inside~/.mandor, which the profile closes already. An entry never hides the worker's own worktree, home or job directory, or the cache directories of--worker-add-dir. It applies to ZCode only: the sandboxes of Codex and Antigravity read what your account can read.--shared-temp: keeps/tmpand the per-user temporary directory open to Codex and ZCode workers, and the per-user cache directory as well for ZCode, instead of a directory of the job's own. Off by default, as the lead's proofs and your own tools keep caches and compiled files in those directories, and a worker can leave files there that they run later. Turn it on only for a toolchain that cannot work without them: see Before you start. WhileMANDOR_HOMEor the repository lies under/tmp,/var/foldersor theTMPDIRof the process, a project set up with it is refused agoal start, adispatch, a fix, an answer, a drop and a reassign, and a job that is about to start fails, as its workers could then write the state home or your checkout.--update: start from the stored configuration, whichmandor project showprints, instead of an empty one. The flags above then add to its lists and replace its single settings,--remove-clone,--remove-shared,--remove-deny,--remove-generator,--remove-worker-add-dirand--remove-worker-deny-readtake one entry away (an entry the configuration does not hold is refused), and--no-setup,--no-worker-network,--no-name-is-a-wordand--no-shared-tempswitch one setting off. Without it, each run states the whole configuration.--name-is-a-word: this repository's own subject uses the word mandor, a foreman. A phrase such as "the mandor status" in a file or a commit message is then no longer taken for the tool. A real invocation, a command with an option or through the launcher, is still refused.
- Ask for the work. In Claude Code, describe the goal and ask Claude to lead it through mandor, for example Use mandor to add pagination to the orders API, with tests. You can also run
/mandor:lead <goal>. Claude reports each event in one short line and asks you when the decision is yours, such as a takeover or an account switch.
| Slash command | Effect |
|---|---|
/mandor:lead |
Load the lead's playbook: plan, dispatch, review, accept. Add the goal after the command, or just ask Claude to lead coding work through mandor and it loads the playbook itself |
/mandor:status |
Show the goals, tasks and exhausted tools of this repository |
The lead's commands print JSON; status, show and logs print plain text.
| You run | Purpose |
|---|---|
mandor init |
Create ~/.mandor, read the Codex model list, print warnings |
mandor models [--refresh] [--json] |
List the models that the enabled tools offered when the list was last read, each as tool:model with its efforts. It is read again when it is older than five minutes, or with --refresh. A read that no tool answered is not repeated for five minutes, and the last list stays |
mandor tiers [--json] |
List the candidates of each tier as config.json writes them, with what keeps one from running: its tool is off, the model list lacks it, or it is exhausted. A ZCode or Antigravity candidate is marked as needing worker network |
mandor login zcode [--api-key] |
Sign the ZCode worker in under a home of its own: in a browser, or with a Coding Plan API key piped in |
mandor project setup [flags] |
Record what workers need in this repository. Each run replaces the whole configuration, unless it is given --update |
mandor project show |
Print the configuration that project setup stored, which a setup without --update replaces |
mandor status [--json] |
Goals with their integration worktrees, tasks, jobs, the time each exhausted tool resets with the reason, the commits on a goal branch that mandor did not record, and a goal whose killed accept it could not settle. status and wait settle a killed accept the way the next accept would: undone when nothing landed, adopted when its commit landed |
mandor show <slug> |
The outcome detail of a task, and each of its jobs with the tokens that run used |
mandor logs <slug> |
The paths of a task's job logs |
mandor goal adopt <branch> |
Keep, as your own, the commits at the top of a goal branch that mandor did not make: accept refuses while a goal branch ends in one |
mandor --help |
List every command with its options |
| The lead runs | Purpose |
|---|---|
mandor scratch [name] |
Print the directory for briefs, plans and evidence files, which never go inside a repository |
mandor goal start <branch> |
Make the goal branch and its integration worktree. --from <ref> branches from another commit |
mandor plan set |
Record the plan: --goal, --file and --description |
mandor dispatch |
Start a worker on a task: --goal, --task, --tier and --brief, and optionally --scope (repeatable), --use <tool:model@effort> and --after <slug>. It prints the warnings of the tools that are switched on |
mandor wait --since <cursor> |
Return when a task needs the lead. --timeout <seconds> bounds the wait |
mandor review <slug> |
Print the review pack, which also names the ignored paths that changed since the task's first job, a report that is blocked, partial or asks questions, and an accept of the goal that was killed and not yet settled, and record the reviewed tree |
mandor diff <slug> |
Print the task's change as patch text, read through the same confined staging as the review. It records no review, and it refuses a task with a job in flight, whose worker is still changing the files |
mandor verdict <slug> accept |
Commit the reviewed tree: --evidence-file and --message-file |
mandor verdict <slug> fix |
Send notes back to the worker: --notes |
mandor verdict <slug> answer |
Answer a report that is blocked, partial or asks questions: --notes. The worker resumes with the answer, and no fix round is counted |
mandor verdict <slug> takeover |
Make the change in the task worktree. A stalled task needs --approved, which marks a takeover you approved; a task under review does not. show lists how each takeover was approved |
mandor confirm <slug> |
Close a task after the proofs pass in the integration worktree: --evidence-file. When it prints cleanup: "failed", the worktree is still there, and the same command finishes removing it |
mandor drop <slug> |
Remove the commit and send the notes back: --notes |
mandor reassign <slug> |
Move a stalled task to its next candidate |
mandor ready <tool> |
After an account switch or a reset, resume the stalled tasks of that tool |
mandor cancel <slug> |
Stop a task's job and remove its worktree, after saving the worker's change as cancelled.patch in the task's round. When the copy cannot be taken it prints patch: "failed" and keeps the worktree. The same command, run again on the cancelled task, takes the copy if none was saved and removes a worktree that is still there, which is what cleanup: "failed" asks for |
- Turn off Claude Code's Bash sandbox for the session that leads.
sandbox-execcannot run inside another sandbox, sogoal start,dispatch,verdict fix,drop,reassignandreadyrefuse while the session's sandbox is on, a runner started there fails its job before the worker starts, andinitwarns. A ZCode that is switched on cannot be listed there either, as its catalog copy is written undersandbox-exec;initandmodels --refreshreport that as the tool's problem. The workers stay confined: by their tool's own sandbox for Codex and Antigravity, and by asandbox-execprofile from mandor for ZCode. - Workers run on your Codex login and home.
--ignore-user-configskipsconfig.tomland nothing else, so your globalAGENTS.md, your skills (in~/.codex/skillsand~/.agents/skills) and your rules (~/.codex/rules) load into every worker. A rule of yours that allows a command makes Codex run it outside the worker's sandbox, and a rule matches by prefix, so the worker may add any arguments after the words you wrote. Plugins, tool servers and hooks do not load: where they are enabled or trusted isconfig.toml. Read your rules before the first run, and remove anallowrule that you would not give a worker. - A worker can read what you can read. Codex's
workspace-writesandbox confines a worker's writes to its worktree, its own temporary directory and the cache directories the project opens, not its reads, and the worker runs with your home directory. Whatever a worker's model reads reaches the worker's vendor as model context. With the network closed, which is the default, the commands it runs can write what they read only into its worktree, its temporary directory or a cache directory the project opens. With--worker-networkit can send a file such as a key or a credential out, so turn that on only for a repository whose tasks you trust. Antigravity's commands reach whatever its sandbox's proxy lets through, so an Antigravity job only runs with it. - Workers have no network unless you pass
--worker-networktoproject setup. ZCode and Antigravity workers only run in a project that has it, as their commands reach the network whatever the project says: see ZCode workers and Antigravity workers. - Your repository gets branches and worktree registrations. The goal branch, the
wip/task branches and the worktree registrations stay until you remove them (see State and uninstall). - The lead runs your proofs on code a worker wrote. To check a result, the lead runs the task's tests and builds in the task worktree, with your privileges and no sandbox. Nothing mechanical stops code a worker wrote from running there. The lead's instructions list reading every changed file before running the proofs, and that order rests on the lead following it. A file in a path that git ignores is never listed in a review, and the proofs can still run it.
- Switching accounts to get past a limit is your call. When no candidate is left to run a task, the lead offers three choices: wait for the reset, take over, or continue after you switch the worker account. Whether a vendor lets one person switch accounts to get past a limit is for you to check in its terms. mandor never switches an account itself.
- Your code goes to every enabled vendor. Tools are enabled per machine, not per project. For a repository that must not reach a vendor, switch that tool off in
~/.mandor/config.jsonbefore you ask for work on it. - The guards have no override. If your repository or employer requires that the use of an AI tool be stated in the history, mandor does not state it for you. Its guards refuse the usual forms of such a statement, a co-author trailer or a credit line that names a tool, in a commit message and in a diff, and have no way to allow one. A plain sentence that says an AI tool was used can pass the guards, and only the lead's instructions keep it out of a commit message.
- Paid usage is not always stopped. Antigravity runs ask the CLI to switch AI credits off for the run. Codex has no such switch:
mandor initandmandor modelswarn about that, and mandor marks Codex used up after a finished run whose rate-limit record shows the plan's limit reached while credits were available, which is how it assumes a paid run looks. That run, and any run already in flight, is paid for already, and a run that fails or times out is not checked. For ZCode mandor does not switch billing off or detect billed usage, and a stored key may be one that is billed per use:mandor init,mandor models, the session summary anddispatchsay so while ZCode is on, andmandor login zcodesays it whether or not ZCode is on yet. - Cache directories are shared, and Antigravity's temporary ones. The cache directories a project opens to workers are shared with the lead's proof commands and with your own tools, and so are the temporary directories that an Antigravity worker may write, whatever its sandbox allows. A worker can leave files there that they run later. A Codex or a ZCode worker gets a temporary directory of its own for each job,
jobs/<id>/tmpin the state home, as itsTMPDIR,TMPPREFIX(the files of zsh's here-documents), clang's module cache and the temporary directory of a JVM (JAVA_TOOL_OPTIONS), and it is removed when the run ends./tmpand the sharedTMPDIRare closed to the worker, and/var/folderstoo for ZCode. A build that names/tmpitself, opens a socket there or does not readTMPDIRfails, and so doesmktemp, which takes the per-user directory from the system;git,ccandpython3print a complaint about the cache ofxcrunand go on. A project whose toolchain needs them runsmandor project setup --update --shared-temp, which opens them again to its Codex and ZCode workers.
mandor init writes ~/.mandor/config.json with defaults. A present file is the whole configuration: it is not merged with the defaults, and it must name all three tools. A minimal valid file looks like this; the defaults list more candidates per tier, zcode and agy ones included:
{
"version": 1,
"tools": {
"codex": { "enabled": true, "maxParallel": 2, "bin": "codex", "ignoreUserConfig": true },
"zcode": { "enabled": false, "maxParallel": 2, "bin": "zcode", "ignoreUserConfig": true },
"agy": { "enabled": false, "acknowledged": false, "maxParallel": 2, "bin": "agy", "ignoreUserConfig": true }
},
"tiers": {
"light": ["codex:gpt-6-luna@medium"],
"medium": ["codex:gpt-6.1-sol@high", "codex:gpt-6-luna@high"],
"heavy": ["codex:gpt-6.1-sol@max"]
},
"jobTimeoutMinutes": 60,
"maxFixRounds": 3
}Each tier lists its candidates as tool:model@effort, in order of preference; mandor models shows what each enabled tool offers. A candidate the model list cannot run (a model your plan lacks, or one that was renamed) is passed over, and mandor init and mandor models warn about it. tools.agy.acknowledged must be true as well for Antigravity to take part: see Antigravity workers. maxParallel caps the workers a tool runs at once, jobTimeoutMinutes ends a job that runs too long, and maxFixRounds is how many fix rounds a worker gets before the task needs a takeover. A bin is an absolute path or a bare name, which is looked up on PATH (for ZCode it means the app's own executable): a relative path is refused, as it would resolve in the directory of whichever command starts the job. The Indonesian tier names ringan, sedang and berat are still read as light, medium and heavy, in config.json and for --tier.
| Variable | Effect |
|---|---|
MANDOR_HOME |
The state directory. Must be an absolute path, and must not lie inside a git working tree: init, models, project setup, goal start and dispatch refuse one. Defaults to ~/.mandor |
MANDOR_CODEX_BIN |
The Codex binary, as an absolute path. Overrides tools.codex.bin and the PATH lookup |
MANDOR_JOB |
Set by mandor in a worker's environment to the job id. You do not set it |
ZCode is off until you switch it on. Set tools.zcode.enabled to true in ~/.mandor/config.json, then sign the worker in, one of two ways. With an API key: put pbpaste | mandor login zcode --api-key on your terminal's command line without running it, create a key for your Coding Plan at https://z.ai/manage-apikey/apikey-list and copy it, then press Enter. The order matters: the command reads the clipboard, so the key must be the last thing copied. The key never shows on screen or in your shell history, and it lasts until you revoke it. In a browser: run mandor login zcode and approve the sign-in, which stops working after an hour. mandor models then lists the models of your plan, and the zcode: candidates of each tier start to run.
A ZCode worker differs from a Codex worker in five ways:
- A home of its own for each project. A job runs with
~/.mandor/zcode/homes/<project>as itsHOME, one directory for each project, so the sign-in of your ZCode app is never touched and what one project's jobs leave behind reaches no other project. The ZCode CLI reads your MCP servers, plugins, hooks, skills and instructions fromHOME: a worker on your own home would load all of them into every turn.mandor login zcodesigns in under~/.mandor/zcode/home, which no worker's command can read, and every job start copies the two sign-in files from there into the project's home, replacing what lies there, so a key or a plan that a worker put in their place lasts no longer than its job. The commands of a job can write inside the project's home but cannot remove or move it, and what they leave there stays for that project's later jobs: at every run of a job the CLI starts the hooks and tool servers of.zcode/cli/config.jsonand loads.zcode/AGENTS.md, under the same profile as the worker's commands, and it keeps the input and output of every session. What mandor itself stores there (the catalog copy, the sign-in files) is written confined to it, so a link the worker puts in the home leads nowhere, and the writes of the CLI's version call are confined to the sign-in home. A sign-in file that names a plan of another shape thanaccount:<name>is refused. Each home takes about 64 MB, the plugin files that the CLI unpacks on its first start, and is removed when a job ends after its project's state is gone. After a project you do not trust has run, look in its home and remove what you did not put there. - mandor's own sandbox. ZCode has no sandbox of its own, so the worker runs under a
sandbox-execprofile: it writes only to its worktree, its project's home, the cache directories of--worker-add-dirand the job's own temporary directory (/tmpand/var/foldersare open to it in a project set up with--shared-temp). - The network is always open. The profile cannot close the network for the worker's commands and leave it open for the CLI that runs them. A ZCode job therefore refuses to start in a project without
--worker-network: routing passes a ZCode candidate over there, anddispatch --useof one is refused. To make up for it, the profile keeps the worker from reading what your credential directories hold (~/.ssh,~/.aws,~/.gnupg,~/.config/gh, the homes of the other tools and the like) and the rest of~/.mandor, and the paths you add with--worker-deny-read. Any other file your account can read is still readable. - A browser sign-in runs out. It lasts an hour and the CLI does not renew it. Every run then fails at once, so mandor sets the tool aside as it does one out of quota, and its tasks can move to another tool. Sign in again, then run
mandor ready zcode. An API key does not run out. The CLI encrypts a browser sign-in with a key it takes from the home directory, so mandor gives every ZCode call one secret of the state home (~/.mandor/zcode/credential-secret, made on first use) and the sign-in opens under each project's home; one made by an earlier version has to be made again. Either sign-in is copied into the project's home at every job start, where the job's own commands can read it, and the secret is in their environment: revoke the key at Z.ai if a run ever looks wrong. - The report is checked, not enforced. ZCode has no output schema, so the prompt states the report's format and mandor takes the last object of the answer that fits that format. A run that ends on another model than the task asked for is failed: ZCode falls back to your plan's default model without saying so.
A bare tools.zcode.bin means the app's own executable in /Applications; give a path for an app kept elsewhere.
Antigravity is off until you switch it on, and Google's terms are the reason to think first: its FAQ calls driving the agy CLI from another tool unsupported on consumer plans, and an account can be blocked for it. mandor init and mandor models repeat this while it is on. If you accept that, set tools.agy.enabled and tools.agy.acknowledged to true in ~/.mandor/config.json. With enabled alone Antigravity stays off, and mandor init, mandor models, the session summary and a refused dispatch --use say why, with the same notice. There is no separate sign-in: the worker runs on the account your Antigravity app holds, and mandor models lists what that account offers. A model's id carries its effort, so an agy candidate is written without one, as in agy:gemini-4-argon-high.
What mandor does for an Antigravity worker:
- A configuration directory of its own. The worker runs with
~/.mandor/agy/homein place of~/.gemini, so your plugins, MCP servers, hooks and rules stay out of it. A hook of yours would otherwise rewrite the worker's commands. - Antigravity's own sandbox. The worker's commands run in the CLI's sandbox. They write nowhere outside the worktree and nothing into its git directory; the cache directories of
--worker-add-dirare the one other place they may write, if the sandbox lets them (not yet confirmed). Their network reaches only what the sandbox's proxy lets through, which--worker-networkdoes not change; a project without it is refused, as its setting cannot close that network. A build that downloads its dependencies may fail there. - Narrow permissions. Without a person to ask, the CLI refuses any tool that needs a permission and still reports success. Each run is given rules for exactly its worktree, the cache directories of
--worker-add-dir, and commands. A run that was refused a tool is failed. - Paid credits are off. Every run switches AI credits off for itself, whatever your settings say. Past the plan's quota the CLI would otherwise bill them, with no quota error.
- A lost conversation starts over. When the conversation of a fix round is gone, the CLI starts a new one without failing. mandor sees the new id and starts the task over once, from the work so far.
mandor's own state lives under ~/.mandor, or MANDOR_HOME when it is set: config.json, the model catalog, the ZCode sign-in home and one ZCode home for each project, the Antigravity worker's configuration directory, one directory per project with its event ledger, tasks, rounds and scratch files, the task and integration worktrees, the job logs, and logs/runner.log, logs/hooks.log, logs/vendor.stderr, where what the tools' version and model calls print on stderr goes, as it can hold a token, and logs/git.stderr, where the words of a failed git step of a review or an accept go, as they can quote what a worker wrote. A repository itself gets the worktree registrations, the goal branch, the wip/ task branches and the commits the lead accepted. A review, a diff, an accept's staging, a handoff and a cancel read a task's changes through a copy of the task's index and an object directory of their own under stage/ in the state home, which are removed when they end (the next staging removes one that a kill left, once it is an hour old), so no worker file reaches the repository's object store from them. An accept, and a rebase onto a goal that has moved, apply the change through git itself, which keeps what it applied in the repository's object store. Codex also keeps its own record of each Codex worker's session in its home (~/.codex, or CODEX_HOME), among your own sessions, and mandor never removes it.
A job's directory, its logs included, is removed 30 days after the job ended, unless it is the newest job of a task that is still open.
To stop using mandor, stop passing --plugin-dir. To remove its state, delete ~/.mandor, then in each repository run git worktree prune and delete the goal and wip/ branches you no longer need.
- Three worker tools in this version: Codex, ZCode and Antigravity. Only Codex is on by default.
- You switch worker accounts yourself. mandor keeps the record of the work and resumes it with
mandor ready <tool>. - No dashboard:
mandor status, the lead's reports in chat and the log files are the interface. - A repository whose git directory is kept outside its work tree, made with
git init --separate-git-dir, works from its main checkout. A linked worktree of it is a project of its own, because git does not say where the main checkout is. - A filter or merge driver anywhere in the git configuration that applies to a repository makes mandor refuse it. That includes your global file:
git lfs installwrites Git LFS's filters there, and after it every repository is refused. - A partial clone is refused, whether
extensions.partialcloneor apromisorremote marks it: git would fetch the objects it lacks from the remote by itself, and mandor starts no command that contacts one.
mandor is TypeScript that Node runs directly, with no runtime dependencies.
| Path | Purpose |
|---|---|
.claude-plugin/plugin.json |
Plugin manifest |
hooks/hooks.json |
The SessionStart and Stop hooks |
skills/lead/SKILL.md |
The lead's playbook, loaded as /mandor:lead |
skills/status/SKILL.md |
/mandor:status |
bin/mandor |
The CLI launcher |
src/ |
The CLI |
test/ |
Tests, run with node --test |
npm install # dev dependencies only, used by the type check
npm run typecheck
npm test
claude plugin validate .Load your working copy into a session with claude --plugin-dir ..
Issues and pull requests are welcome. CONTRIBUTING.md says how to file an issue, what a commit and a pull request should look like, and how a release is cut. Keep changes small, add a test for any change in what a guard refuses or what a worker may do, and run npm run typecheck and npm test before you open a pull request.
A change that gives workers more reach than they have today (a wider environment, a writable path, a weaker guard) explains in the pull request why it is safe, and adds two tests: one that shows the new reach works, and one that shows the next thing beyond it is still refused.
Report a security problem privately, as SECURITY.md describes. Releases and what changed in each are listed in the changelog.
If mandor saves you review time, you can support its development by buying me a coffee.
Released under the MIT License.
Claude Code is a product of Anthropic and Codex is a product of OpenAI. mandor is an independent project and is not affiliated with or endorsed by Anthropic or OpenAI.
Made with ❤️ by Yudhi Armyndharis & mandor contributors