Skip to content

Several agents on one repository, without stepping on each other

A task claims its scope before the first edit; check and finish refuse a file outside it and report another worktree's overlapping claim; every client of the shared server is a peer that can announce its intent and paths; and each branch has exactly one worktree, derived from git.

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
stable
exposed through
area
coordination
for
ai-native-team
platform-team

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.

The capabilities behind it

The capability modules of the executable this feature names, each with the capabilities it composes. The command line, the HTTP route, the MCP tool and the reference beside every row are projections of one declaration, not four registrations.

Peers peers behaviorally verified

The clients attached to this repository's shared server, named by their own initialize, and what each announced it is working on. In memory; gone with the process.

apps/majordomus-cli/src/capability/builtin/peers.rs

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.

apps/majordomus-cli/src/capability/builtin/worktree.rs

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.

What it answers

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.

The rules that hold it

  • blockingScope integritymajordomus.scope-integrity
  • advisoryParallel work requires isolationmajordomus.isolated-parallelism
  • advisoryOne worker, one clear scopemajordomus.one-worker-one-scope
  • blockingA branch's worktree is at <repo>-wt/<branch>, derived from git, never registeredproject.worktree-topology
  • blockingNothing a client leaves behind locks another client outproject.shared-server-resilience

What is guaranteed

Executable use cases