Docs › CLI › Reviewing a branch

Reviewing a branch

Review a branch's changes from the terminal or in a pull request, and get only findings that describe a concrete failure.

On this page

astracode-agent review reads what this branch changed and reports only problems it can show will break: each finding names the input or state and the wrong result that follows. Naming, style and refactoring suggestions are left out. It reports at most eight findings, most serious first, and a review that finds nothing says so. It is read-only: every edit and command is refused.

Terminal

astracode-agent review                       # against the branch's base
astracode-agent review --base origin/main    # against a ref you name
astracode-agent review --output-format json  # for a script

What it compares against

The review covers the changes since the merge base of HEAD and the base, so work others landed on the base meanwhile is not included. Without --base, it takes the first of these that exists:

  1. The branch's upstream (@{upstream}).
  2. The remote's default branch (origin/HEAD).
  3. origin/main, then origin/master.
  4. main, then master.

The diff it reads is cut at 120,000 characters; the result says when it was. The agent reads the code around each change, not only the diff.

Options

OptionDefaultWhat it does
--base <ref>as aboveWhat to compare against. An empty ref, or one starting with -, is refused.
--output-format text|jsontextA readable list, or one JSON object.
--max-steps <n>60The step limit for the review.
--cwd <dir>the current folderAny folder inside the repository; the review runs from its root.
--trustoffLoad the project's rules, skills and agents. Without it the folder is untrusted, because a fork's pull request reaches the review.
-v, --verboseoffThe agent's log and each tool it calls, on stderr.

Output

Text: Reviewed N file(s) against the base, then No findings. or the count and each finding as its severity, file:line, a summary, and the failure on the next line. JSON:

--output-format json

{
  "type": "result",
  "ok": true,
  "end": "finished",
  "base": "origin/main",
  "files": ["src/billing.py"],
  "findings": [{
    "file": "src/billing.py", "line": 42,
    "summary": "Refunds are added to the total",
    "failure": "A refund of 10 on an invoice of 100 totals 110 instead of 90.",
    "severity": "high", "category": "logic"
  }],
  "reported": true,
  "truncated": false,
  "summary": "...",
  "steps": 23
}

severity is high, medium or low; category may be absent. reported is false when the review ended without reporting its findings, and truncated is true when the diff was cut. On failure, error says why.

Exit codes

CodeMeaning
0The review finished, with or without findings. A branch with nothing to review also exits 0.
1It did not finish, ended without reporting its findings, or the gateway refused.
2Not inside a git repository; no common ancestor with the base (In CI, check out with fetch-depth: 0.); could not work out what to compare against; pass --base <ref>; a usage error; or not signed in.
130Interrupted.

Review every pull request

The AstraCode Review GitHub Action runs this review on each pull request and comments on what it finds.

  1. Create an API key on your dashboard under API & SSH keys.
  2. In the repository, add it as a secret named ASTRACODE_API_KEY (Settings, Secrets and variables, Actions).
  3. Add the workflow below as .github/workflows/astracode-review.yml.

.github/workflows/astracode-review.yml

name: AstraCode review
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: AstraCode-io/review-action@v1
        with:
          api-key: ${{ secrets.ASTRACODE_API_KEY }}
InputDefaultWhat it does
api-keyrequiredYour AstraCode API key.
fail-onnoneFail the check on a finding at or above low, medium or high.
max-steps60The step limit for the review.
versionthe latestThe astracode-agent version to install.
github-tokengithub.tokenThe token used to comment. Needs pull-requests: write.

From the editor and the conversation

In a conversation, /review (or /review <branch>) runs the same review. In the editor, Review This Branch does it from the Source Control view; see Git.

If something goes wrong

← Scripts and CI Zed and JetBrains →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference