Superset: Git Worktree Isolation for Parallel Coding Agents

Superset solves the multi-agent filesystem collision problem by giving each coding agent its own git worktree. You can run Claude Code, Codex, or any CLI-based agent in parallel without branch conflicts, file locks, or shared state corruption. The isolation is filesystem-level, not container-based, which keeps startup overhead low but introduces a blocking-hook performance bottleneck when you add plugins. This approach prioritizes local development speed over horizontal scalability.

The Worktree Isolation Model

Git worktrees let you check out multiple branches from the same repository into separate directories. Superset wraps this primitive with task orchestration:

Each agent task spawns a new worktree linked to a unique branch
The worktree directory becomes the agent’s working directory
File changes, dependency installs, and build artifacts stay isolated
When the agent finishes, you review the diff and merge or discard

This avoids container startup overhead (no Docker pull, no image build) and VM memory allocation. The trade-off is that all worktrees share the same .git object database, so disk I/O contention can rise with agent count.

Performance Characteristics

Table 1: Conceptual isolation trade-offs (illustrative, not benchmarked)

Isolation Method	Startup Time	Memory per Agent	Disk I/O Contention	State Collision Risk
Git worktree	Sub-second	Minimal	Shared .git DB	None
Docker container	2-5s	Base image size	Isolated layers	None
VM snapshot	10-30s	Full OS overhead	Fully isolated	None
Shared directory	None	None	Very high	Very high

Superset’s plugin system uses blocking hooks. When a plugin registers a lifecycle event (pre-task, post-commit, etc.), the main execution thread waits for the hook to complete. With multiple agents and several plugins per agent, you get serial hook invocations per lifecycle phase. This becomes a bottleneck as plugin count increases.

Architecture Flow

// Task spawn sequence showing worktree creation and plugin hook execution
async function spawnAgentTask(taskConfig: TaskConfig) {
  // 1. Create isolated worktree
  const worktreePath = await git.worktree.add({
    branch: `task-${taskConfig.id}`,
    path: `/tmp/superset-worktree-${taskConfig.id}`
  });

  // 2. Run blocking plugin hooks (serial execution blocks all agents during hook phase)
  for (const plugin of plugins) {
    await plugin.onTaskStart(taskConfig, worktreePath);
  }

  // 3. Spawn agent process with isolated working directory
  const agentProcess = spawn(taskConfig.agentCommand, {
    cwd: worktreePath,
    env: { ...process.env, ...taskConfig.env }
  });

  // 4. Monitor agent output and state
  agentProcess.stdout.on('data', (chunk) => {
    taskState.appendLog(chunk);
    notifyUI(taskConfig.id, chunk);
  });

  // 5. On completion, run post-task hooks (serial)
  agentProcess.on('exit', async (code) => {
    for (const plugin of plugins) {
      await plugin.onTaskComplete(taskConfig, worktreePath, code);
    }
  });
}

The blocking hook design means plugin authors cannot introduce async work without stalling the orchestrator. If a plugin calls an external API or runs a slow filesystem scan, every other agent waits.

Workspace Presets and Environment Setup

Superset includes workspace presets that automate dependency installation and environment configuration. A preset is a JSON manifest that declares:

Shell commands to run on worktree creation (npm install, poetry install, etc.)
Environment variables to inject into the agent process
File templates to copy into the worktree

This reduces the manual setup tax when spinning up new tasks, but it runs synchronously during worktree creation. If your preset installs dependencies, the agent does not start until the install completes. The synchronous execution model means slow presets delay all downstream task initialization, which compounds when orchestrating multiple agents with heavy dependency graphs.

Diff Viewer and Editor Handoff

The built-in diff viewer shows file changes inline and lets you edit directly in the UI or hand off to your local editor (VS Code, Cursor, etc.) with one click. The handoff opens the worktree directory in the editor, preserving the isolated branch context.

This workflow reduces the review latency tax compared to:

Switching branches manually in your editor (context loss, uncommitted changes)
Using git diff in the terminal (no syntax highlighting, no inline edit)
Opening a web-based review tool (network round-trip, separate auth)

The diff viewer does not support three-way merge conflict resolution. If two agents modify the same file, you resolve conflicts in your editor after handoff.

Failure Modes

Disk space exhaustion: Each worktree duplicates the working directory. Large repositories with multiple active worktrees can consume significant disk space. Superset does not enforce disk quotas or auto-prune stale worktrees.

Shared .git lock contention: Git uses a lock file to serialize writes to the object database. When multiple CLI agents commit simultaneously, lock acquisition can become a serial bottleneck. This is inherent to git’s design and affects any worktree-based orchestration.

These failure modes are manageable at small scale but can compound as agent count increases.

Technical Verdict

Superset solves the multi-agent isolation problem effectively for local development. The git worktree approach delivers near-instant startup and minimal memory overhead, making it practical to run several agent processes concurrently on a developer workstation without resource exhaustion.

The blocking plugin hook model serializes lifecycle events across all orchestrated tasks. A single slow plugin adds orchestration overhead per lifecycle phase that scales linearly with agent count. The shared .git lock file serializes writes to the object database, which can turn parallel agent work into a queue when multiple agents commit simultaneously.

Unlike container-based approaches, Superset avoids image build overhead by leveraging the host filesystem directly. This makes it faster for rapid iteration cycles where agents spawn, execute, and terminate within minutes. For workloads requiring strict resource isolation or long-running agents that produce large build artifacts, container orchestration provides better resource boundaries and eliminates shared lock contention.

Guidance

Use Superset when running 3 to 10 agents per session on the same codebase and you need filesystem isolation with sub-second startup latency. It works best when plugin execution time stays under 500ms per lifecycle event and agent tasks complete within minutes. The built-in diff viewer and editor handoff reduce review friction compared to manual branch switching.

Avoid Superset when you need strict resource limits (CPU, memory, disk) per agent, when your agents run for hours and produce large build artifacts (disk exhaustion risk), or when plugins call external APIs or run slow filesystem scans (blocking hook bottleneck). For workloads with many concurrent agents or CI/CD pipelines, container-based orchestration eliminates shared .git lock contention and provides horizontal scaling.