Skip to content
rmyndharisPublic

About

The foreman for your coding agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

mandor

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.

CI Version Claude Code plugin macOS Node 22.18+ Zero dependencies MIT GitHub Stars Buy Me a Coffee

Read Before you start first. Every worker runs in a sandbox, its tool's own for Codex and Antigravity and a sandbox-exec profile from mandor for ZCode, and mandor's own writes into a worktree (checkout, clean, apply and removal) run under sandbox-exec too, so it runs on macOS only. The Claude Code session that leads must have its own Bash sandbox turned off.

TL;DR

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 work

Mandor 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.

The problem

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.

How it works

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
Loading
  1. 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.
  2. Work. dispatch makes a task worktree from the goal tip and starts a worker on it. The tier (light, medium or heavy) picks a model from its list of candidates, in order. --use pins one. wait returns when a task needs the lead.
  3. 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.
  4. Decide. accept makes one local commit in the integration worktree. fix sends specific notes back to the same worker, for three rounds by default. When the worker's report is blocked, partial or asks questions, answer resumes it with the lead's answer, and no fix round is counted. takeover lets the lead make the change itself; after every candidate is exhausted or the fix rounds run out, it needs your approval.
  5. Confirm. The lead reruns the proofs in the integration worktree. confirm closes the task. drop removes 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.

Hooks

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 wait in the background, when this session has been leading, jobs are still running or waiting to start and no wait is watching them.

Safety model

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.

Install

Requirements

  • 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 your PATH, logged in. Tested with 0.166.0; mandor init warns 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 agy CLI on your PATH, 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.

Load the plugin

git clone https://github.com/rmyndharis/mandor.git ~/mandor
cd ~/your-project
claude --plugin-dir ~/mandor

Run /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.

First use

  1. Set up the home. mandor init creates ~/.mandor and its config.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.
  2. 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 (or MANDOR_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 a stale-input red 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 .env file inside the checkout. The path must exist. It may not hold or lie inside the repository's .git directory, 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 /tmp and 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. While MANDOR_HOME or the repository lies under /tmp, /var/folders or the TMPDIR of the process, a project set up with it is refused a goal start, a dispatch, 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, which mandor project show prints, 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-dir and --remove-worker-deny-read take one entry away (an entry the configuration does not hold is refused), and --no-setup, --no-worker-network, --no-name-is-a-word and --no-shared-temp switch 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.
  3. 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.

Commands

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

Before you start

  • Turn off Claude Code's Bash sandbox for the session that leads. sandbox-exec cannot run inside another sandbox, so goal start, dispatch, verdict fix, drop, reassign and ready refuse while the session's sandbox is on, a runner started there fails its job before the worker starts, and init warns. A ZCode that is switched on cannot be listed there either, as its catalog copy is written under sandbox-exec; init and models --refresh report that as the tool's problem. The workers stay confined: by their tool's own sandbox for Codex and Antigravity, and by a sandbox-exec profile from mandor for ZCode.
  • Workers run on your Codex login and home. --ignore-user-config skips config.toml and nothing else, so your global AGENTS.md, your skills (in ~/.codex/skills and ~/.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 is config.toml. Read your rules before the first run, and remove an allow rule that you would not give a worker.
  • A worker can read what you can read. Codex's workspace-write sandbox 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-network it 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-network to project 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.json before 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 init and mandor models warn 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 and dispatch say so while ZCode is on, and mandor login zcode says 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>/tmp in the state home, as its TMPDIR, 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. /tmp and the shared TMPDIR are closed to the worker, and /var/folders too for ZCode. A build that names /tmp itself, opens a socket there or does not read TMPDIR fails, and so does mktemp, which takes the per-user directory from the system; git, cc and python3 print a complaint about the cache of xcrun and go on. A project whose toolchain needs them runs mandor project setup --update --shared-temp, which opens them again to its Codex and ZCode workers.

Configuration

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 workers

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 its HOME, 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 from HOME: a worker on your own home would load all of them into every turn. mandor login zcode signs 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.json and 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 than account:<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-exec profile: it writes only to its worktree, its project's home, the cache directories of --worker-add-dir and the job's own temporary directory (/tmp and /var/folders are 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, and dispatch --use of 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 workers

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/home in 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-dir are 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-network does 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.

State and uninstall

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.

Known limits

  • 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 install writes Git LFS's filters there, and after it every repository is refused.
  • A partial clone is refused, whether extensions.partialclone or a promisor remote marks it: git would fetch the objects it lacks from the remote by itself, and mandor starts no command that contacts one.

Development

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 ..

Contributing

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.

Support

If mandor saves you review time, you can support its development by buying me a coffee.

Buy Me a Coffee

License

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

About

The foreman for your coding agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages