Ferretta / Documentation

First review

See an example, connect a model, and review a real pull request.

Installed a release? Skip the build steps below and use ferretta wherever the guide shows bin/ferretta.

Start with a small, trusted PR. The current reviewer is advisory: it reads a submitted PR, runs your configured checks locally, and saves a report. It does not post comments or change the PR.

See the result first

Build with Go 1.26.5 and Make, or use a matching release binary when available:

make build
bin/ferretta demo
bin/ferretta demo --outcome question
bin/ferretta demo --outcome lgtm

These are labeled fictional examples, including fictional commits and evidence. They need no account or model and make no network calls.

Connect a local model

Install and start Ollama , then explicitly download a model that supports tools and thinking:

ollama pull qwen3:4b-thinking
bin/ferretta init --discover

Discovery reads model inventories from common Ollama, LiteLLM, vLLM, LM Studio, and llama.cpp endpoints. A discovered endpoint is only a candidate: proxy routing and capabilities can be unknown. Only the Ollama adapter is implemented. Discovery never starts a service, downloads a model, generates responses, or runs checks.

From the trusted repository checkout, run:

bin/ferretta init

Choose an installed model and a check command. Setup suggests make check when that target exists, or go test ./... for a Go module. Inspect the proposal before saving: later reviews execute that command against PR code as your local OS user. A detached worktree is not a security sandbox.

Setup creates .ferretta/review.json and refuses to overwrite existing files. This repository already has a policy; to try a different model, use another path:

bin/ferretta init --model qwen3:4b-thinking --policy .ferretta/local-review.json

For an installed model whose thinking controls are not reported, an explicit --thinking provider_default policy can accept the model default while keeping its effective thinking setting unknown. Automatic setup never silently makes that choice.

Use the same --policy path with subsequent commands. --yes supports unattended setup but requires explicit --model and --check '["make","check"] arguments. New policies request a 16,384-token context, 100 turns, at most 4,096 generated tokens per turn, and a ten-minute attempt. Larger contexts use more memory; these defaults are not a hardware sizing guarantee. Choose a different model-turn ceiling with init --max-turns N (0 disables it); --timeout 0 disables the attempt deadline. --max-output-tokens N controls per-reply generation. The timeout and context bound can stop a review before it reaches that ceiling. Large PRs or conversations may exceed the conservative context admission bound and produce an incomplete review. No evidence is silently truncated to fit.

Optionally test the selected model’s tool protocol before connecting GitHub:

bin/ferretta model test --policy .ferretta/local-review.json

This command runs inference: two turns, using the policy’s output allowance and at most two minutes total (or the policy timeout, if shorter). Tool results are inert fixtures; no repository checks or model-requested commands execute. It stops on failure without automatic retry. A successful result establishes basic tool continuation, not review quality or a particular effective reasoning effort. On alpaca, Qwen qwen3:4b-thinking passed this test with thinking enabled, a 16K context and 4,096 output tokens per turn. A lower 2,048-token probe allowance produced an incomplete response; allow bounded failure rather than assuming every small model reliably finishes every task.

Connect GitHub and verify readiness

bin/ferretta auth github --setup

Follow the printed GitHub App registration steps . Once you have an installed App and its private-key file, verify and save its connection:

bin/ferretta auth github --configure --repo owner/repo \
  --client-id APP_CLIENT_ID --installation-id NUMBER \
  --private-key-file /absolute/private/path/app.pem
bin/ferretta doctor --repo owner/repo --policy .ferretta/local-review.json

Connection setup verifies read access before writing a new machine configuration. It stores the key path, not the key or temporary token, and preserves existing configuration. doctor checks Git, matching checkout origin, App access, policy, and model capability metadata. It lists required checks without executing them and never runs inference. Exit 2 means something is not ready; the output gives the next step. No OpenRouter key is needed: hosted inference and paid/free routing are not implemented yet.

Review an actual PR

Replace owner/repo and 123 with an open, non-draft PR in your trusted checkout:

bin/ferretta review --repo owner/repo --pr 123 --policy .ferretta/local-review.json

The default output is a readable report with exact commits, findings, questions, tradeoffs, model provenance, available token usage and next actions. Add --format json for scripts. Exit 0 means advisory LGTM with configured checks passing; exit 2 means changes, a question, or incomplete work; exit 1 means a setup/output failure. A report is not permission to merge.

Private checkpoints and a JSON report remain in .ferretta/runs/. Do not publish session files: they contain model messages and repository content. Ordinary invocations start new attempts. Enable proposal sessions with --publish-proposals --humans YOUR_LOGIN to post questions and resume after human replies. review --resume PATH polls once; the service does not yet poll replies.

After the first useful review, consult service installation for macOS/Linux boot supervision. The current service durably collects PR revisions only; it does not dispatch these reviews automatically.