# Headless runs

> Run the bitsrun agent on one task from a script or CI with bitsrun -p, choose what it may do with --mode, and read the answer as text or JSON.

Source: https://bitsrun.com/docs/agent/headless/
Updated: 2026-11-09

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.

```bash
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:

```bash
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](https://bitsrun.com/docs/cli/automation/#sign-in-for-ci-with-bitsrun_token)).

## Options

| Option | What it does |
|---|---|
| `-p "<task>"` | The task. Starting it with `/name` runs one of your [custom commands](https://bitsrun.com/docs/agent/extensions/#custom-commands), like `-p "/review src"`. |
| `--output text` or `--output json` | Plain answer (default) or one JSON object. |
| `--mode <mode>` | `manual` (default), `accept-edits`, `auto` or `plan`. Decides what it may do without asking. |
| `--trust-project` | Use the project's `BITSRUN.md`, rules, hooks, MCP servers and commands without asking, as if you had said yes. Remembered until those files change. |
| `-c` | Continue the newest session of this folder instead of starting a new one. |

## 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:

```text
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](https://bitsrun.com/docs/agent/modes-and-approvals/#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):

```bash
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:

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

| Field | Meaning |
|---|---|
| `ok` | `true` when the model answered and nothing was refused. |
| `answer` | The model's final answer. |
| `sessionId` | The saved session, which you can open later with `bitsrun -r`. |
| `refused` | The approvals that were refused. |
| `error` | Present when the run failed, with the reason. |

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

## Example: review every pull request

```bash
#!/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.