Docs

Quickstart: your first parallel run

Run two agents on the same task, compare them, converge, and land one governed merge — end to end, in about ten minutes.

This walks through the core loop end to end: run two agents on the same task, compare them, converge, and land one governed merge. Budget ~10 minutes.

Before you start

  • •Install Recoder.
  • •Have at least two agent CLIs on your PATH (e.g. Claude Code and Codex), each authenticated the way you normally use them.
  • •Have a local git repository you want to work in.

1. Create a workspace

  1. 1Pick a repository — choose the local folder for your git repo. Recoder checks it's a git repo (and can git init for you if not).
  2. 2Describe the task — a short instruction, e.g. “Add input validation to the signup form and cover it with tests.”
  3. 3Select the agents — check two or more detected agents. Agents that aren't installed/authenticated show their state so you're never guessing.
  4. 4Launch. Recoder creates one isolated git worktree per agent, all sharing the same task group, and starts each agent in its own worktree.

2. Watch the runs

Each run streams its activity. Open a run to see its event stream (what the agent is doing, files it's touching, when it needs input or hits an approval). You can also attach a real terminal to a run's session if you want the raw agent TUI. If an agent needs a decision that policy gates, it surfaces as an approval.

3. Compare the results

When the agents finish, open Compare. Recoder shows each agent's diff side by side, which files are contested (more than one agent changed them), and readiness / mergeability signals per run.

4. Converge

Open Converge. Non-contested files are taken automatically; contested files you resolve — either pick one agent's version wholesale, or synthesize (merge non-overlapping edits from several agents). Converge composes the winners into a fresh governed branch; it never mutates any agent's worktree.

5. Merge (governed)

Land the converged branch. The merge passes the governance gate: if policy allows it outright it merges; if policy requires human sign-off it waits for your approval; either way it's sealed into the audit chain and a ConvergenceEvidence record is produced.