Headless runs

A headless run is the agent without the interactive screen: you give it one task, it works, prints the answer and exits. Use it in scripts, git hooks and CI pipelines.

bitsrun -p "Summarize what changed in this branch for the release notes"

Before your first headless run

Set up a model once in an interactive terminal, because a headless run cannot ask you questions:

bitsrun code connect

On a CI machine, provide the model's key through its usual environment variable (for example ANTHROPIC_API_KEY) when you set the connection up that way. For a BitsRun connection, also set BITSRUN_TOKEN (see Scripts and CI).

Options

Nothing waits for an answer

A headless run never asks. Whatever the mode would ask you about is refused, reported on standard error, and listed in the result:

Refused (headless runs never ask): <the step it wanted to take>. Use --mode or an allow rule in settings.json.

So decide up front what the agent may do:

• --mode plan to only read and report.
• --mode accept-edits to let it edit files but not run commands.
• --mode auto to let it edit and run commands. Risky commands and credential files are still refused, because they always ask.
• Or keep the default mode and add allow rules, such as "shell(npm test*)", to settings.json. See Permission rules.

In Plan mode the plan itself is the answer; carrying it out is a separate run.

Pipe input in

Anything you pipe into bitsrun is added to the task (up to 1,000,000 characters):

git diff main | bitsrun -p "Review this diff for bugs. Answer with a list."

Output and exit codes

The answer goes to standard output. Progress goes to standard error as one plain line per change, like [working: Running npm test], so you can keep it out of your results.

With --output json, standard output is a single JSON object:

{ "ok": true, "answer": "The branch adds a --dry-run option ...", "sessionId": "01k8y4000d3m00000000000099", "refused": [] }

The exit code is 0 only when the model answered and nothing was refused, and 1 otherwise. Press Ctrl+C to stop a run; it reports "Interrupted."

Example: review every pull request

#!/usr/bin/env bash
set -euo pipefail
git fetch origin main
git diff origin/main...HEAD | bitsrun -p "/review" --mode plan --trust-project --output json > review.json
jq -r '.answer' review.json

This uses a project command .bitsrun/commands/review.md and Plan mode, so the agent reads and reports without changing anything.