Review code with Arcanist
Arcanist reviews your changes in a private copy of your repository. It reads the code and runs checks to investigate possible bugs, then gives you a merge recommendation with the evidence behind each finding.
Get started
You need a GitHub account and write, maintain, or admin access to the repository. To review on GitHub, you also need an open pull request.
- Open Arcanist and select Continue with GitHub.
- Select Grant GitHub access and choose which repositories the GitHub App can access. Return to Arcanist and select Refresh repositories.
- Choose a repository and start preparation. Arcanist installs the dependencies and sets up a private environment to run your code.
- Open Reviews and choose a pull request. Select Review this PR when the repository is Ready, or Queue this PR to start after preparation finishes.
You can also start a review by adding this comment to a pull request:
@tryarcanist /review
Read the result on GitHub or in Reviews. Check that the reviewed commit matches the code you plan to merge.
A review helps you decide what to fix. Keep your tests and CI checks, and review the evidence before you merge.
Connect your repositories
The Arcanist GitHub App needs access to each repository you want to review. You can inspect its permissions on GitHub.
Find a missing repository
Confirm that you have write, maintain, or admin access on GitHub. Then check that the GitHub App has access to the repository and select Refresh repositories in Arcanist.
If your organization requires approval for new GitHub Apps, ask an organization admin to approve Arcanist. Return to Arcanist and refresh the list after approval.
If your organization uses single sign-on (SSO), select Authorize with GitHub. Complete the organization authorization, then return and select Check again.
Invite your team
Open Settings, then People. Select Invite teammates and Generate invite link. Send the link to the people you want to join your workspace.
Anyone with the link can join after signing in with GitHub. The invite window shows when the link expires, and a new link replaces the old one.
Workspace admins manage people, roles, billing, and review defaults. Members can prepare repositories they can write to, start reviews, and manage their own CLI tokens.
Prepare an environment
An environment is a private copy of your repository with the dependencies needed to run its code. Arcanist prepares the environment before it runs reviews.
Choose repositories during setup, or open Repositories to add them later. You can leave the page while preparation runs and return to Repositories to check progress.
Understand the status
| Status | What to do |
|---|---|
| Preparing | Wait while Arcanist installs dependencies and checks the setup. |
| Ready | Start a review. Arcanist can run code in the environment. |
| Needs your input | Select Add credentials or Answer question and provide the requested information. |
| Waiting for Arcanist | Arcanist is working on a setup issue. You do not need to retry. |
| Setup stopped | Select Try again. If GitHub access is missing, select Review GitHub access and restore it first. |
Provide setup information
If setup asks a question, select Answer question, enter your answer, and select Send.
If setup requests credentials, enter them through Add credentials. Optional credentials can be skipped. If you cannot supply a requested value, select Can't provide these so Arcanist can continue without it.
Saved secret values are not shown again in the browser. Do not put secrets in pull request comments, review replies, or support messages.
Prepare related repositories
On a Team workspace, you can select up to 20 repositories per batch. Each gets a separate environment by default. Starter supports one repository.
For an application that needs several repositories together, open Advanced setup and select Prepare repositories together. Choose a primary repository and up to seven related repositories under the same GitHub owner.
Arcanist places those repositories in one environment. Pull requests on the primary repository trigger reviews. Select Prepare in separate environments to return to individual setup.
Read a review
A review includes a merge recommendation, a summary, and the commit it checked. Each finding explains a problem, the affected code, and a suggested fix. Findings can include reproduction steps, observed results, and a prompt for your coding assistant.
Understand the recommendation
| Recommendation | Meaning |
|---|---|
| Ready to merge | Arcanist found no issue that blocks the merge. Check the evidence and your CI results. |
| Ready to merge with findings | The app can show this result when findings do not block the merge. Decide when to address them. |
| Hold off on merging | At least one finding needs a fix before you merge. |
GitHub uses Ready to merge for both clear reviews and reviews with only nonblocking findings. The GitHub comment lists blocking findings. Open the app or use the CLI for the full findings list.
Read the evidence
Each blocking finding explains what can go wrong and why the change causes it. Read the reproduction steps and results before applying a fix.
The summary can include a Ruled out section for problems Arcanist investigated and disproved. It can also show a blast radius, which describes who would be affected if the change failed. The next line, labeled "If this breaks:", explains the possible effect. Low means no customer would see a failure. High means all customers could be affected, or stored data or sent messages could be wrong.
If a finding is incorrect or missing context, reply to its GitHub thread with the relevant details. Resolve the thread when your team has decided how to address it.
Review new commits
A review applies to the commit it names. After a code change, start another review in the app or comment @tryarcanist /review again. Automatic reviews can also review new pushes when enabled in Settings.
From the second review onward, open Review history in the GitHub comment to compare results. Carried findings are marked still open, and newly reported findings are marked new. Fixed findings leave the list.
Understand GitHub approvals
Arcanist posts a comment by default. An admin can enable approval for clear reviews under Settings, then Reviews, then Approve. A review with findings never approves the pull request.
Arcanist does not request changes, merge your code, or deploy your application.
Set review defaults
Workspace admins can change defaults under Settings, then Reviews. Start with a manual review if you want to check the setup before enabling automatic reviews.
Automatic reviews
Turn on Review new pull requests to review pull requests when they open. Use Skip draft PR reviews to exclude drafts. Re-review on every push controls whether new commits get another review on a pull request Arcanist already reviewed.
Add Skip rules to exclude a bot author, a repository, or a source branch pattern. Branch patterns support * and ? wildcards. Skip rules affect automatic reviews only, so you can still request a manual review.
After changing a rule, check a matching pull request to confirm the behavior you want.
Approval settings
Under Approve, select the blast radius levels at which a clear review can approve a pull request on GitHub. The choices are Low, Medium, and High. Leave all levels unchecked to post every review as a comment.
Review access
A person who requests a manual review must be an active workspace member with write, maintain, or admin access to the repository.
A review can use stored credentials only while the requester remains a workspace member with write access. Pull requests from forks do not receive your credentials when the application starts. A fork is a copy of your repository under a different owner.
Use the CLI
The Arcanist command-line tool lets you set up a repository and request reviews from a terminal or coding agent. You need Node.js 22 or newer.
Set up your repository
Run the setup command from your repository:
npx --yes @tryarcanist/cli@latest setup
Setup installs the arcanist command and starts sign-in. Enter the displayed code in your browser and approve access. Follow the returned instructions to connect GitHub and prepare the repository.
For a coding agent, add --json. The output gives the next action and any approval link. You approve sign-in and GitHub access yourself.
npx --yes @tryarcanist/cli@latest setup --json
Review local commits
Commit your changes, then run:
arcanist review
A local review compares your committed changes with the repository's default branch. Uncommitted changes are not included. Local reviews require a paid plan or a pilot and a token with write access.
For output a coding agent can read, use:
arcanist review --json
Read the recommendation and findings, apply any fixes, and commit them before requesting another review.
Sign in for automation
For a machine without a browser, create a Write token under Settings, then CLI. Pass the token through standard input to arcanist auth login --token-stdin. Do not put it in a command argument or commit it to your repository.
A Read token can list reviews, sessions, and events. It cannot start a review.
Run arcanist --help for available commands, or read the CLI reference.
Get help
A review does not start
Check that the repository is Ready and that you have write access. For automatic reviews, check the draft setting and Skip rules under Settings, then Reviews. Try a manual review from Reviews to check the setup.
Setup needs attention
Open Repositories and read the current status. Answer any question or credential request there. For Setup stopped, select Try again. For Waiting for Arcanist, wait for the next status instead of restarting setup.
Contact us
Email team@tryarcanist.com with the repository name, pull request URL, and the message you see. Include the reviewed commit if the problem concerns a result. Do not include secret values or CLI tokens.