Metagit Agent Coordination

Metagit Agent Coordination Layer (ACL)

Use when more than one agent may edit the same repository, or when an orchestrator must give each agent an exclusive checkout.

Full reference: docs/reference/agent-coordination.md

Task graphs (metagit task …) can store ACL command hints on nodes via metagit task bind-acl without running git — see docs/reference/task-graph.md.

Merge orchestration (metagit merge …) records conflicts with ACL command hints only; it does not allocate branches or worktrees automatically.

The agent scheduler (metagit schedule next) scores ready task nodes and returns dispatch hints without launching models or mutating git — see docs/reference/agent-scheduler.md.

For a composed operator snapshot and next-work envelope across ACL + task graph + optional 0009–0012, use skill metagit-aos (metagit aos|coord status|doctor|next) — see docs/reference/aos.md.

When to use

• Dispatching parallel subagents on the same repo
• handoff.acl_commands appears in metagit agent dispatch-plan
• Preventing two agents from sharing a working directory
• Declaring intended file paths before coding (advisory claims)
• Cleaning up expired leases / orphan worktrees

Do not confuse with handoff leases

Happy path

export METAGIT_AGENT_MODE=true

# 1. Allocate an exclusive agent branch
metagit branch allocate \
  --repository project/repo \
  --agent-id agent-1 \
  --task-id 412 \
  --description auth \
  --json

# 2. Lease it (default TTL 30m; renew while working)
metagit lease acquire \
  --repository project/repo \
  --agent-id agent-1 \
  --task-id 412 \
  --allocate \
  --ttl 30m \
  --json

# 3. Create an isolated worktree (requires active lease)
metagit worktree create \
  --repository project/repo \
  --agent-id agent-1 \
  --task-id 412 \
  --branch agent/412-auth \
  --json

# 4. Optional: advisory file claims before editing
metagit claim declare \
  --repository project/repo \
  --agent-id agent-1 \
  --pattern 'src/auth/*' \
  --json

# 5. Show execution manifest written on create
metagit worktree manifest agent-1

Or allocate + lease in one step with --allocate on lease acquire.

Paths

• Metadata: .metagit/{branches,leases,worktrees,claims,agents,events}/ under the manifest/session root
• Checkouts: <session-root>/<worktrees_path>/<agent-id>/<project>/<repo>/
  • Default worktrees_path: .worktrees
  • Appconfig: workspace.worktrees_path
  • Env: METAGIT_WORKSPACE_WORKTREES_PATH
• Path basenames (e.g. worktrees, .worktrees, campaigns, _campaigns) are reserved and cannot be workspace project names

MCP tools (ACTIVE gate)

Events appear in metagit context events / metagit_events with source=acl.

Conflict handling

• Branch already allocated — choose a different task-id / description, or wait for release
• Lease held by another agent — wait, renew is owner-only; do not force unless authorized
• Claim overlap — advisory; response includes owner + overlapping patterns; subdivide, wait, or override with --strict off (default allows declare with conflict event)
• Worktree already exists for agent+repo — destroy/gc first; one active worktree per (agent_id, repository)

Cleanup

metagit lease renew --lease-id <id> --agent-id agent-1 --ttl 1h
metagit lease release --lease-id <id> --agent-id agent-1 --release-branch
metagit worktree destroy --worktree-id <id> --force
metagit worktree gc
metagit branch cleanup

Anti-patterns

• Two agents editing the same sync-root checkout
• Using handoff --ttl instead of metagit lease for branch ownership
• Naming a workspace project worktrees or campaigns
• Skipping lease acquire before worktree create
• Leaving expired leases / orphan worktrees without gc

Related skills

• metagit-control-center — orchestrator dispatch; run this skill when isolating subagents
• metagit-multi-repo — cross-repo delivery; use ACL per repo before parallel edits
• metagit-sharing-state — shared objectives/handoffs across machines (orthogonal to git isolation)
• metagit-cli — short ACL command cheat sheet