Run Parallel Attempts

Start several agent attempts from one commit, compare their diffs, and promote the best result.

Create several ephemeral branches from one commit when you want multiple agents to solve the same task. Each branch starts from the same files without a repository copy.

This guide uses the session branch from Capture Agent State.

Pin the start state

Read the current tip SHA from your backend session record. Use the same SHA for every attempt.

Set PIERRE_ORG and PIERRE_PRIVATE_KEY as shown in the Quick Start.

TypeScript

import { GitStorage } from '@pierre/storage';

const baseSha = process.env.TIP_SHA;

const store = new GitStorage({
  key: process.env.PIERRE_PRIVATE_KEY!,
  name: process.env.PIERRE_ORG!,
});

const repositoryId = 'acme/storefront';
const repo = await store.findOne({ id: repositoryId });

Create the attempt branches

Create each attempt from the same SHA. Branch creation writes refs only and does not copy Git objects.

TypeScript

const attempts = await Promise.all(
  Array.from({ length: 4 }, () =>
    repo.createBranch({
      baseRef: baseSha,
      targetIsEphemeral: true,
    }),
  ),
);

const attemptBranches = attempts.map((attempt) => attempt.targetBranch);

Give each sandbox one branch and one credential. Use expectedHeadSha: baseSha for its first commit, then use each returned commit SHA for the next write.

TypeScript

const attemptSource = 'export const authEnabled = true;\n';

const attempt = await repo
  .createCommit({
    author: { email: '[e-mail]', name: 'Agent 1' },
    commitMessage: 'Attempt 1',
    ephemeral: true,
    expectedHeadSha: baseSha,
    targetBranch: attemptBranches[0],
  })
  .addFileFromString('src/auth.ts', attemptSource)
  .send();

console.log(attempt.commitSha);

Compare the results

Read each attempt tip as a commit diff from the pinned start state. Evaluate each diff with tests, code review, or your own evaluation method.

TypeScript

const currentBranches = await repo.listBranches({ ephemeral: true, limit: 100 });

const results = await Promise.all(
  attemptBranches.map(async (attemptBranch) => {
    const current = currentBranches.branches.find((item) => item.name === attemptBranch);
    if (!current) throw new Error(`No branch exists for ${attemptBranch}`);

    return {
      branch: attemptBranch,
      diff: await repo.getCommitDiff({ baseSha, sha: current.headSha }),
    };
  }),
);

for (const result of results) {
  console.log(result.branch, result.diff.stats);
}

See getCommitDiff() for path filters and response fields.

Promote the winner

Promote the best ephemeral branch to a normal branch. You can then review and merge the normal branch.

TypeScript

const winner = attemptBranches[2];

await repo.createBranch({
  baseIsEphemeral: true,
  baseRef: winner,
  targetBranch: 'agent/fix-auth',
});

Delete the other refs after you no longer need their states.

TypeScript

await Promise.all(
  attemptBranches
    .filter((attemptBranch) => attemptBranch !== winner)
    .map((attemptBranch) => repo.deleteBranch({ ephemeral: true, name: attemptBranch })),
);

Deletion removes the refs. Git objects remain available while another ref can reach them.

See Ephemeral Namespace for promotion details and Ref Policies for per-attempt credentials.