Handoff MCP v0.34 through v0.35 introduces the parallel development foundation for running multiple AI agents on the same project simultaneously.

What Happens When Multiple Agents Work on the Same Project

As AI-assisted development matures, the desire to run several agents at once is natural. But the moment multiple agents touch the same project, you face the same problems human teams have always faced with branch strategies:

No visibility into who's doing what — two agents pick up the same task and one's work is thrown away
Concurrent file edits collide — test results and document updates overwrite each other
No way to see overall progress — you have to check each worktree individually to know what's done

v0.34–0.35 solves these problems by building on git worktree.

Shared Storage: Unified State Across Worktrees

When you add a git worktree, Handoff MCP automatically detects the primary worktree's .handoff/ directory and connects to it via symlink. No configuration needed.

Every worktree sees the same tasks, sessions, memories, and documents. There is no per-worktree copy to maintain. When one worktree completes a task, every other worktree sees it immediately.

A misdetection bug with git submodules is also fixed, so monorepo setups work safely.

Lease-Based Task Locking: Prevent Collisions Before They Happen

handoff_claim_task acquires an exclusive lock on a task. The lock is implemented as a lease protected by flock, with a default 30-minute TTL. The lease auto-extends on every update_task call, so it won't expire during normal work.

If an agent crashes or disconnects without releasing the lease, expired lease auto-recovery kicks in. A lazy scan during load_context, claim_task, dashboard, and other operations detects expired leases and reverts the task to todo so another agent can pick it up.

Administrators can force-release a lock with handoff_reclaim_task.

Agent Registration and Visibility

Calling handoff_load_context automatically registers the agent in .handoff/agents/. Each agent's status is tracked via heartbeat and classified as active / stale / disconnected. Agents with no response for 7 days are garbage-collected.

handoff_overview provides a cross-worktree bird's-eye view of the entire project:

Agent roster — who is connected, who has dropped off
Task × agent claim matrix — which tasks are held by which agents
Worktree × branch × session mapping — which worktree runs which branch under which session

Conflict Detection

When tasks carry scope_paths, handoff_claim_task automatically detects overlap with other active tasks. Directory containment triggers an info advisory; exact file matches trigger a warn. The lock itself is not blocked, but you learn about potential conflicts before they happen.

session-loop Multi-Worktree Automation

Enable auto_assign = true in config.toml's [worktree.session_loop] section, and session-loop automates worktree assignment end to end:

Functional grouping — pending tasks are grouped into per-worktree work units
Parallel execution — each worktree runs its own subagent for implementation, testing, and review
Merge — choose rebase, merge, or squash to integrate results into the main branch
Cleanup — worktrees that are no longer needed are automatically removed

Event Log and Audit Trail

.handoff/events.jsonl records task claim, release, and expiration events. The handoff_events tool supports filtering by since, task_id, agent_id, and event_type. Session creation/closure and agent registration events are also recorded.

Changes at a Glance

v0.34.0 (2026-08-21)

Multi-worktree shared storage — secondary worktrees auto-detect and symlink to the primary .handoff/
Task claim/release — flock-guarded leases (30-min TTL, auto-extend) for exclusive task ownership
Agent registration — auto-register on load_context, heartbeat tracking, status classification, 7-day GC
handoff_list_agents — query registered agents with status filter and claimed-task listing
Event log — .handoff/events.jsonl records claim/release/expired events
Expired lease auto-recovery — lazy scan on operations detects expired leases, reverts tasks to todo
Dashboard enhancements — per-task claim state, stale/expired warnings, agents section
Version marker — .handoff/version with version-mismatch warning
[worktree] config section — handoff_root override, auto_link toggle
Advisory warnings — warns when updating a task held by a different agent

v0.35.0 (2026-08-22)

Session scope auto-detection — agent_id, worktree, scope (primary/worktree/ephemeral) inferred from git worktree relationship
handoff_overview — agent roster, task × agent matrix, worktree × branch × session mapping
handoff_reclaim_task — admin force-release of leases
Conflict notification — scope_paths overlap detection (info: directory containment, warn: file match)
handoff_events — filtered event log queries
Auto-schedule agent awareness — agent_capacity (claimed vs max-concurrent) and ready_tasks
[worktree.session_loop] config — auto_assign, merge_strategy, max_concurrent_wts, auto_cleanup
session-loop multi-WT orchestration — functional grouping → parallel execution → merge → cleanup

v0.35.1 (2026-08-25)

session-loop skill split — reduced from 1,173 to 463 lines; the oversized skill had been causing Claude to hallucinate execution

Install or Update

npx handoff-mcp-server@latest

If you use it as a Claude Code plugin:

/plugin install alphaelements/handoff-mcp

See Handoff case studies