Inside a Barge session

A Barge worker opens the draft pull request before running its review and manual verification. The intro explains the handoff; here is the order of work inside a session.

The lifecycle

A session moves through five stages: queue, provisioning, workspace, the agent build, and finalize. The stage list is visible in the dashboard, so at any moment you can see which of the five the session is in and how long it has been there.

The worker is a disposable container. Barge attempts to destroy it when the session ends, including on failure or cancellation. A provider teardown failure can leave cleanup pending until reconciliation confirms the worker is gone.

The workspace

A session starts from one of two origins. A cloud start points Barge at a GitHub repository and a ref. A local handoff packages the machine’s current state: reachable commits, a binary-safe patch of tracked changes, and non-ignored untracked files. Both origins land in the same kind of workspace.

Once restored, the worker runs the repository’s own setup. That comes from .barge.yml in the repo root:

version: 1
setupCommand: bun install
testCommand: bun test
validationCommand: bun run check
commandTimeoutSeconds: 600
worker:
  cpu: 2
  memoryMb: 4096
  timeoutMinutes: 120
exclude: []

Configured setup, test, and validation commands run in that order before the agent starts. They can catch a broken starting workspace; passing them is not proof that the agent’s later changes pass. With no config file, those workspace commands are skipped.

Unknown fields are rejected. Worker sizing can be overridden per session with CLI flags (--cpu, --memory, --timeout-minutes). When conventional root Python manifests (requirements.txt, pyproject.toml, or Pipfile) exist, the worker prepares a Python runtime and puts a private virtual environment on PATH before the configured commands run.

The dashboard

The session view shows stage progress, logs, and test output. A session URL means Barge accepted the work, not that provisioning has finished. The laptop can disconnect while the session queues or runs. Use barge get <session-id> to check its state or barge wait <session-id> to wait for it to finish.

Build and draft PR

The agent runs the task against the workspace. Finalization commits and pushes the changes, then opens a draft PR using a GitHub App installation token scoped to the repository. It does not itself rerun the configured workspace checks.

The draft PR exists before the automated review begins. It is not a promise that all checks have passed or that the work is ready to merge.

Review and verification

First, a bounded review and fix loop: the changes get reviewed, findings are reported, fixes land on the same branch, and the review runs again. The loop is capped, so it converges or stops and says what is left rather than spinning.

Second, a manual pass suited to the changed surface. For UI changes, the worker can start the app, poll for an HTTP success response, and drive scripted headless Chromium at desktop (1440x900) and mobile (390x844) viewports. Non-UI work uses API or CLI checks instead.

The reports distinguish passed, failed, blocked, and partial verification. The time budget can also leave stages skipped. Read those results rather than treating a completed session as proof of a clean review.

Findings and results post as PR comments. Screenshots start in temporary worker directories and are attached to those comments. With an installation token, files upload to the repository’s barge/attachments branch through the Contents API. The comment still uses the normal comments API, with links to those files.

Queued follow-ups

Start with --alive to enable dashboard or CLI messaging:

barge cloud owner/repo main "fix the failing tests" --alive
barge message <session-id> "also cover the empty-input case"

Messages queue during the build. After the initial PR and verification, the worker consumes them in order using the build’s resumable agent thread. Follow-up fixes use the same branch. This is not a live interruption of the initial build.

The window stays within the original runtime budget (120 minutes by default); --alive does not extend it. Sessions without keep-alive, sessions without a resumable thread after the build, and terminal sessions reject messages. A separate PR-comment /handoff can request a continuation after the worker is gone. You still decide whether to merge.

The security posture

The local-handoff scanner checks the tracked patch and eligible untracked text up to 1 MiB, not committed history or all archived content. Binary, oversized, and unreadable files are not comprehensively scanned. Findings report kind and location, never the secret value. Packaging stops by default; the explicit --allow-secrets override must not be enabled automatically.

Uploaded workspace archives are encrypted at rest. Workers receive a per-session control-plane JWT and repository-scoped GitHub access. Cleanup of the worker does not erase the run’s logs, and failed local handoffs may retain their encrypted artifact for retry.

Barge is in private beta. Join the waitlist to get an invitation.