Skip to main content
This guide captures the baseline operating model we recommend for production usage.
  • Use branch-per-run for non-trivial agent tasks.
  • Treat main as promoted, reviewed state.
  • Scope API keys to the minimum required permissions.
  • Add metadata in commit messages so runs are traceable.

​
Operational practices

  • Track commit and merge latency in your critical paths.
  • Enforce repository naming conventions and limits.
  • Keep human review workflows for high-impact changes.

​
Repo-per-project

Use a separate repository for each project or similar concept in your application. This keeps history focused, reduces noisy diffs, and lets you apply permissions and retention policies per project. Use this when projects are logically independent and typically reviewed/deployed separately. Some examples of how to decide what’s a repo and what isn’t:
  • n8n-style workflows: each workflow is a separate repo
  • app builder: each user app is a separate repo
  • coding agents: each user codebase is a separate repo
  • VMs & infra: each user volume is a separate repo

​
Checkpoint-per-prompt

Create a checkpoint after each user prompt. This gives you a clean timeline of intent, makes undo/redo straightforward, and lets you restore the repository to a known good state if a later step goes wrong. Recommended for:
  • conversational coding agents,
  • iterative content generation,
  • any workflow where users expect “undo last prompt” behavior.

​
Branch-per-session

Create one branch per user session/chat/run instead of mixing multiple sessions on one branch. Each session can evolve independently, and you can merge or discard without affecting parallel work. Recommended naming: session/<session-id> or proposal/<feature-name>-<run-id>.

​
Short-lived branches

Keep branches temporary. Merge approved work quickly and delete abandoned branches. Short-lived branches reduce drift from main, lower conflict rates, and make reviews easier because diffs stay small. Good rule of thumb: if a branch has been idle for a while, either refresh it from main or close it.

​
Approvals (branch + diff endpoint)

Use a proposal branch for all non-trivial changes, then show users a diff before merge:
  1. Agent writes to a proposal branch.
  2. Use structured diff endpoint to compare the changes to main.
  3. Render the diff in your UI in a way that makes sense for your app.
  4. On user approval, merge proposal into main.
  5. On reject, keep the branch for iteration or discard it.
This pattern gives users explicit control and creates a clear audit trail of what was proposed and accepted. 
// Example approval flow (illustrative SDK shape)
const proposal = await repo.branch.create({ repo: repo.id, name: "proposal/add-forecast-widget" });

// ...
// Agent writes changes on proposal branch
// ...

// Build approval UI from diff (endpoint-backed)
const diff = await repo.diff({
  repo: repo.id,
  from: "main",
  to: proposal.id,
  format: "structured",
});

renderApprovalUI(diff);

if (userApproved) {
  await repo.branch.merge({
    repo: repo.id,
    from: proposal.id,
    to: "main",
    message: "approve proposal/add-forecast-widget",
  });
} else {
  // keep for iteration or clean up
  await repo.branch.delete({ repo: repo.id, branch: proposal.id });
}