Review Studio

Review Studio is a local-first repository review dashboard. It inspects a selected Git repository, keeps evidence revision-bound, and presents deterministic review results through a private local interface.

It is a desktop-style local tool, not a hosted website: the service binds to 127.0.0.1, and the dashboard is opened in your browser only on your own machine. Review Studio does not submit GitHub reviews or modify repository source files. Review artifacts can be exported as local Markdown, JSON, or self-contained HTML.

Install the published package

Requirements: Python 3.13 or newer and uv.

uv tool install review-studio
cd /path/to/your/repository
review-studio

The published package includes the dashboard, so Bun is not required for normal use. Review Studio opens the dashboard at a loopback address such as http://127.0.0.1:3000. If that port is busy, it selects the next available loopback port.

Useful options:

review-studio --help
review-studio --workspace /path/to/your/repository --no-open
review-studio --port 3012

--workspace selects the repository to inspect; when omitted, Review Studio uses the current directory. --no-open starts the local service without opening a browser window. --port requests a loopback HTTP port between 1 and 65,535.

What it does

Review Studio provides bounded actions for repository evidence, including local change analysis, testing and coverage analysis, runtime-log diagnosis, dependency and documentation scans, security review, type analysis, and a full review flow. Actions stop with a specific Blocked result when required evidence is missing instead of inventing a result.

Deterministic handlers run first and remain authoritative. AI is optional and must be enabled per action. Before a provider request, Preview remote context shows the eligible files, evidence classes, estimated size, destination host, redaction count, truncation state, and digest. A workspace change after preview invalidates the remote call and preserves the deterministic result.

Provider credentials are optional. Review Studio supports OpenAI, Anthropic, and OpenAI-compatible providers. On macOS, credentials are stored in the local Keychain rather than returned to the browser or written to SQLite. Provider failure, rate limiting, malformed output, or missing evidence leaves the local result available and marked partial or unavailable.

The GitHub read adapter is opt-in and requires authenticated gh plus REVIEW_STUDIO_ENABLE_NETWORK=1. It reads PR metadata and a bounded remote patch, including changed paths and added/deleted line evidence. Start the process with the flag when you want to use Analyze GitHub PR:

REVIEW_STUDIO_ENABLE_NETWORK=1 review-studio --workspace /path/to/your/repository

Without that flag, NETWORK_DISABLED is an intentional safe block, not a failed analysis. Review Studio does not execute reviewed repository code or AI-generated commands, and it does not automatically commit, push, approve, or write to GitHub.

Interpreting review output

Review Studio is an evidence workspace, not an autonomous merge approval. Analyze Current Diff reports revision-bound diff facts and conservative heuristics; Run Full Review combines the available local analyzers but does not replace the repository's tests, lint, type checks, security tooling, or human review. Findings can be inferred or unverified, and a clean result is not proof that a change is safe.

The Visualize PR Changes action renders a bounded changed-file topology graph in the dashboard. Directory nodes are connected to the files they contain; link lines are directory-membership evidence, not inferred code dependencies. Node size reflects the file's additions plus deletions. Treat the graph as change navigation evidence, not as a semantic dependency or correctness claim.

The Analyze GitHub PR action reads pull-request metadata and a bounded remote patch through the opt-in GitHub CLI adapter—title, state, URL, file count, line counts, changed paths, and changed-line evidence. It does not post comments, create statuses, or write to GitHub. Use Analyze Current Diff when reviewing local uncommitted changes.

Repository review policy

Review Studio accepts an optional repository-owned policy at .review-studio/config.toml. Copy the example below and commit the policy when it should apply consistently across contributors:

cp .review-studio/config.toml.example .review-studio/config.toml

The policy supports review_model, a separate triage_model, reviewer context, ignore globs, and bounded path-scoped rules. Invalid policy fails closed to built-in defaults. Ignored paths are excluded from optional AI context; they are not deleted or modified.

Repeated local reviews persist revision-stable finding threads. Unchanged revisions carry local dismissals or resolutions without another AI request. A changed revision reopens previously triaged findings so an old dismissal cannot silently suppress new evidence. This is local triage only; GitHub conversations and inline comments are not yet connected.

For a review-ready Markdown file, run Run Full Review, Generate PR Summary, or Create Review File, open the completed job, and use the artifact ledger's Download action. Full Review now creates its evidence-linked Markdown artifact automatically; the summary and explicit review-file actions remain available for narrower outputs. The deterministic output uses bounded local evidence only. If AI is explicitly enabled, previewed, and successfully run, Generate PR Summary also creates a separate AI-enriched Markdown artifact with the provider, model, context digest, and unverified AI findings. To place a copy in the repository, open a completed local review and explicitly choose Save copy to workspace.

Run from a source checkout

Requirements: Bun, Python 3.13 or newer, and uv.

bun install --frozen-lockfile
bun run build
uv lock --check
uv sync --frozen
uv run review-studio

This builds the dashboard, installs the locked Python environment, starts the loopback-only backend, and opens the local interface. For a different port or no browser window, pass the CLI options through the backend command:

uv run review-studio --no-open --port 3012

To install the checkout as an editable command during development:

bun run build
uv tool install --editable .
review-studio

Local data and review files

Review Studio stores its local application database and generated artifacts under the platform user-data directory. Generated Markdown is available from the completed job's artifact ledger: Run Full Review creates a revision-bound evidence-linked review artifact automatically; Generate PR Summary creates a deterministic summary artifact and, only after a successful opted-in AI pass, a separate AI-enriched artifact. Create Review File creates an editable evidence-linked review artifact using the review template described below. Use the download action in the job detail view to retrieve either file. Generated repository output such as .next, node_modules, and build directories is excluded from source evidence, while coverage reports remain available to the coverage analyzer.

Review file quality and template

The review file is rendered by review_studio/artifacts.py and includes the revision, worktree fingerprint, summary, active findings, evidence locations, severity, confidence, verification state, rule IDs, bounded code snippets where available, validation hints, impact, recommendations, known unknowns, and provenance. It is a local Markdown evidence packet—not a GitHub approval, SARIF report, or proof that the change is safe. Findings from deterministic analyzers are conservative but can be incomplete; AI findings are explicitly marked unverified. The file records the AI provider and model when an AI pass actually ran. Saving an explicit workspace copy does not change the review fingerprint; later source changes still mark the review stale.

AI is never implicit: the user must enable it for that action, preview the exact redacted context, and run with the matching context digest. The deterministic handler runs first. If the provider is unavailable, over budget, stale, or returns invalid output, Review Studio keeps the deterministic result and marks the AI step unavailable or partial. Provider/model and usage metadata are stored in the local usage ledger; credentials are kept in the macOS Keychain and are not written to the review file or database.

An optional workspace copy of a completed review is written under .review-studio/reviews/ when you explicitly choose Save copy to workspace. It is visible in Git status so it can be reviewed before sharing. The actions do not silently write files into the repository.

Only one Review Studio process should use the local application database at a time. If an action reports that the database is busy, close the other Review Studio process and retry; the API returns an actionable 503 response instead of hiding this condition behind a generic server error.

Verify changes

bun run build
uv lock --check
uv sync --frozen
bun run check

The test suite covers the API, action contracts, built dashboard, persisted job and review state, provider-secret isolation, staleness, artifact containment, remote-context preview invalidation, bounded GitHub patch parsing, repository review policy, revision-stable triage, provider fallback, budgets, AI-output validation, AST analysis, redaction, and optional-input paths.

The CodeCanary parity assessment and current limitations live in docs/codecanary-parity.md.

Release a new version

Merges to main do not publish a package. Releases are intentional: use the version helper, review the diff, commit it, and run the manual GitHub Actions workflow. The complete TestPyPI-first procedure is in docs/releasing.md.

uv run scripts/release_version.py patch --dry-run
uv run scripts/release_version.py patch

The helper updates pyproject.toml and regenerates uv.lock. It accepts patch, minor, major, or an explicit MAJOR.MINOR.PATCH version. It never commits, tags, pushes, or publishes.

Release notes live in CHANGELOG.md. Security reports should follow SECURITY.md.

License

Review Studio is distributed under the MIT License.