Frequently asked questions

Connect GitHub, choose repositories, then ask for a review:

• Sign in with GitHub and choose your personal account or organization under Choose where your repositories live. If it isn’t listed, select Install on GitHub and choose it there.
• On GitHub, choose Only select repositories, pick the ones to review and confirm. In an organization, GitHub asks an owner to approve unless you are one.
• Decide whether HeyDeer reviews on its own: keep Review pull requests automatically on to review every push, up to 5 times per pull request, or turn it off to review only on request.
• Comment @heydeer review on an open pull request.

You need write access to the repository. A new workspace starts on the Free plan with no credit card, and the findings arrive as review comments on the pull request.

You can request a review straight after connecting. HeyDeer reads the pull request’s changes in the context of the whole repository, along with the PR title, description and discussion, and every review already looks for bugs and security issues.

When your first reviews show a gap, add guidance where it belongs:

• AGENTS.md for how your code works and the conventions it follows; coding agents follow it too.
• REVIEW.md for what reviews should look for, leave alone, and how serious an issue is.
• A repository check for a requirement HeyDeer must verify in every pull request that changes certain files.
• Review instructions for guidance a pull request mustn’t change, or that applies to every repository.

As soon as someone asks: comment @heydeer review on a pull request, select Start a review on the Reviews page, or select Re-run on the HeyDeer Review check. A new workspace starts on Manual only, and right after setup HeyDeer asks whether to review automatically.

A workspace admin can change the schedule anytime in Workspace settings → Review rules → When to review:

• Once per PR reviews a matching pull request until one review succeeds.
• On every push reviews when the pull request first matches your filters, then after each push that adds commits, up to 5 times by default.

Automatic reviews skip drafts, forks and dependency updates by default.

Introduce it in stages, and let HeyDeer gate merges once your team trusts its results:

• Try it on a few pull requests: with automatic reviews off, comment @heydeer review on a handful of different kinds and compare the findings with your reviewers’.
• Fill the gaps those reviews show: conventions in AGENTS.md, requirements in repository checks, priorities in review instructions.
• Turn on automatic reviews for one or two repositories (select them in Repositories, then Change schedule), then for the whole workspace.
• Require the HeyDeer Review check, decide on automatic approval and, on a paid plan, set auto-reload and a usage limit.

Move to the next stage when your team acts on most findings and reviews finish without review notes. Workspace admins change the settings; anyone with write access can request reviews.

Any of these reviews the pull request’s latest commit:

• Comment @heydeer review on the pull request.
• Select Re-run on the HeyDeer Review check.
• Select Start a review on the Reviews page in HeyDeer, where you can also choose another depth or feedback scope.

With Review only new changes on, a review covers what changed since the last one; comment @heydeer full review to review the whole pull request again. Requesting a review takes write access, and a requested review is charged like any other but doesn’t count toward Maximum automatic reviews per PR.

Starting a review from HeyDeer lets you choose the depth and feedback scope for that one review:

• Open Reviews and select Start a review.
• Choose the Repository and Pull request. The list shows repositories where you have write access.
• To change the review depth or feedback scope, open Review options; both start at the repository’s defaults.
• Select Run review.

The review then runs and publishes like one requested on GitHub.

After the first review, HeyDeer focuses on what’s new. With Review only new changes on, the default, a later review looks for new findings only in what the pull request’s own commits changed since the last successful review, and rechecks the earlier findings. Commits merged in from the base branch are left out, while conflict resolutions are reviewed.

HeyDeer reviews the whole pull request when:

• Someone comments @heydeer full review, or the setting is off.
• The base branch changed since the last review.
• The last review had review notes or asked for clarification.

The check’s summary shows whether a review covered New changes or the Whole PR.

Each later review rechecks HeyDeer’s open earlier concerns against the current code:

• Concerns that still apply are listed under Earlier concerns to address.
• Concerns HeyDeer can’t verify are listed under Earlier concerns to confirm, with the information it needs.
• With Resolve addressed HeyDeer conversations on, the default, HeyDeer resolves its conversation once the code fixes the concern or shows it was mistaken, or the concern is declined.

The code has to show the fix; a reply saying it’s fixed isn’t enough. Open or unconfirmed concerns block automatic approval and, with Fail the check when issues are found on, fail the check.

HeyDeer posts the findings within your Feedback scope, which sets how sure HeyDeer must be before it reports a finding of each severity (Critical, High, Medium or Low):

• Concise reports Critical findings when likely, High and Medium only when certain, and Low ones only from repository checks. It suits teams that read every comment.
• Balanced, the default, reports Critical findings when suspected, High when likely, and Medium and Low when certain.
• Detailed reports Critical and High findings when suspected, and Medium and Low when likely. It suits teams whose coding agent verifies each finding before fixing it.

Findings outside the scope aren’t reported, don’t fail the check and don’t block automatic approval. To compare scopes, preview them on a completed review in HeyDeer before switching.

Yes. Fix with HeyDeer turns the findings you choose into a pull request you can inspect and merge:

• Select Fix with HeyDeer in a review comment, or Fix findings on the review page in HeyDeer.
• Choose the findings, and use Add instructions for any that need context, such as an approach to take or behavior to preserve.
• Select the button that counts your selection, such as Fix 2 findings.

HeyDeer makes the changes, runs your tests in a sandbox and opens a separate PR targeting your PR’s branch. After you merge it, the next review of your PR rechecks those findings. Fix with HeyDeer is included in every plan.

Autopilot hands a pull request to HeyDeer until it’s ready to merge or needs you. In each round, HeyDeer fixes what’s open, pushes to the PR’s own branch and reviews the new commit, up to its round limit: 5 rounds by default, which a workspace or repository can change. It works on:

• Findings within your feedback scope and open earlier concerns.
• Requests from people with write access in unresolved review conversations and new comments.
• Failing checks: the required ones, or every check except HeyDeer Review.
• Merge conflicts, which it resolves by merging the base branch, never by rebasing or force-pushing.

Start it with the Autopilot button on the review page or in HeyDeer’s review comment, or comment @heydeer autopilot. When it stops, HeyDeer publishes its review and lists what’s left. Autopilot requires a paid plan, and each round uses credits like any other fix and review.

Select Stop Autopilot on its page in HeyDeer or comment @heydeer autopilot stop; anyone with write access can stop it. Autopilot also stops on its own when:

• Nothing is left to fix, or it needs your answer to a question.
• Someone else pushes to the branch, including with GitHub’s Update branch button.
• It reached its round limit, or its rounds stopped making progress.
• Checks were still running after an hour, the PR is in the merge queue, or GitHub rejected its push.
• The PR was closed or merged, or the workspace ran out of credits or no longer has a paid plan.

Its comment on the PR says why it stopped and what still needs you, and mentions whoever started it when it needs them. Starting it again resets the round count and picks up new answers and comments.

Mention @heydeer in a pull request or issue comment, an inline review comment, or the description of a new pull request or issue to ask a question or hand it a job. For example:

• @heydeer what does this function do? explains the code in a reply.
• @heydeer fix the first issue and open an issue for the second opens a pull request with the fix, and the new issue.
• @heydeer do the latest Next.js docs recommend this? checks the documentation on the web.

HeyDeer reads the conversation, works in a sandbox where it can run your tests, and answers where you asked; code changes go to a new pull request unless you ask otherwise. Anyone with write access can ask, and each request uses workspace credits and appears under Tasks in HeyDeer.

Fix with HeyDeer is included in every plan, including Free. A fix needs:

• An open pull request whose branch is in the same repository, not a fork.
• Write access to the repository.
• HeyDeer’s read and write access to Contents, Pull requests and Workflows. If HeyDeer was installed before it requested Workflows access, an installation admin approves the updated permissions on GitHub first.

Each pull request runs one fix at a time, with up to 100 findings.

Yes. Put them in AGENTS.md at the repository root, and HeyDeer reviews every pull request against them; coding agents that support AGENTS.md follow the same file when they write code. Write what a new teammate would need, such as how the code is organized, naming, which helpers and libraries to use, and how errors and tests work, one convention per bullet, with the reason when it isn’t obvious.

A directory that needs its own conventions can have its own file, such as src/payments/AGENTS.md, which adds to the ones above it and wins where they conflict. In a directory without AGENTS.md, HeyDeer reads CLAUDE.md. Write conventions in the file itself, since HeyDeer doesn’t follow imports.

In REVIEW.md, at the repository root or in any directory that needs its own guidance. Use it for:

• What to check that HeyDeer can’t know from the code, such as which log fields count as personal data.
• What to leave alone, kept narrow and naming the paths it covers.
• How serious a kind of issue is, using Critical, High, Medium and Low.
• What evidence a kind of finding needs, when that kind keeps turning out wrong.

A REVIEW.md written for Claude Code Review works as it is. A pull request can edit REVIEW.md, so keep guidance it mustn’t change in review instructions.

A requirement you keep in your repository as a Markdown file in .agents/checks/, with the files it covers listed under files in its frontmatter. HeyDeer verifies it in every pull request that changes those files, with a reviewer of its own for that requirement, so a check is more thorough than general guidance and uses more credits.

Use checks for requirements that are costly to miss and easy to overlook, such as access control on your API routes. A finding from a check names its file and counts toward the HeyDeer Review check and automatic approval. To have checks written for you, choose Set up repository checks on the dashboard: HeyDeer reads the repository and its past pull requests, then opens a pull request that adds checks, using no credits.

Usually the guidance doesn’t cover the changed files. Check the cause that fits:

• A repository check must be a .md file directly in .agents/checks/, with files patterns that match a changed file.
• An AGENTS.md or REVIEW.md must sit in a directory that covers the changed files.
• Review instructions apply to reviews requested after you save, and repository instructions win where they conflict with workspace ones.
• The finding may be outside your feedback scope; try Balanced or Detailed.
• A requirement HeyDeer can’t verify by reading the code needs rewriting as a condition on the code.
• Generated files and lock files the base branch already has are skipped.

After fixing the cause, comment @heydeer review.

Work down this list, which starts with the changes that do the most for the least effort:

• Switch Feedback scope to Concise, after previewing it on a recent review in HeyDeer.
• Mark generated code linguist-generated in .gitattributes.
• Skip bot or throwaway pull requests with automatic review filters, such as a skip-review label.
• Decline findings you’ve decided not to fix, so they aren’t raised again.
• For a kind of comment nobody acts on, add a narrow review instruction with a reason.
• Narrow a repository check’s files patterns if it reports on files it isn’t about.

Remote MCP servers that let reviews and tasks check what the code alone can’t show: how a feature is used, what the logs say, the data in a table or a library’s documentation. They’re included in paid plans, and the owner of the GitHub organization or personal account manages them.

To add one, open Workspace settings → Connectors, select Add connector, enter the server’s HTTPS endpoint and the headers it needs, and select Load tools. Choose the tools to allow and the repositories, then select Save connector. Read-only tools are allowed at first, a connector is used only in private repositories by default, and tool calls add to the work’s credits.

Use Automatic review filters under When to review in Workspace settings → Review rules, or on a repository’s Review rules tab. Each row filters by labels, author, the author’s team, relationship or account type, draft state or source, and a pull request qualifies only when it matches every row. Some common rows:

• Skip all bots: Author account → Is none of → Bot.
• Review only labeled pull requests: PR labels → Is any of → ai-review.
• Let authors opt out: PR labels → Is none of → skip-review.

By default, the filters skip drafts, forks and dependency updates. They apply only to automatic reviews, so you can still request a review of any pull request.

In credits, for the work each review or fix does, so a larger change or a Deep review uses more than a small Standard one. The whole workspace shares one plan and credit balance, with unlimited developers and repositories and no seat fees, so adding teammates doesn’t change the price.

• Every plan includes monthly credits. Free starts with 1,000 credits in the first month and 300 a month after that.
• Any plan, including Free, can add credits at a base rate of $10 per 1,000 credits, with discounts on larger purchases.
• Reviews of public repositories are free up to a fair-use limit.

Paid plans add more monthly credits and parallel reviews, plus Deep reviews, Autopilot and connectors.

HeyDeer stops starting new reviews until the workspace has credits again. A review already running finishes, with HeyDeer covering the unpaid usage, while a running fix stops. When an automatic review can’t start, the HeyDeer Review check says why, and HeyDeer comments once a day on the first such pull request in each repository with a link to plan and credit options.

To continue, add credits in Usage & billing → Overview, wait for the next monthly refresh, or choose a paid plan, then request the review again; later automatic reviews start as usual. On a paid plan, HeyDeer emails the workspace when credits run low and when they run out, and auto-reload can add credits before that happens.

Workspace admins set both in Usage & billing → Overview → Spending controls once the workspace has chosen a plan:

• Auto-reload, off by default, buys a fixed amount of add-on credits at your volume discount whenever the balance falls below a threshold you set, so reviews keep running. It needs an active paid plan and charges your subscription card.
• A usage limit caps the credits reviews and fixes together use in a calendar week or month. Once it’s reached, new reviews and fixes don’t start until the limit resets or you raise it, while running ones finish.

Weekly limits reset every Monday and monthly limits on the 1st, both at 00:00 UTC. Adding credits doesn’t lift a usage limit.

Workspace admins manage the plan in Usage & billing → Overview:

• To upgrade, use Change plan. It applies when you pay: you pay the difference for the rest of the period, get a matching share of the extra monthly credits and keep your renewal date.
• To downgrade, also use Change plan. It applies at the next renewal, and Keep current plan undoes it.
• To cancel, open Billing portal. The plan stays until the end of the paid period, then the workspace returns to Free; select Resume subscription before then to keep it.

Control how many reviews run and how deep they go:

• Keep Default review depth at Standard, and use Deep only where the code needs it.
• Set Review schedule to Once per PR, or lower Maximum automatic reviews per PR.
• Keep Review only new changes on.
• Skip pull requests you don’t need reviewed with automatic review filters, and mark generated files.

On a paid plan, a weekly or monthly usage limit caps spending. Usage & billing → Usage shows the credits used by repository, pull request, review and task.

Every member sees reviews for the repositories they can access on GitHub, and with write access to a repository can start and cancel reviews there. Admins also:

• Change review rules and schedules, which members can view.
• Manage Workspace settings and Usage & billing.
• Change members’ roles.

Connectors are managed only by admins marked GitHub owner or Account owner, and Manual review access can narrow who requests reviews.

Insights sums up what your reviews found and what your team did with it, for a period and repository you choose:

• PRs reviewed, findings, findings per PR and the decline rate.
• Findings by severity over time, and whether a later review found each one fixed, still in the code, or declined.
• The same totals for each repository and, for workspace admins, each pull request author.

Each finding counts once, even when later reviews report it again. A high decline rate in one repository often means HeyDeer is missing context there, which review instructions, REVIEW.md or a repository check can add.

Emails about the workspace’s credits, payments and GitHub access, and never marketing:

• Credits running low (on a paid plan with auto-reload off, at 20% of the plan’s monthly credits) and credits run out.
• A failed subscription payment, a payment your bank asks you to confirm, or a renewal still unpaid after the grace period.
• Auto-reload failing or pausing at a purchase limit, and payments paused while a billing issue is resolved.
• A GitHub organization owner approving a request to connect HeyDeer.

HeyDeer installs as a GitHub App, and choosing Only select repositories limits it to the repositories you want reviewed. The main permissions are:

• Contents read & write: read code and history, and push commits for fixes and @heydeer requests, never overwriting commits on a branch.
• Pull requests read & write: publish reviews and comments, and open, update or merge pull requests you ask for.
• Checks read & write: show the HeyDeer Review check.
• Workflows: update GitHub Actions workflow files when a fix changes them.

Smaller permissions cover commands, Actions logs for Autopilot, organization members for filters and your email for billing notices. HeyDeer doesn’t request Administration access, and each token is scoped to one repository and the permissions its step needs.

What it needs to keep your review history and run the workspace:

• Review and fix results, selected findings and instructions, which can quote the lines they comment on.
• Repository and PR identifiers.
• Account and workspace information, and settings.
• Billing records.

Your repository itself is processed on a temporary clone that’s discarded when the work ends. For connector calls, HeyDeer keeps the tool, time, duration and outcome, but not what was sent or returned.

The HeyDeer Review check on the latest commit names the reason in its title. The common causes, most frequent first:

• The schedule is Manual only, the default for new workspaces: choose Once per PR or On every push.
• The filters skip it, as they do drafts, forks and dependency updates by default: mark it ready, change the filters, or comment @heydeer review.
• The review is queued while capacity is in use: it starts when a slot frees up.
• Once per PR already has a successful review, or the PR reached Maximum automatic reviews per PR: comment @heydeer review.
• The workspace ran out of credits or reached its usage limit: add credits or raise the limit, then request a review.
• Automatic reviews are paused on the PR: comment @heydeer resume.

Usually the repository hasn’t been reviewed yet, or check publishing is off. Check these in order:

• The repository is on Manual only and has never been reviewed: request a review, and later revisions get a check.
• Publish GitHub check is off: turn it on under Publish results in Review rules.
• HeyDeer lacks the Checks permission or access to the repository: a GitHub owner selects Review permission request or Add repositories in Workspace settings → GitHub connection.
• The pull request is closed: reopen it.

Once HeyDeer publishes checks in a repository, every pull request update gets a check result, so a required check never waits forever.

HeyDeer adds 👀 to every command it accepts. Without it, check these:

• Post the command as plain text in a new PR comment or inline review comment, not in code, a quote, an HTML comment or an edit, from a personal account rather than a bot.
• You need write access, and to be listed under Manual review access if it’s limited.
• The workspace may be out of credits or at its usage limit.
• HeyDeer may need the Issues or Pull requests permission: a GitHub owner selects Review permission request in Workspace settings → GitHub connection.
• pause and resume work only on open pull requests.

After fixing the cause, post the command again in a new comment.

Require the HeyDeer Review check and let findings fail it:

• Let HeyDeer review at least one pull request in the repository, so the check exists.
• In your GitHub branch protection rule or ruleset for the base branch, turn on required status checks, add HeyDeer Review and select HeyDeer as its source.
• In HeyDeer, turn on Fail the check when issues are found in Workspace settings → Review rules → Publish results.

A pull request then merges only after its findings and earlier concerns are fixed or declined. A commit HeyDeer doesn’t review automatically, for example after Maximum automatic reviews per PR, also blocks merging until someone requests a review.

The check’s summary counts the findings, open earlier concerns and failed repository checks behind the result. The check fails when:

• Fail the check when issues are found is on, and the review has findings within your feedback scope, open or unconfirmed earlier concerns, or review notes.
• Whatever the setting, a repository check didn’t run, an earlier concern wasn’t rechecked, or HeyDeer couldn’t start or finish the review.

Fix the findings and push, or decline them in their conversations and comment @heydeer review. For an incomplete review, request another; HeyDeer returns a failed review’s credits unless it called a connector.

Automatic approval is off by default; turn it on under Publish results in Review rules. When it’s on, the review’s page in HeyDeer shows Not automatically approved with the reason, such as:

• Findings or earlier concerns remain: fix or decline them, or choose Allow Low issues to approve with only Low ones left.
• The PR’s risk level is above your PRs HeyDeer may approve setting, so a person approves it.
• A question waits under Needs clarification, or the review has review notes.
• The PR changes guidance HeyDeer reads from it, such as AGENTS.md or a repository check, or HeyDeer opened it.
• New commits arrived or the base branch moved after the review.