Skip to content

Several agents on one repository, without stepping on each other

Every worker declares the paths it may touch, every session can see who else is attached and what they announced, and a collision is reported before it is committed.

status
feature status: stable
on the homepage
featured

What it does

Parallel work needs isolation and visibility, and the tool gives both without a person coordinating by hand. majordomus start records the paths a task may touch; check and finish fail on a touched file outside them and report the overlapping claim of any other worktree of the same repository on the same machine. Every branch that is worked on has one worktree at a path derived from git's own identity, so two sessions cannot occupy one path by accident and a handover can name where the work is.

The shared server makes the live half visible: every attached client — Claude Code, Codex, Gemini CLI, a script — is a peer named by its own handshake, and majordomus_announce tells the others one line of intent and the paths it expects to touch, before the first tool call.

What it does not do

Overlap is reported, never blocked: the tool refuses to accept work as completed when a file is outside the declared scope, and it does not stop an editor from writing the file while the task runs. An announcement is informational and lives in the server's memory; the durable, enforced form is the task record and its scope.

Why it exists

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

Every moment it answers (14)

forai-native-teamplatform-team

How it works

The capability modules of the executable this feature names, each with the capabilities it composes. The interfaces each one reaches are listed under Interfaces below: they are projections of one declaration, not separate registrations.

Peers peers behaviorally verified

The workers of this repository, named by their own initialize, and what each announced it is working on — gathered from the board of every checkout, because a server serves a checkout and a repository worked on through linked worktrees has one board per worktree. In memory; gone with the processes.

Server server behaviorally verified

The shared server of this checkout and of every other checkout of the same git repository: what each lease says, whether the server it names answers, whether what answers is the code on disk at this executable's version, and how many peers each one holds.

Worktree topology worktree behaviorally verified

Where every linked git worktree of this repository belongs and where each one is. The container is the primary checkout's sibling named with `-wt`, the path under it is the branch name with its hierarchy kept, and both are derived from git's own identity — the common directory, the registered worktrees, the branches — never from a registry, a configuration or the current directory. A worktree somewhere else is a typed diagnostic with a remedy; the migration that repairs it is a command-line operation of the same service.

Pull-request integration integration experimental

Every open pull request classified against the current master — ready, needs refresh, waiting for checks, review or a dependency, draft, needs repair, conflicting, blocked, unsafe (auto-merge armed), redundant (its work is on master already), superseded (by a declared successor that landed, named in superseded_by), possibly redundant, other base or unknown — each with the master and head it was decided against, its reasons, its evidence, its risk and its overlaps, ranked deterministically; and the audit trail of the executor that merges the next provably safe one, one at a time. The relation to master is decided by git with this repository's own merge drivers, because the forge cannot run the derived-file driver. Read from the last recorded forge observation; the one exception is the dry-run proof, which observes the forge itself because the observation is part of what it proves moves nothing.

Edit guard guard experimental

Whether a write to a file of this checkout is covered by a claim: the active task's scope, or a live mesh claim of the writing session. The judgement a provider's pre-tool hook asks before every edit (majordomus guard hook), switched by session.edits_require_claim.

The monitor monitor experimental

Everything that happens around this repository, followed in one stream: the mesh journal (sessions on every linked machine, this checkout's board among them, their claims, handovers and reviews), the executor's trail (merges, refreshes, repairs, closures, failures) and GitHub (pull requests opened, merged and closed, finished workflow runs), folded so that a session re-announcing itself unchanged and a step that decided nothing are counted rather than shown, with what is addressed to the reader marked (ADR 0133).

Where it sits

domain
Coordination — Every worker declares the paths it will touch, sees who else is working and where, and hears about a collision before it is committed.
areas of work
coordination

Interfaces

Each capability behind it, on every interface it is projected onto. A link goes to this site's reference for that interface; an HTTP route and an MCP tool are answered by a running majordomus serve, not by this site.

The capabilities behind this feature, by interface
capabilitycommand lineHTTPMCP tool
peers.announce —none POST /api/v1/peers/announce majordomus_announce
peers.list —none GET /api/v1/peers majordomus_peers
server.status majordomus serve status GET /api/v1/server majordomus_server
worktree.inspect majordomus worktree inspect GET /api/v1/worktrees/inspect majordomus_worktree_inspect
worktree.migration_plan majordomus worktree migrate GET /api/v1/worktrees/migration majordomus_worktree_migration_plan
worktree.status majordomus worktree status GET /api/v1/worktrees/status majordomus_worktree_status
worktree.topology majordomus worktree topology GET /api/v1/worktrees majordomus_worktrees
worktree.trunk majordomus worktree trunk GET /api/v1/worktrees/trunk majordomus_worktree_trunk
worktree.uncommitted majordomus worktree uncommitted GET /api/v1/worktrees/uncommitted majordomus_worktree_uncommitted
integration.cleanup —none GET /api/v1/pull-requests/cleanup majordomus_pull_requests_cleanup
integration.events majordomus prs events GET /api/v1/pull-requests/events majordomus_integration_events
integration.explain majordomus prs explain GET /api/v1/pull-requests/explain majordomus_pull_request_explain
integration.prove_dry_run majordomus prs prove-dry-run GET /api/v1/pull-requests/prove-dry-run majordomus_pull_requests_prove_dry_run
integration.queue majordomus prs status GET /api/v1/pull-requests majordomus_pull_requests
integration.timings —none GET /api/v1/pull-requests/timings majordomus_ci_timings
integration.trains majordomus prs trains GET /api/v1/pull-requests/trains majordomus_pull_request_trains
guard.edit —none GET /api/v1/guard/edit majordomus_guard_edit
monitor.stream —none GET /api/v1/monitor majordomus_monitor
in the Cockpit, of a running server
/cockpit/worktrees Worktrees
/cockpit/peers Peers
/cockpit/integration Integration
served by the executable
/mcp MCP over HTTP for attached clients

Evidence

What is guaranteed

Each claim this feature names, with the status its row declares, the verdict the recorded runs support, and the test that settles it.

Executable use cases

The rules that hold it

  • blocking Scope integritymajordomus.scope-integrity
  • advisory Parallel work requires isolationmajordomus.isolated-parallelism
  • advisory One worker, one clear scopemajordomus.one-worker-one-scope
  • blocking A branch's worktree is at <repo>-wt/<branch>, derived from git, never registeredproject.worktree-topology
  • blocking Nothing a client leaves behind locks another client outproject.shared-server-resilience

The decisions behind it

Using it

The commands that run it

  • majordomus start begin

    Begin one scoped task under a profile, and refuse while another is active.

  • majordomus check verify · read-only

    Is the current task still consistent with its policy, its scope and this checkout?

  • majordomus finish conclude

    Evaluate the finish contract and refuse the outcome if any line of it is unmet.

From the executable's command line

The synopsis of each, as the executable's own help prints it.

  • majordomus serve status [OPTIONS]

    Where this checkout's server stands — absent, starting, ready, outdated or stale — and every server of the repository

  • majordomus worktree status [OPTIONS]

    Where this call is — branch, worktree, canonical or not, uncommitted work — and how many errors the whole topology carries; exit 10 when this worktree is out of place

  • majordomus worktree topology [OPTIONS]

    The whole topology: repository, container, trunk, every worktree, every branch without a worktree, every diagnostic; exit 10 when it has an error

  • majordomus worktree inspect [OPTIONS] <BRANCH>

    One branch: its canonical path, whether it exists, what occupies the path, the worktree holding it, and what stands in the way

  • majordomus worktree migrate [OPTIONS]

    Bring every misplaced worktree to its canonical path, dirty state included, with a fingerprint taken before and after each move; --plan shows the steps and changes nothing

  • majordomus worktree uncommitted [OPTIONS]

    Every linked worktree holding uncommitted work: how many paths, how old the oldest change, what holds it (an active task, an open episode, a process inside) and whether it is abandoned, with the command that would put it on a remote ref. Reads every worktree and writes none

  • majordomus worktree trunk [OPTIONS]

    How far this checkout and the local trunk are from the remote trunk, as of the last fetch, judged against the policy's checkout.trunk_distance: current, lagging, stale, unjudged or unmeasured, with the commands that bring it current. Fetches nothing; exit 10 when stale

  • majordomus prs status [OPTIONS]

    Every open pull request with its disposition, risk and reason, in rank order, from the last recorded observation; exit 10 when the observation is stale or absent

  • majordomus prs explain [OPTIONS] <NUMBER>

    Why one pull request is where it is: the revisions it was decided against, every piece of evidence, its rank and the factors behind it

  • majordomus prs events [OPTIONS]

    The audit trail: every selection, merge, refusal, stale decision and closure this checkout's executor recorded

  • majordomus prs trains [OPTIONS]

    The trains of stacked pull requests, in landing order: each link's disposition, relation to master, prepared head under `refs/prep/<n>` (pushed or pending) and turn. Offline and read-only, from the last recorded observation; exit 10 when it is stale or absent

  • majordomus prs prove-dry-run [OPTIONS]

    Prove the non-mutating cycle moves nothing: snapshot origin's refs, the open pull requests, the audit trail, the lease and the local refs, run refresh, plan, drain --dry-run and cleanup (listing), snapshot again and compare; the refresh's fetched mirrors must equal what origin serves. Exit 10 naming what moved. Takes no flag: there is nothing to turn on

Where this page comes from

the file
.ai/repo/features/coordination.md
the same answer
majordomus product show coordination

Searches the titles and descriptions of every page this site publishes.