Proliferate: Parallel Agent Architecture with Git Worktree Isolation

Running multiple coding agents in the same workspace is a coordination nightmare. One agent refactors a module while another adds a feature to the same file. Merge conflicts pile up. Terminal sessions collide. Conversation state bleeds across tasks.

Proliferate solves this with git worktree isolation. Each agent gets its own branch, working directory, terminal, and conversation context. Claude Code can refactor authentication on one branch while Codex adds API endpoints on another. Both run in parallel. No file locks. No merge drama until you explicitly choose to integrate.

Architecture: Worktree-Per-Task Isolation

Git worktrees let you check out multiple branches simultaneously in separate directories. Proliferate wraps this primitive into a workspace model where each task spawns:

A dedicated git worktree (isolated working directory)
A branch scoped to that task
A terminal session tied to the worktree path
A conversation thread with the agent
Review state (diffs, approval status, merge readiness)

When you start a new task, Proliferate creates a worktree from your current branch. The agent operates inside that directory. File changes stay local to the worktree until you merge or discard.

State Flow in Subagent Delegation

Proliferate supports hierarchical delegation. A parent agent can spawn a subagent for a scoped subtask. The plumbing:

Parent agent identifies subtask (e.g., “write unit tests for auth module”)
Proliferate creates a child worktree branching from the parent’s current state
Subagent executes in the child worktree with its own conversation thread
On completion, the subagent’s branch is available for the parent to merge or review
Parent resumes with access to the subagent’s changes as a discrete commit or diff

State flows up through git merge operations, not shared memory. The parent can inspect the subagent’s work before integrating it. If the subagent fails or produces garbage, the parent discards the worktree without polluting the main task.

Agent Harness Routing

Proliferate ships native harnesses for Claude Code, Codex, OpenCode, Cursor, and Grok. Each harness translates the IDE’s task model into the agent’s expected input format and streams responses back.

Routing logic:

User selects agent when creating a task (dropdown or config default)
Harness adapter wraps the agent’s API or CLI invocation
Conversation state is serialized per-task, so switching agents mid-conversation requires explicit handoff

You cannot hot-swap agents mid-conversation without losing context. If you start a task with Claude Code and want to switch to Codex, you either:

Merge the current work and start a new task with Codex
Manually copy conversation history into a new task (no built-in migration)

This is a deliberate trade-off. Each harness maintains its own state schema. Cross-agent handoff would require a unified conversation format, which Proliferate does not enforce.

Parallel Execution Model

Proliferate’s UI shows all active tasks in a sidebar. Each task card displays:

Agent name and status (running, paused, completed)
Branch name
Last message in the conversation
Diff summary (files changed, lines added/removed)

You can interact with multiple agents simultaneously. Click a task to focus its terminal and conversation. The agent continues running in the background when you switch focus.

Concurrency Boundaries

Boundary	Isolation Mechanism	Conflict Risk
File system	Separate worktree directories	None (each agent writes to own tree)
Git history	Independent branches	Merge conflicts on integration only
Terminal session	Per-worktree shell instance	None (separate process groups)
Conversation state	Task-scoped JSON or SQLite	None (no shared conversation storage)
API rate limits	Shared across all agents	High (no per-task throttling)

The weak spot is API rate limits. If you run five agents in parallel, they all draw from the same OpenAI or Anthropic quota. Proliferate does not implement per-task rate limiting or backpressure. You will hit 429 errors if you spawn too many concurrent tasks.

Integration Points

Proliferate exposes several extension hooks:

MCP (Model Context Protocol) servers for custom tool calls
Skills (reusable agent behaviors packaged as TypeScript modules)
Computer Use (Anthropic’s desktop automation API)
Browser Use (headless browser control for web scraping or testing)

Skills are the most interesting. A skill is a function that takes task context (files, conversation history, branch name) and returns structured output. Example use case: a skill that runs linters on the current worktree and posts results to the conversation thread.

Skills run in the same Node.js process as the IDE. No sandboxing. If a skill crashes, it can take down the entire IDE. Proliferate does not isolate skill execution in workers or containers.

Code Example: Creating a Task Programmatically

Proliferate exposes a TypeScript API for task creation. This is useful for workflow automation or CI integration.

import { ProliferateClient } from '@proliferate/sdk';

const client = new ProliferateClient({
  workspaceRoot: '/path/to/repo',
});

const task = await client.createTask({
  agent: 'claude-code',
  branch: 'feature/add-auth',
  prompt: 'Add JWT authentication to the API routes',
  parentBranch: 'main',
});

// Stream conversation updates
for await (const message of task.streamMessages()) {
  console.log(`[${message.role}]: ${message.content}`);
}

// Wait for completion
await task.waitForCompletion();

// Review changes
const diff = await task.getDiff();
console.log(diff.summary);

// Merge or discard
await task.merge(); // or task.discard()

The SDK handles worktree creation, agent invocation, and cleanup. You can script multi-agent workflows by spawning tasks in parallel and coordinating merges.

Observability Gaps

Proliferate logs agent interactions to a local SQLite database. Each message, tool call, and file change is recorded. The UI shows a timeline view per task.

What’s missing:

No distributed tracing across subagent hierarchies. You cannot visualize the full call graph when a parent spawns multiple children.
No metrics export. Token counts, latency, and error rates stay in SQLite. No Prometheus or OpenTelemetry integration.
No replay mechanism. You cannot re-run a task with the same inputs to debug non-deterministic failures.

For production use, you would need to instrument the SDK with custom telemetry hooks.

Deployment Shape

Proliferate is a desktop Electron app. It runs locally on macOS (Windows and Linux support planned). The agent harnesses call external APIs (OpenAI, Anthropic, etc.) over HTTPS.

For team use, you can:

Share the workspace repo via git (each developer runs their own Proliferate instance)
Use a shared MCP server for common tools (deployed separately)
Sync task metadata via a custom backend (Proliferate does not include multi-user sync)

There is no cloud-hosted version. You cannot run Proliferate in a browser or on a remote server. The worktree model assumes local file system access.

Failure Modes

Worktree cleanup: If Proliferate crashes mid-task, orphaned worktrees accumulate. You must manually run git worktree prune to reclaim disk space.

Agent hangs: If an agent stops responding (API timeout, infinite loop in tool call), Proliferate does not auto-kill the task. You must manually cancel it. No timeout enforcement at the harness level.

Merge conflicts on integration: Proliferate does not prevent you from merging conflicting branches. If two agents modify the same lines, you resolve conflicts manually in git. The IDE does not provide a visual merge tool.

Subagent state loss: If a parent task is deleted before merging a subagent’s work, the subagent’s worktree is removed. No automatic backup or recovery.

Technical Verdict

Use Proliferate when:

You need to run multiple coding agents in parallel without file conflicts
Your workflow involves hierarchical task decomposition (parent agents delegating to subagents)
You want native integration with Claude Code, Codex, or OpenCode
You are comfortable with git worktrees and manual merge conflict resolution

Avoid Proliferate when:

You need cloud-hosted or multi-user collaboration (no sync, no web UI)
You require strict agent sandboxing (skills run in the main process)
You need observability beyond local SQLite logs (no metrics export, no tracing)
You want automatic merge conflict resolution (manual git merges required)
You need Windows or Linux support today (macOS only for now)

The worktree isolation model is the real innovation here. It turns git branches into first-class concurrency primitives for agent execution. The trade-off is operational complexity: you manage more branches, more worktrees, and more merge decisions. If your workflow already involves heavy branching, Proliferate fits naturally. If you prefer linear history and single-agent execution, the overhead is not worth it.

Agentic AI, minus the noise.