Parallel Agents

Verun's core strength is running multiple AI agents at the same time. Each task gets its own isolated git worktree, so agents never interfere with each other.

How Worktree Isolation Works

Every task creates a separate git worktree — a full copy of your repository's working directory on a dedicated branch. Agents read and write files inside their worktree only. Your main branch and other tasks are untouched.

your-project/
├── .git/
├── .verun/
│   └── worktrees/
│       ├── sleepy-capybara-472/   ← Task 1 (isolated)
│       ├── brave-penguin-891/     ← Task 2 (isolated)
│       └── quiet-otter-305/      ← Task 3 (isolated)
├── src/
├── package.json
└── ...

Branch Naming

Each task gets an auto-generated branch name in the format {adjective}-{animal}-{number}. For example:

• sleepy-capybara-472
• brave-penguin-891
• quiet-otter-305

These names are unique per task and deterministic — they are generated from the task ID.

Running Multiple Tasks

1. Create the first task with a description (e.g., "Refactor auth module").
2. Create a second task with a different description (e.g., "Add dark mode").
3. Start an agent session on each task.
4. Both agents work in parallel in their own worktrees.

There is no hard limit on the number of parallel tasks. Practical limits are determined by your machine's resources (CPU, RAM, disk I/O).

Task States

created ──→ active    (session started)
active  ──→ paused    (session closed, worktree preserved)
paused  ──→ active    (session resumed)
active  ──→ completed (user merges/closes worktree)
active  ──→ forked    (Fork from Message → new task created)

• Created: Task exists but no session is running.
• Active: At least one agent session is running.
• Paused: All sessions are closed. The worktree and branch are preserved.
• Completed: The worktree is merged or discarded.

Port Assignment

If your .verun.json defines ports, Verun automatically maps unique ports to each task to avoid conflicts. For example, if you specify [3000], Task 1 gets port 3001, Task 2 gets port 3002, and so on.

{
  "ports": [3000, 5173]
}

Merging Parallel Work

When a task is complete:

1. Review the diff in the built-in diff viewer.
2. Commit the changes within the task's worktree.
3. Push the branch to your remote.
4. Create a pull request from within Verun.
5. Merge via your git hosting platform (GitHub, GitLab, etc.).

After merging, Verun cleans up the worktree. Other parallel tasks continue unaffected.