Paradev's Parallel Agent Orchestration: How Git Worktrees Let Multiple Coding Agents Work the Same Repo Without Colliding

Most coding agents run one session in one terminal. If you want to parallelize tasks across the same repository, you end up juggling terminal tabs, manually creating branches, and hoping agents don’t stomp on each other’s work. Paradev (formerly Superset) solves this with Git worktrees: each agent task gets its own filesystem copy of the repo, its own branch, and its own terminal session. No context collision, no branch conflicts, no manual cleanup.

This is not a new agent. Paradev is orchestration infrastructure. You bring Claude Code, Codex, OpenCode, Gemini CLI, Cursor Agent, or any CLI agent. Paradev wraps them in isolated workspaces and gives you a unified UI for review, commit, and PR creation.

The Worktree Model

Git worktrees let you check out multiple branches of the same repository into separate directories. Paradev creates one worktree per agent task. When you start a new task, the app:

Creates a new branch from your current HEAD
Checks out that branch into a new worktree directory
Spawns a terminal session in that directory
Launches the agent CLI with your prompt

Each agent sees its own isolated filesystem. Changes in one worktree do not affect another until you explicitly merge. The main repository .git directory remains shared, so commits and branches are visible across all worktrees.

Why this matters: Traditional agent UIs assume one session at a time. If you want to run two agents, you open two terminals, manually create branches, and track which terminal is doing what. Paradev automates the branching and directory management, and gives you a sidebar that shows which agents are working, waiting, or done.

Architecture: Workspace Lifecycle

Paradev is an Electron app with a TypeScript backend. The core orchestration loop:

Task creation: User submits a prompt. Backend creates a Git branch and worktree, then spawns the agent CLI as a child process.
Terminal session: Each worktree gets its own pseudoterminal (PTY). The agent writes to this PTY, and Paradev streams output to the UI.
File watching: Paradev watches the worktree directory for file changes. When the agent modifies files, the Changes pane updates in real time.
State tracking: The app tracks agent status (running, waiting for input, completed) by monitoring PTY output and exit codes.

When the agent finishes, the worktree remains on disk. You review changes in the app, commit, push, and optionally open a pull request. The worktree is not deleted until you explicitly close the task.

Handling Overlapping File Changes

Two agents can modify the same file in different worktrees without conflict, because each worktree is a separate checkout. Conflicts only surface when you merge branches.

Paradev’s Changes pane shows diffs per worktree. When you commit and push, the branch goes to your remote. If you open a PR, GitHub or GitLab handles merge conflicts the usual way. Paradev does not attempt automatic conflict resolution. It surfaces the conflict in the PR pane, and you resolve it in your editor or via the web UI.

Trade-off: This model works well for independent tasks (new feature, bug fix, refactor). It breaks down if two agents need to coordinate on the same file in real time. For that, you need a different orchestration pattern (shared state, message passing, or sequential execution).

Port Detection and Browser Previews

Each worktree can run its own dev server. Paradev scans terminal output for localhost URLs and port numbers. When it detects a server, it adds a browser preview pane for that workspace.

How it works:

Agent starts a dev server (e.g., npm run dev on port 3000)
Paradev parses PTY output for patterns like http://localhost:3000
The app opens an in-app browser tab pointing to that URL
Each workspace’s browser tab is isolated, so you can preview multiple servers simultaneously

Limitation: If two agents try to bind the same port, the second one fails. Paradev does not rewrite port numbers. You must configure your dev servers to use different ports, or let them auto-assign.

State Persistence and Session Recovery

Paradev stores workspace metadata in a local SQLite database. Each workspace record includes:

Worktree path
Branch name
Agent CLI command
Last known status (running, waiting, completed, failed)
Terminal scrollback buffer (limited to last N lines)

When you restart the app, Paradev reloads workspaces from the database. If an agent was running when the app quit, Paradev marks it as failed and does not restart the process. You must manually re-run the agent.

Why no auto-restart: Agents often require user input (approval for file writes, API key confirmation). Restarting without context can leave the agent in a broken state. Paradev assumes you will review and re-run manually.

Remote Hosts and Mobile App

Paradev Pro adds remote execution. You can run agents on a Linux server and control them from the macOS app or an iPhone/iPad app. The architecture:

Remote daemon: A Node.js process runs on the remote host, managing worktrees and PTYs.
WebSocket sync: The desktop or mobile app connects via WebSocket. Terminal output, file changes, and status updates stream over the socket.
SSH tunneling: The app uses SSH to forward the WebSocket connection, so no public endpoint is required.

This lets you run heavy agent workloads on a beefy server while reviewing changes on a laptop or phone. The mobile app is read-only for now (no terminal input), but you can review diffs, approve commits, and open PRs.

Scheduled and Event-Triggered Automations

Pro plan includes cron-style scheduling and webhook triggers. You can configure a task to run daily, or start an agent when a GitHub webhook fires (e.g., new issue, PR comment).

Implementation: The remote daemon includes a scheduler (using node-cron) and a webhook listener (Express server). When a trigger fires, the daemon creates a new worktree and spawns the agent CLI with a predefined prompt template.

Use case: Nightly dependency updates, automated code reviews on new PRs, or batch refactoring tasks that run on a schedule.

Failure Modes and Observability

Failure Mode	Symptom	Mitigation
Agent hangs waiting for input	Workspace stuck in “running” state	Manual intervention required; Paradev does not auto-timeout
Worktree disk space exhaustion	New task creation fails	Paradev warns when disk usage exceeds threshold; you must manually delete old worktrees
Port collision	Second dev server fails to start	Configure agents to use unique ports or auto-assign
Git merge conflict	PR shows conflicts	Resolve in GitHub/GitLab UI or local editor; Paradev does not auto-merge
Remote daemon disconnect	WebSocket drops, terminal freezes	App retries connection; if daemon is down, you must restart it manually

Paradev logs agent stdout/stderr to disk (one log file per workspace). The app does not include distributed tracing or structured logging. For production use, you would pipe agent output to your own observability stack.

Code Example: Creating a Worktree Task

Paradev’s CLI command is still superset (legacy name). Here’s how the app spawns a new task:

import { spawn } from 'node:child_process';
import { mkdirSync } from 'node:fs';
import { join } from 'node:path';

interface WorkspaceConfig {
  repoPath: string;
  branchName: string;
  worktreePath: string;
  agentCommand: string[];
  prompt: string;
}

function createWorktreeTask(config: WorkspaceConfig): void {
  // Create Git worktree
  const gitWorktree = spawn('git', [
    'worktree',
    'add',
    config.worktreePath,
    '-b',
    config.branchName
  ], { cwd: config.repoPath });

  gitWorktree.on('close', (code) => {
    if (code !== 0) {
      throw new Error(`Git worktree creation failed: ${code}`);
    }

    // Spawn agent CLI in the new worktree
    const agent = spawn(config.agentCommand[0], [
      ...config.agentCommand.slice(1),
      config.prompt
    ], {
      cwd: config.worktreePath,
      env: { ...process.env, FORCE_COLOR: '1' }
    });

    // Stream output to UI
    agent.stdout.on('data', (data) => {
      // Send to Electron renderer process
      sendToUI('terminal-output', { data: data.toString() });
    });

    agent.on('close', (exitCode) => {
      sendToUI('agent-complete', { exitCode });
    });
  });
}

This is simplified. The real implementation includes PTY allocation, file watching, port detection, and database persistence.

Deployment Shape

Paradev is distributed as:

macOS app: Signed and notarized .dmg for Apple Silicon and Intel
Linux AppImage: Experimental x64 build, not production-ready
Remote daemon: Node.js package installed via npm on Linux servers

The desktop app is self-contained. No cloud backend, no telemetry, no model proxying. You provide your own API keys and agent subscriptions. Paradev does not see your code or prompts.

For remote execution, you run the daemon on your own infrastructure. The WebSocket connection is encrypted via SSH, but you are responsible for firewall rules and access control.

When to Use Paradev

Good fit:

You already use CLI coding agents (Claude Code, Codex, OpenCode) and want to run multiple tasks in parallel
You need to review agent changes before committing, and you want a unified UI instead of terminal diffs
You want to run agents on a remote server and review changes on a laptop or phone
You need scheduled or event-triggered agent tasks (nightly updates, PR reviews)

Poor fit:

You want a single-session agent UI with inline editing (use Cursor, Windsurf, or Zed)
You need real-time coordination between agents on the same file (Paradev does not support shared state)
You want automatic conflict resolution (Paradev surfaces conflicts but does not auto-merge)
You are on Windows (not yet supported)

Technical Verdict

Paradev is production-grade orchestration infrastructure for developers who already use CLI coding agents and need to parallelize tasks. The Git worktree model is sound: it isolates agents at the filesystem level, avoids branch conflicts, and integrates cleanly with existing Git workflows.

The trade-off is manual conflict resolution. If your tasks are independent (new features, bug fixes, refactors), this works well. If you need agents to collaborate on the same file in real time, you need a different architecture.

The remote execution and mobile app are useful for running heavy workloads on a server while reviewing on a laptop or phone. The scheduling and webhook triggers turn Paradev into a lightweight CI/CD system for agent tasks.

Avoid Paradev if you want a single-session agent UI with inline editing, or if you need automatic conflict resolution. Use it if you want to run multiple CLI agents in parallel without juggling terminal tabs and branches by hand.

Agentic AI, minus the noise.