moire-parallel

Run N agents at once, each in its own git worktree, with moire reporting when any two of them are about to break each other.

Before anything: should this be parallel at all?

Decomposition is a judgement call and it is yours (or the user's) to make — moire has no opinion about it and will not help.

Parallelise when the work splits into pieces that touch mostly different parts of the codebase, and each piece is independently verifiable.

Do not parallelise when the pieces share a core abstraction, or when one must land before another can be written. Say so and work sequentially instead. Splitting tightly coupled work across agents produces collisions faster than any tool can report them, and serial execution is a legitimate answer, not a failure.

If unsure, prefer fewer agents. Three is usually plenty; the coordination cost grows with every additional one.

Setup

moire init-swarm --agents 3

This creates ../<repo>-agent-1, -2, -3, installs the binary and git hooks into .git/ (shared by every worktree), places the skills, and runs doctor. It is idempotent and --dry-run shows the plan without touching anything.

Each worktree is tracked files only. Install dependencies in each one separately — do not symlink a shared node_modules, .venv, or vendor across worktrees to skip the step. Concurrent agents would then be mutating each other's dependencies, which is exactly the class of interference moire exists to detect.

Observing a peer writes that peer's untracked, non-gitignored files into the repository's shared object store, where they persist refless until git's housekeeping prunes them. Gitignored files are never captured, so make sure .env*, credentials and key material are gitignored before dispatching a swarm. The README section "What observation writes, and where" has the detail.

If you want the optional semantic check (moire verify), configure its checker once, before dispatching anyone. The default checker reads Python only; on any other repository it examines nothing and says so. The measured base rate of the failure verify looks for — a textually clean merge that is semantically broken — is 0 of 672 audited co-active agent PR pairs (docs/MEASUREMENTS.md), which is why verify is optional rather than wired into any hook.