> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 [Store Session State](/docs/guides/session-state).

## Pin the start state

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

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
import { GitStorage } from '@pierre/storage';

const baseSha = process.env.TIP_SHA;
const sessionId = process.env.SESSION_ID;

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

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 TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const attemptBranches = Array.from(
  { length: 4 },
  (_, index) => `sessions/${sessionId}/attempt/${index + 1}`,
);

await Promise.all(
  attemptBranches.map((attemptBranch) =>
    repo.createBranch({
      baseRef: baseSha,
      targetBranch: attemptBranch,
      targetIsEphemeral: true,
    }),
  ),
);
```

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 TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const attemptSource = 'export const authEnabled = true;\n';

const attempt = await repo
  .createCommit({
    author: { email: 'agent-1@example.com', 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 TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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()`](/docs/reference/sdk/get-commit-diff) 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 TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const winner = attemptBranches[2];

await repo.promoteEphemeralBranch({
  baseBranch: winner,
  targetBranch: 'agent/fix-auth',
});
```

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

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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](/docs/guides/ephemeral-branches) for promotion details and
[Branch Protection](/docs/guides/branch-protection) for per-attempt credentials.