# AI review usage and limits
Source: https://docs.cubic.dev/account/ai-review-usage
How GitHub PR AI review usage and billing-period limits work.
cubic measures GitHub PR AI review usage in **reviewed lines** — the changed lines of code cubic actually reviewed in completed PR reviews.
Auto-generated files, binaries, vendored code, and anything matching your ignore patterns are discounted automatically and barely touch your quota. So a 30,000-line PR that's mostly a regenerated lockfile counts as a small fraction of that.
## Paid team capacity
Each paid seat adds to a shared reviewed-line pool for your whole team.
| Plan | Reviewed lines per seat per billing period |
| ----------- | ------------------------------------------ |
| Trial | 20,000 |
| Team (paid) | 40,000 |
| Pro | 80,000 |
A 5-seat Pro team gets `5 × 80,000 = 400,000` reviewed lines per billing period, pooled across everyone.
You can see your current usage, reset date, and a breakdown by review type, base branch, and repository in **[Settings → Usage](https://www.cubic.dev/settings?tab=usage)** when reviewed-line limits apply to your installation. The quota resets with your billing period, not a rolling 30-day window.
## What is not included
The reviewed-line meter applies to GitHub PR AI reviews. Other cubic features use separate limits and do not consume this reviewed-line pool:
* CLI/local reviews
* Codebase reviews and daily scans
* Wikis
* cubic coding agents
## When you run out
If your team uses its full reviewed-line capacity, new GitHub PR AI reviews pause until the next reset or until you add more capacity. Existing comments stay on PRs, and replying to cubic still works. Other features are unaffected by this reviewed-line quota because they have their own limits.
Paid workspaces can use [flex capacity](/account/flex-capacity) to keep reviews running automatically after included usage runs out. Flex capacity costs \$20 per 10,000 extra reviewed lines, is billed only as used, and stops at the monthly spend limit you set.
## Tips to reduce usage
Use these ideas when you want to lower reviewed-line consumption without changing your plan. Most options live in [AI review settings](https://www.cubic.dev/ai-review) or [`cubic.yaml`](/configure/cubic-yaml).
* **[Disable automatic reviews](https://www.cubic.dev/ai-review?tab=setup\&card=ai-review-card-code-review-agent)** for repositories where you only want cubic to review PRs manually. Turn off AI reviews for the repository, or set `reviews.enabled: false` in [`cubic.yaml`](/configure/cubic-yaml).
* **[Ignore specific files or directories](https://www.cubic.dev/ai-review?tab=setup\&card=ai-review-card-ignore-patterns)** that do not need AI review. Add file globs under **Ignore files**, or add them to `reviews.ignore.files` in [`cubic.yaml`](/configure/cubic-yaml).
* **[Ignore test files and fixtures](https://www.cubic.dev/ai-review?tab=setup\&card=ai-review-card-ignore-patterns)** if your team generates a lot of test code. Choose the repository, open **Ignore files**, and add file path patterns such as `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `tests/**`, `test/**`, or `fixtures/**`.
* **[Turn off automatic incremental reviews](https://www.cubic.dev/ai-review?tab=setup\&card=ai-review-card-incremental-reviews)** to review a PR once when it opens instead of re-reviewing every pushed commit, or set `reviews.incremental_commits: false` in [`cubic.yaml`](/configure/cubic-yaml). You can still request an incremental review by commenting `@cubic-dev-ai incremental review`.
* **[Use the cubic CLI locally](/ide/cli-review).** CLI and local reviews don't draw from your reviewed-line pool, so running in-progress checks with the cubic CLI keeps your cloud capacity for the PRs that need it.
* **[Skip automatic reviews on non-default base branches](https://www.cubic.dev/ai-review?tab=setup\&card=ai-review-card-ignore-pull-request-patterns)** when long-lived branches do not need continuous review, or set `reviews.ignore.base_branches` in [`cubic.yaml`](/configure/cubic-yaml). You can still request a review with `@cubic-dev-ai review` when one is useful.
* **Avoid unnecessary full reruns.** Pushing commits triggers incremental reviews when they are enabled. You can also comment `@cubic-dev-ai incremental review` to review only the changes since cubic's last completed review. Incremental reviews count only newly reviewed changes, while `@cubic-dev-ai review this PR` runs a full review and counts reviewed lines again.
* **[Use PR label ignores](https://www.cubic.dev/ai-review?tab=setup\&card=ai-review-card-ignore-pull-request-patterns)** for work-in-progress PRs. Add label patterns, or set `reviews.ignore.pr_labels` in [`cubic.yaml`](/configure/cubic-yaml), to suppress automatic reviews, including push-triggered incremental reviews, while still allowing manually requested reviews.
For example:
```yaml theme={null}
reviews:
enabled: true
ignore:
files:
- 'dist/**'
- 'generated/**'
- '**/*.test.*'
- '**/*.spec.*'
- '**/__tests__/**'
- '*.lock'
```
When a file matches your ignore patterns, cubic skips it during PR review, so it does not spend reviewed-line capacity on that file.
## How to get more
* **[Set a flex capacity spend limit](/account/flex-capacity)** to cover overages automatically at \$20 per 10,000 extra reviewed lines.
* **[Upgrade to Pro](https://www.cubic.dev/settings?tab=subscription)** for a higher per-seat allowance.
* **Add seats** in [Settings → Subscription](https://www.cubic.dev/settings?tab=subscription). Capacity goes up immediately.
* **Tighten ignore patterns** in [`cubic.yaml`](/configure/cubic-yaml) for generated or vendored code you don't want reviewed.
## FAQ
Usage counts added and deleted lines actually reviewed, including full reruns. Ultrareviews
count at 3× the standard rate. For example, a review of 1,000 added and 200 deleted lines uses
1,200 reviewed lines, or 3,600 for an Ultrareview. A later incremental review of 100 new changed
lines uses 100 more at the standard rate.
Check **Settings → Usage** for a breakdown by review type and repository. Exclude generated
files or fixtures with [ignore patterns](/configure/cubic-yaml) to keep them out of reviews.
No. Only changed lines actually reviewed count, not the surrounding code cubic reads for context.
Caching and learning your codebase do not reduce the reviewed-line count. Incremental reviews
reduce usage by reviewing only new changes instead of repeating the full PR review.
No. The reviewed-line allowance covers GitHub PR reviews only. Codebase scans, wikis, CLI reviews,
and coding agents have separate limits.
Full reruns can count the same lines again. Commenting `@cubic-dev-ai review this PR` runs a fresh
full review, while `@cubic-dev-ai incremental review` reviews and counts only the changes since
cubic's last completed review. Pushing new commits also triggers incremental reviews when they are
enabled.
No. Reviewed-line usage is based on the changed lines of code cubic reviews, not how many comments cubic leaves. Changing sensitivity can make cubic more or less selective about the issues it reports, but it does not change how much code cubic reviews.
To reduce reviewed-line usage, change when reviews run or which files cubic reviews. You can do that with [AI review settings](/ai-review/ai-review-settings) or [`cubic.yaml`](/configure/cubic-yaml).
Yes. Add a PR label ignore pattern in [AI review settings](/ai-review/ai-review-settings), or add
the label to `reviews.ignore.pr_labels` in [`cubic.yaml`](/configure/cubic-yaml). For example,
labels such as `wip` or `skip-review` suppress automatic reviews, including push-triggered
incremental reviews, until the label is removed. If you want a review before then, comment
`@cubic-dev-ai review` on the PR.
No. Only completed reviews count toward your billing-period capacity. If you cancel a review,
merge a PR before its review finishes, or cubic hits an error, those reviews don't use any of your
quota.
Public repositories can use cubic for open-source work at no cost, subject to separate reviewed-line fair-use and abuse-protection limits. These safeguards are designed for unusually large or high-volume usage, not normal OSS maintenance.
On paid plans, reviews of public PRs from workspace members count toward the team's
reviewed-line allowance. Reviews from external contributors use a separate public allowance
and do not consume the team's reviewed lines. Unpaid public repositories use the public
fair-use pool instead of the private free-plan review count.
If your open-source project is blocked and you think the limit was applied incorrectly, email [contact@cubic.dev](mailto:contact@cubic.dev) with your organisation, repository, and PR link.
Your cap recalculates immediately. Adding seats gives you more capacity right away; removing seats
lowers it.
Flex capacity costs \$20 per 10,000 extra reviewed lines. cubic buys whole blocks only when a
review would otherwise be paused, and it never buys a partial block that would charge you without
unblocking the review. See [Flex capacity](/account/flex-capacity) for examples and spend-limit
behavior.
Yes. An Ultrareview is a longer, deeper review using cubic's most capable models, so it counts
against your reviewed-line capacity at 3× the standard rate. There is no separate Ultrareview
limit — usage shares the same reviewed-lines allowance as normal reviews.
Email [contact@cubic.dev](mailto:contact@cubic.dev) with your organisation name and we'll dig in.
# Flex capacity
Source: https://docs.cubic.dev/account/flex-capacity
How cubic bills extra reviewed-line capacity after your included usage runs out.
Flex capacity keeps GitHub PR AI reviews running after your workspace uses its included reviewed-line capacity. You set a monthly spend limit, and cubic buys extra reviewed-line capacity only when a review would otherwise be paused.
Flex capacity is available on paid workspaces billed through Stripe. Admins manage it in **Settings → Subscription** by choosing a top-up size and setting a monthly spend limit.
## How flex capacity works
Flex capacity turns a reviewed-line usage block into an automatic one-off charge:
1. Your workspace uses its included reviewed-line capacity for the billing period.
2. A new GitHub PR review would otherwise pause because the workspace is over its monthly limit.
3. cubic checks your flex capacity setting and monthly spend limit.
4. If the needed capacity fits under your spend limit, cubic charges the saved payment method immediately.
5. After payment succeeds, cubic adds the extra reviewed-line capacity for the current billing period and continues the review.
Flex capacity applies only to GitHub PR AI review usage. CLI/local reviews, codebase scans, daily scans, wikis, and cubic coding agents use separate limits.
## Pricing
Flex capacity costs **\$20 per 10,000 extra reviewed lines**.
| Item | Amount |
| -------------- | ------------------------------------------- |
| Billing unit | 10,000 extra reviewed lines |
| Price | \$20 per 10,000 lines |
| Default top-up | 10,000 extra reviewed lines for \$20 |
| Billing timing | Charged immediately when capacity is needed |
| Availability | Current billing period only |
The price is the same for Team and Pro workspaces, and the same for monthly and annual subscriptions. Flex capacity is separate from your seat subscription; it appears as a one-off invoice charge when cubic adds capacity.
## Example charges
You choose a preferred top-up size in multiples of 10,000 lines. cubic buys enough blocks to cover the current overage, and it never buys a partial block.
For a preferred top-up size of 20,000 lines:
| Current overage | Preferred top-ups | Charge | Extra capacity granted |
| --------------------- | ----------------- | ------ | ---------------------- |
| 4,000 reviewed lines | 1 | \$40 | 20,000 reviewed lines |
| 15,000 reviewed lines | 1 | \$40 | 20,000 reviewed lines |
| 25,000 reviewed lines | 2 | \$80 | 40,000 reviewed lines |
If a review is 25,000 lines over the included limit, cubic needs two blocks of 20,000 lines each.
If your remaining monthly flex limit is less than the price for a preferred top-up, then cubic will buy the smallest amount that fits under the limit. For example, if your remaining limit is \$30, but your preferred top-up is 20,000 lines for \$40, and the review needs 5,000 lines, cubic will buy a 10,000-line block for \$20. If a review needs 40,000 lines, cubic will buy nothing because the remaining \$30 cannot fund the required 40,000 lines.
## Spend limits
A monthly spend limit is the most cubic can spend on flex capacity during one billing period. The setting is a hard stop: reviews can continue while the needed flex purchase fits under the limit, and reviews pause once the next needed purchase would exceed the limit.
For example, a \$60 monthly spend limit can buy up to 30,000 extra reviewed lines during the current billing period. If your workspace has already spent \$40 and the next review needs 5,000 lines, cubic can buy a smaller 10,000-line top-up for the remaining \$20. If the review needs 15,000 lines, cubic buys nothing because the remaining \$20 cannot fund the required 20,000 lines.
Admins can set, raise, lower, or remove the spend limit from **Settings → Subscription → Flex capacity**. Removing the spend limit turns flex capacity off for future purchases. Extra capacity already bought during the billing period remains available until the period ends.
## Payment behavior
Flex capacity is granted only after payment succeeds. If the payment method is declined, cubic does not grant the extra capacity and reviews stay paused at the current limit.
Some cards require extra authentication, such as 3D Secure. When that happens, cubic emails workspace admins a link to the installation's Subscription settings. The settings page provides the secure Stripe invoice link, and cubic grants the extra capacity after Stripe confirms the payment.
A failed flex capacity payment prevents cubic from creating another flex invoice for the same capacity. cubic retries the existing open invoice when another review needs capacity, and workspace admins can pay it from the installation's Subscription settings.
## How to turn it on
Admins can enable flex capacity from the subscription settings:
1. Open **Settings → Subscription**.
2. Find **Flex capacity**.
3. Select **Set a spend limit**.
4. Choose how many lines cubic should add per top-up.
5. Enter a maximum monthly spend.
6. Save the settings.
The setting takes effect for future reviews. If reviews are already paused because your workspace is over the reviewed-line limit, setting a limit can let cubic buy the needed extra capacity and resume reviews.
## How to monitor usage
Open **Settings → Usage** to see your reviewed-line usage, reset date, and flex capacity spend for the current billing period. The subscription page also shows flex spend, the monthly limit, and how many extra reviewed lines were bought this period.
Flex capacity resets with your billing period. Unused extra capacity does not roll over.
## FAQ
No. Seats still determine your included reviewed-line allowance and who has paid AI review access. Flex capacity covers temporary overages after your included reviewed-line capacity runs out.
No. cubic charges flex capacity only when a review needs extra capacity and the purchase fits under your monthly spend limit.
No. The spend limit is a hard cap. If the next required purchase would exceed the limit, cubic buys nothing and reviews stay paused until you raise the limit or the billing period resets.
cubic buys your preferred top-up size in 10,000-line units. It can combine multiple preferred top-ups when the current overage needs more capacity.
cubic stops making future flex capacity purchases. Extra capacity already paid for during the current billing period remains available until the period resets.
Your included reviewed-line allowance resets, flex spend returns to \$0 for the new period, and any unused extra flex capacity from the previous period expires.
Flex capacity applies to your paid workspace's GitHub PR AI review usage. Public repositories may also be subject to separate fair-use and abuse-protection limits, which flex capacity does not override.
# Privacy & security
Source: https://docs.cubic.dev/account/privacy-security
How cubic keeps your code and data safe
cubic is built by developers, for developers. We understand that your source code is your most valuable asset, so we designed our systems with security and privacy as a first-principle—not an afterthought.
## Our guiding principles
* **Encryption everywhere** – All data is encrypted **in transit** (TLS 1.2+) and **at rest** (AES-256), including database records and object storage.
* **Least-privilege access** – The cubic GitHub App requests the minimum scope required to perform reviews. No additional write-or-admin permissions are granted unless they are strictly necessary (see below).
* **Transparent operations** – We publish this page so that every customer—current or prospective—can understand exactly how we treat their data. If you have questions, email us any time at [contact@cubic.dev](mailto:contact@cubic.dev). Our data handling practices are further detailed in our [Privacy Policy](https://cubic.dev/privacy) and use of the service is governed by our [Terms of Service](https://cubic.dev/terms).
* **No third-party model training on Customer Code** – Our AI model providers (e.g., OpenAI, Anthropic) contractually commit that code snippets and metadata passed through their APIs are **not** used to train or improve their underlying models.
## SOC 2 compliant
cubic is **SOC 2 Type 1** compliant, demonstrating our commitment to security and trust for our customers. We maintain comprehensive controls for change management, access management, and vulnerability management.
## Permissions requested by the cubic GitHub App
Granting the following scopes allows cubic to read pull-requests, leave review comments, and update PR status checks.
| Scope | Access | Why we need it |
| ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Administration** | Read-only | Access repository settings and organization information |
| **Actions** | Read & write | Manage GitHub Actions workflows when [Background Agents](/ai-review/coding-agents) push fix commits or create fix PRs (read-only for basic reviews) |
| **Checks** | Read & write | Surface pass/fail status checks for AI review completion |
| **Code** | Read & write | Read: Fetch PR diffs and context for reviews. Write: Enable [Background Agents](/ai-review/coding-agents) to push fix commits to your PR branch or create fix PRs (never pushes directly to main or protected branches—all fixes go through PR review) |
| **Commit statuses** | Read-only | Monitor and display commit status in the cubic UI |
| **Deployments** | Read-only | Access deployment information for integration purposes |
| **Issues** | Read & write | Create issues for tracking review findings when configured (optional feature) |
| **Metadata** | Read-only | Display repository information inside the cubic UI |
| **Pull requests** | Read & write | Post AI-generated review comments, resolve threads when feedback is addressed, and create fix PRs or update PR branches via [Background Agents](/ai-review/coding-agents) |
| **Workflows** | Read & write | Run CI/CD checks on fix PRs or fix commits created by [Background Agents](/ai-review/coding-agents) (read-only for basic reviews) |
> **Note:** You can install the cubic App on a single repository or an entire organization. Access is scoped to the repositories you select during installation, and can be modified at any time from GitHub's "Installed Apps" settings page.
>
> **Write permissions are primarily needed for the Background Agents feature**, which can push commits to your PR branch or create separate fix PRs—never direct commits to your main branch. The Background Agents feature uses Claude Code in an isolated sandbox to generate fixes, ensuring all changes go through your standard PR review process.
**For extra peace of mind:** While cubic never pushes directly to your main branch, you can
enhance security by enabling branch protection rules. Configure [branch protection
rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
on your main/default branch to prevent direct commits and require pull request reviews before
merging. This ensures all changes—including those from cubic's Background Agents—must go through
your standard review process.
## How AI code review works
1. **Event trigger** – Whenever a pull request is opened or updated, GitHub sends cubic a webhook describing the event.
2. **Isolated sandbox** – A new isolated container is launched.
3. **Analysis** – The pull-request diff and *only* the necessary context needed for reviewing the PR are processed by AI models.
4. **Comment publication** – The generated review comments are posted back to the PR via the GitHub API.
## AI subprocessors
cubic uses best-in-class large-language models hosted by vetted providers. Our agreements with these subprocessors explicitly prohibit using Customer Code to train their own models. Only the minimal code snippets required for the requested analysis are transmitted, and all requests are sent over encrypted channels.
If your organization prefers to *completely* block AI features, please contact us and we can disable them for your workspace.
## Reporting a security issue
If you believe you have found a vulnerability in cubic, please email our security team at [contact@cubic.dev](mailto:contact@cubic.dev) with the subject line "Security Vulnerability". We investigate all reports promptly and appreciate the efforts of the security community.
# Referral program
Source: https://docs.cubic.dev/account/referral-program
Earn up to $2,000 for every team you refer to cubic.
Invite teams to cubic and earn rewards that scale with their team size—up to \$2,000 per referral. Your referred teams get an exclusive extended 14-day trial period to fully explore cubic.
## How it works
Referring teams to cubic is simple and rewarding:
1. **Share your unique link** - Every cubic user gets a personalized referral link
2. **Teams sign up** - New teams use your link to create their cubic account
3. **Earn rewards** - Get rewards when referred teams upgrade to paid plans
There's no limit to how many teams you can refer, and rewards are automatically processed when teams convert to paid subscriptions.
## Getting your referral link
Access your unique referral link in seconds:
1. Go to [cubic.dev/refer](https://www.cubic.dev/refer) while signed in to your cubic account
2. Click **Refer and earn** in the top right
3. Copy your personalized link and share it via email, Slack, or social media
## Reward structure
Earn rewards based on the team size at conversion:
| Team Size | Your Reward |
| ----------- | ------------ |
| 1 seat | \$30 |
| 2 seats | \$60 |
| 3 seats | \$90 |
| 4 seats | \$120 |
| 5 seats | \$150 |
| 6-9 seats | \$30 × seats |
| 10-15 seats | \$300 |
| 16-19 seats | \$500 |
| 20-30 seats | \$750 |
| 31-50 seats | \$1,000 |
| 51-75 seats | \$1,500 |
| 76+ seats | \$2,000 |
**Example:** If you refer a team that subscribes with 8 seats, you'll receive \$240.
Rewards are calculated based on the subscription size when the team first upgrades to a paid plan.
## Benefits for referred teams
Teams you refer receive an exclusive extended trial period:
### Extended 14-day trial
While standard trials last 7 days, teams that sign up through referral links enjoy a full 14-day trial period, giving them an extra week to experience cubic's full capabilities.
### Full platform access
During their extended trial, referred teams get AI code reviews and complete access to all cubic features, giving them ample time to evaluate cubic for their team.
## Frequently asked questions
### Who can participate?
Every cubic user with an active account can refer new teams.
### Can I refer my own team or organization?
For fairness, you cannot earn rewards for referring teams within your own GitHub organization.
### When do I receive my reward?
Rewards are processed after a referred team makes their first payment for a cubic subscription.
### Is there a limit on referrals?
No! You can refer as many teams as you'd like. Each successful referral that converts to a paid plan earns you a reward based on their team size.
### What if a referred team changes their subscription size?
Your reward is calculated based on the team's subscription size at the time of their first payment. Later changes don't affect your reward amount.
### Can referred teams use other promotions?
The extended 14-day trial is automatically applied to all referred signups and cannot be combined with other trial extensions or promotional offers.
### What happens if a referred team cancels?
Once you've received your reward for a successful referral, it's yours to keep—even if the team later cancels their subscription.
## Start referring today
Ready to earn rewards while helping other teams discover cubic?
Questions about the referral program? Contact us at [contact@cubic.dev](mailto:contact@cubic.dev).
# Roles and permissions
Source: https://docs.cubic.dev/account/roles-and-permissions
Manage team roles and permissions in cubic
cubic uses a role-based access control system to manage who can make changes to your team's subscription and settings. Every team member has one of three roles:
| Role | Best for | What they can do |
| ---------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin** | Workspace owners, engineering managers, and operations owners | Manage seats, roles, billing, subscription settings, integrations, repository settings, and AI review settings. |
| **Member** | Engineers and teammates who need to configure cubic day to day | Use cubic's full product surface and edit non-billing settings, including AI review behavior, repository settings, integrations, and scan settings. |
| **Viewer** | Stakeholders who need visibility without configuration access | View team information, settings, review surfaces, analytics, and subscription status without changing configuration. |
## Permissions matrix
| Permission | Admin | Member | Viewer |
| ---------------------------------------------------------------------- | ----- | ------ | ------ |
| Use PR review, analytics, and other non-settings surfaces | ✅ Yes | ✅ Yes | ✅ Yes |
| View team members, role assignments, subscription status, and settings | ✅ Yes | ✅ Yes | ✅ Yes |
| Configure AI review behavior and repository settings | ✅ Yes | ✅ Yes | ❌ No |
| Manage integrations and linked repositories | ✅ Yes | ✅ Yes | ❌ No |
| Configure codebase scan settings and scan automation | ✅ Yes | ✅ Yes | ❌ No |
| Manage seat assignments | ✅ Yes | ❌ No | ❌ No |
| Change user roles | ✅ Yes | ❌ No | ❌ No |
| Configure auto-assign and usage seat automation | ✅ Yes | ❌ No | ❌ No |
| Manage billing, plans, and subscription controls | ✅ Yes | ❌ No | ❌ No |
| Promote bot accounts to admin | ❌ No | ❌ No | ❌ No |
## Seats and roles
Seats and roles are related, but they control different things.
* **Seats** control which GitHub users are assigned cubic access and how usage is counted for billing.
* **Roles** control what a seated user can change inside cubic.
Bot rows can be enabled so bot-authored PRs receive AI reviews without adding a paid developer seat. Those reviews still use the team's normal reviewed-line allowance.
Members and viewers can both use cubic surfaces available to their seat. The difference is configuration access: members can change non-billing workspace and repository settings, while viewers can only read them.
Repository and PR visibility can still depend on GitHub repository access. If someone cannot see a specific repository or PR, confirm that they have access to the repository in GitHub and that cubic has access to that repository.
## How to become an admin
There are three ways to become a cubic admin:
1. **Install the cubic GitHub app.** When you install cubic for your GitHub organization, you automatically become an admin.
2. **Be a GitHub organization admin.** GitHub organization admins automatically become cubic admins when the app is installed.
3. **Get promoted by an existing admin.** Any current admin can promote you through [subscription settings](https://www.cubic.dev/settings?tab=subscription).
At least one admin is required for every team. Admins cannot remove their own admin role, and cubic prevents changes that would leave the team without an active human admin. Bot accounts cannot be admins.
The default role for new seats is **Member** unless the user qualifies for admin during setup.
## Admin role
Admins have full control over team management and can:
* **Manage seat assignments:** Add or remove cubic seats for team members
* **Manage roles:** Change members between admin, member, and viewer roles (note: bot accounts cannot be admins)
* **Configure workspace settings:** Change AI review settings, repository settings, integrations, scan settings, and billing automation
* **Configure auto-assign:** Enable automatic seat assignment and removal when GitHub organization members join or leave
* **Manage billing:** Update plans, seats, and subscription controls
* **Bulk actions:** Select multiple users to manage seats and roles in bulk
## Member role
Members can use cubic's full feature set and edit non-billing settings:
* **Full platform access:** Use all cubic features including AI reviews, analytics, and PR management
* **Manage workspace settings:** Configure AI review behavior, repository settings, integrations, scan settings, and other non-billing team settings
* **View billing status:** See subscription status and billing-related information without changing billing details
* **No seat, role, or billing management:** Cannot assign/remove seats, change user roles, or manage billing and subscription controls
## Viewer role
Viewers can use cubic's review and analytics surfaces, but they cannot change cubic settings:
* **View team information:** See team members, role assignments, subscription status, and settings
* **Use review surfaces:** Access PR review, analytics, and other non-settings views available to their seat
* **No configuration changes:** Cannot change AI review settings, repository settings, integrations, seats, roles, or billing controls
## How to manage user roles
Only admins can change user roles. cubic provides both individual and bulk role management:
### Individual role changes
To promote or demote a single user:
1. Navigate to [Settings → Subscription](https://www.cubic.dev/settings?tab=subscription)
2. Find the team member in the list
3. Click the three-dot menu (⋮)
4. Select the new role: Admin, Member, or Viewer
5. The change takes effect immediately
Only admins can see and use seat and role management options. Members and viewers can view the
team list, but they cannot change seats or roles.
### Bulk role changes
To change roles for multiple users at once:
1. Navigate to [Settings → Subscription](https://www.cubic.dev/settings?tab=subscription)
2. Use the checkboxes to select multiple team members
3. Click "Update role" in the bulk action bar
4. Choose the role to apply to the selected users
5. All selected users are updated immediately
## FAQ
Check your role in **Settings → Subscription** for the selected GitHub organization. Billing
requires the **Admin** role in cubic. GitHub organization admins receive that role during
installation, but later role changes are managed in cubic. Ask an existing cubic admin to
promote you. If you installed the app and have no admin access, contact
[support](/account/support) with your GitHub username and organization.
Not automatically. Your personal GitHub installation and an organization's installation are
separate. Check the selected organization and its subscription in **Settings → Subscription**.
Contact [support](/account/support) if you need help moving a subscription to the right
workspace.
## Troubleshooting
### I need someone to edit settings, but not billing
Give them the **Member** role. Members can edit non-billing settings, but they cannot manage seats, roles, or billing.
### A user can view settings but cannot save changes
Check their role. Viewers can read settings but cannot change AI review settings, repository settings, integrations, seats, roles, or billing controls.
### I cannot demote myself from admin
cubic prevents admins from removing their own admin role. Ask another admin to change your role after confirming that the team will still have at least one admin.
### I cannot remove or demote the last admin
Every team needs at least one active human admin. Add or promote another admin first, then change the original admin's role or seat.
### I cannot make a bot an admin
Bot accounts cannot be admins. Assign bot seats a non-admin role instead.
# Subscription
Source: https://docs.cubic.dev/account/subscription
Free and paid cubic plans.
Start with a 7-day free trial, with no credit card required.
Everyone on your team is enabled by default during the trial.
Choosing a paid plan at checkout starts billing immediately.
After the trial, continue on the free plan or upgrade to a paid plan.
## Free plan
The free plan includes 20 AI reviews per month, shared across repositories in your
GitHub organization. The quota resets on the 1st of each month. Review comments
show how many reviews remain.
## Paid subscriptions
For paid AI review access, cubic's subscription cost is determined by the number of developer seats you choose to activate. Each active seat corresponds to a unique GitHub user within your organization. AI review usage on paid plans is measured in reviewed lines, with an allowance per paid seat that is pooled across your team.
* **Seat-based billing:** You are billed based on the number of *active* seats you assign to your team members (GitHub users).
* **Flexible seat management:** You can manage seat assignments at any time, both during your free trial and after it ends.
* **Customizable checkout:** When you purchase a subscription, you select the exact number of seats you need.
* **Ultrareview:** Paid and trial plans include Ultrareview for high-risk or complex PRs. Ultrareviews count toward your team's reviewed-lines allowance at 3× the standard rate.
* **Subscription management:** Seat assignments and active seats can be viewed and managed through the subscription tab in your settings: [https://www.cubic.dev/settings?tab=subscription](https://www.cubic.dev/settings?tab=subscription)
### Seat scope across organizations
Seat assignments are scoped to the selected GitHub organization. If your company uses cubic in multiple GitHub organizations, assigning a seat in one organization does not automatically assign that user a seat in another organization.
The seat count shown in **Settings → Subscription** applies to the selected organization. For example, `86/155 seats assigned` means that organization has 86 active developer seats out of 155 available seats. Other linked organizations do not consume that organization's available seats.
### Usage and flex capacity
See [AI review usage and limits](/account/ai-review-usage) for what counts toward your
allowance. Other features, such as local reviews and coding agents, have separate limits.
Enable [flex capacity](/account/flex-capacity) on a paid plan to buy extra
reviewed lines when the included allowance runs out. An admin sets the monthly
spend limit in **Settings → Subscription**.
### Assigning seats
To manage seats as an admin, go to **Settings → Subscription**:
* Toggle the switch next to a developer to assign or unassign a seat.
* To update several developers, select their checkboxes and use **Update seat status**.
Members and viewers cannot change seats. See [Roles and permissions](/account/roles-and-permissions)
for the full permission list.
To set a work email for the selected organization, open **Settings → Subscription & team**
and click the pencil beside your email under **Team members**. Enter the address and press
**Enter** to save. Weekly summaries, trial emails, and codebase scan completion emails use
this address; your GitHub email stays the same.
### Automatic seat management
Enable automatic seat management in your subscription settings to assign seats to
new organization members and remove seats when members leave. These changes affect billing.
Existing manual assignments remain. For example, if 3 of 10 developers have seats,
enabling automatic assignment gives a seat to the next developer who joins,
bringing the assigned total to 4. It does not assign the other existing members.
## Bot seat management
cubic creates a separate bot row when a recognized bot, such as
`devin-ai-integration[bot]`, first opens a PR. Bot reviews are disabled by default;
an admin can enable them in subscription settings.
Enabled bots do not require paid developer seats. Their reviews consume the team's
shared reviewed-line allowance.
## Frequently asked questions
Pro requires a seat for each active developer in the installation, including developers whose
seat toggle is off. Active means opening at least 15 PRs in the last 30 days. Bots are excluded.
This minimum applies because Pro's codebase scans cover the whole repository. Team does not have
this activity-based minimum.
No. Everyone is enabled during the trial so your team can try cubic. Before upgrading, go to
**Settings → Subscription** and unassign users who do not need seats, individually or through
**Update seat status**. Choose your paid seat count at checkout. Pro still requires enough seats
to cover its active-developer minimum.
Check that you're viewing the GitHub organization linked to your cubic integration in Vercel. A
subscription linked to your personal GitHub installation does not automatically cover a separate
organization. If the wrong installation is linked, contact [support](/account/support) with the
organization name and your Vercel subscription details so we can help correct the connection.
Yes. We offer an annual subscription at a 20% discount off the monthly rate. Select "12 months"
on the checkout page, and the discount will apply automatically.
You can enter your coupon or promo code on the subscription checkout screen:
![Screenshot showing the promo code field on the checkout page]()
You can cancel your subscription at any time from **Settings → Subscription → Manage plan**.
You'll keep full access until the end of your current billing period; after that you won't be
billed again.
To change your seat count after your subscription has started, go to [**Settings →
Subscription**](https://www.cubic.dev/settings?tab=subscription) and click on **Manage plan**.
This will direct you to our billing portal (Stripe) where you can adjust the number of seats.
Prorated charges or credits will be applied based on your changes.
We currently accept all major credit cards (Visa, MasterCard, American Express) and PayPal. For
enterprise customers, we also support ACH bank transfers. Contact support to set them up.
Nonprofits and schools can receive a 50% discount. Please [contact
support](mailto:contact@cubic.dev?subject=Nonprofit%20Discount) to verify your eligibility.
Yes. Public repositories on the free plan use a separate public fair-use allowance. On paid
plans, reviews of public PRs from workspace members count toward the team's reviewed-line
allowance; reviews from external contributors do not. See [public-repository
usage](/account/ai-review-usage#faq) for details.
Cancelling a subscription, disconnecting GitHub, and deleting your account are separate actions.
See the [Support FAQ](/account/support#faq) for each one.
For billing questions, [contact support](/account/support).
# Support
Source: https://docs.cubic.dev/account/support
Contact cubic support for help, questions, and feedback.
Email [contact@cubic.dev](mailto:contact@cubic.dev) for help or to share feedback.
## FAQ
Go to **Settings → Subscription → Manage plan** to cancel. For subscriptions purchased through
Vercel, manage billing in Vercel. Cancelling a subscription does not delete your cubic account.
In GitHub, open the settings for the account or organization where you installed cubic. Under
**Installed GitHub Apps**, select cubic and configure its repository access, or uninstall it to
disconnect the installation. Manage your paid subscription separately.
Email [contact@cubic.dev](mailto:contact@cubic.dev) from your account email address with your
GitHub username and organization name. Tell us whether you want to delete your personal account
or the organization's cubic workspace so we can confirm the scope of the request.
# Verify your GitHub email
Source: https://docs.cubic.dev/account/verify-github-email
Steps to verify your primary GitHub email address so you can sign in to cubic.
If you see an **“unverified\_email”** error when signing in with GitHub, it means your primary GitHub address hasn’t been verified yet.
To verify your email:
1. Open [GitHub](https://github.com) and go to **Settings › Emails**.
2. Click **Resend verification** next to your primary address.
3. Follow the link in the email from GitHub to complete verification.
4. Return to cubic and sign in again.
Having trouble? Reach out at [contact@cubic.dev](mailto:contact@cubic.dev).
# AI review settings
Source: https://docs.cubic.dev/ai-review/ai-review-settings
Configure repository-level and organization-level AI review behavior in cubic.
Within your project's [settings](https://cubic.dev/settings), the **AI review** section offers controls to tailor AI review behavior.
![AI review settings]()
## Configurable options
AI review settings can be configured for individual repositories or globally for all repositories
in an installation. To update settings for all repositories at once, select "All repositories"
from the repository picker before making changes.
1. **Review instructions**
* Provide general guidelines for the AI in plaintext.
2. **Library & framework versions**
* Specify or override detected versions (e.g., React 18, Django 4) to improve suggestion accuracy.
* Note that, by default, cubic will try to automatically detect the common libraries and versions they use to ensure that it tailors its reviews to those specific ones.
3. **Ignore patterns**
Define comprehensive patterns to control which pull requests and files are reviewed:
* **File path patterns**: Skip files or directories matching glob patterns (e.g., `dist/`, `*.test.ts`)
* **Head branch patterns**: Suppress automatic reviews for PRs from matching branches (e.g., `feature/*`, `hotfix/*`)
* **Base branch patterns**: Suppress automatic reviews for PRs targeting matching branches (e.g., `staging`, `develop`)
* **PR label patterns**: Suppress automatic reviews for PRs with matching labels (e.g., `wip`, `skip-review`)
* **PR title patterns**: Suppress automatic reviews for PRs with matching titles (e.g., `Draft:*`, `WIP:*`)
* **Maximum changed lines**: Store the automatic-review threshold for a PR's reviewable added plus deleted lines. The default is 50,000 lines, and leaving the setting absent or blank uses that default. cubic preserves positive integers up to 2,147,483,647, but applies an effective ceiling of 50,000 reviewable lines to every review. Manual `@cubic-dev-ai review` requests can bypass a lower repository threshold, but not the effective ceiling.
Pull request label, title, and branch patterns suppress automatic reviews. You can still request a review on a matching PR with `@cubic-dev-ai review`. File path patterns continue to apply to manually requested reviews, so matching files remain excluded.
4. **Exclude generated files**
For large repositories, you can tell cubic to ignore files that don't require review. This is handy for:
* Data files that don’t need to be reviewed
* Auto‑generated code produced by build or code‑gen tools
* Any other files that would make a pull request too large for cubic to process
You can do this by marking files as generated in your repository’s `.gitattributes` file:
```gitattributes theme={null}
# Exclude specific files
docs/data.txt linguist-generated=true
# Exclude file types
*.csv linguist-generated=true
*.pb.go linguist-generated=true
# Exclude entire directories
data/* linguist-generated=true
generated/* linguist-generated=true
```
Files marked as `linguist-generated` will be:
* Automatically collapsed in GitHub pull request views
* Skipped entirely during **cubic**'s code review
5.
Automatic PR approval
* When enabled, cubic can evaluate clean pull requests for automatic approval
* Disabled by default to prevent bypassing branch protection rules
* Only available when general AI review is enabled
* Useful when you want to start in a safe dry-run mode, confirm your approval policy matches team expectations, and only later allow cubic to submit real approvals
Behavior controls:
* **Disabled**: cubic only comments on PRs and skips auto-approval evaluation
* **Shadow**: cubic evaluates whether the PR would be approved, but still posts a normal review comment instead of a real GitHub approval
* **Live**: cubic evaluates the PR and submits a real GitHub approval when the selected policy allows it
Approval policy controls:
* **Low-risk only**: Approves only when no open issues block approval and cubic determines the PR is low-risk
* **Always**: Approves any clean PR, regardless of risk level
* **Custom**: Define your own criteria via a custom prompt. For example, only approve documentation changes while requiring human review for source code modifications
* **Allow open issues**: Approve even while cubic issues at the chosen priorities stay open. Choosing a priority also includes every lower one; none are selected by default. See [Allow open issues](/ai-review/auto-approval#allow-open-issues).
* **Never auto-approve**: Add file or directory globs that block auto-approval. If any changed file in a PR matches, cubic will not auto-approve that PR.
* **Only auto-approve files**: Add file or directory globs that define an allowlist. Every changed path must match at least one glob. Renamed files must match on both their current and previous paths.
* **Do not auto-approve external contributors**: For public repositories, cubic still reviews PRs from external contributors, but leaves a comment review instead of approving.
Shadow mode is useful when you want to test your approval policy safely before letting cubic approve pull requests automatically. See [Auto-approval](/ai-review/auto-approval) for setup steps, YAML configuration, safeguards, and troubleshooting.
![Auto-approve PR settings showing behavior and approval policy controls]()
6. **Review incremental commits**
* When enabled, cubic reviews new commits pushed to open pull requests
* Only new issues are posted as comments; previously flagged issues are not repeated
* This setting also covers force-pushes, including jj workflows. cubic reviews only new changes relative to a previously reviewed version when it can safely reconstruct the difference.
* Rewrites with no new code changes skip AI review. Text additions and modifications are supported. Unsupported changes (such as renames or binary changes) cause a skip, as does an unavailable reviewed baseline. Neither case falls back to a full review.
7. **Auto-resolve threads when addressed**
* When enabled, cubic automatically resolves GitHub review threads after detecting the issue has been addressed in a subsequent commit
* Enabled by default for new installations
8. **Merge confidence summary**
* Adds a 1-5 confidence score to cubic's reviews, helping you assess the risk of merging a pull request
* The score considers factors like test coverage, code complexity, and potential regressions
* During incremental reviews, cubic updates the score when issues are addressed and removes it when all issues are addressed
* Disabled by default
9. **Ultrareview** (own tab)
* The **Ultrareview** card controls whether [ultrareviews](/ai-review/ultrareview) — deep \~30-minute reviews billed at 3× the reviewed-lines rate — can run at all: **Disabled**, **Manual** (default; PR-comment and dashboard triggers only), or **Automatic**
* With the mode set to **Automatic**, choose a risk policy (**Off**, **High-risk PRs**, or a **Custom prompt**) and add file rules that always trigger an ultrareview independently of the policy; manual triggers stay available; see the [ultrareview docs](/ai-review/ultrareview) for details
10. **Review draft pull requests**
* When enabled, cubic reviews draft PRs immediately when opened
* Get early feedback while still working on your changes
* Disabled by default
11. **Cross-repo reviews**
* Check related repositories for changes that need coordinated updates
* Configured per repository from the **Cross-repo reviews** card
* Available on every plan
* See [Cross-repo reviews](/ai-review/cross-repo-reviews) for setup and behavior
12. **Sign commits**
* When enabled, cubic signs the commits it pushes when applying fixes, so GitHub marks them as verified
* Useful for repositories that require signed commits via branch protection
* Applies only to the **cubic** coding agent; the Cursor cloud agent always signs its commits
* Requires "Fix with cubic" to be enabled first
* Disabled by default
## PR description settings
Control how AI generates PR descriptions for your repository through the dedicated **Descriptions** tab.
### Available options
1. **PR description generation toggle**
* Enable or disable automatic PR description generation for new pull requests
* When enabled, cubic generates descriptions when PRs are opened
2. **Custom instructions**
* Provide specific guidelines for how PR descriptions should be formatted
* Instructions are applied to all AI-generated descriptions in the repository
* Leave empty to use cubic's default description format
3. **Review in cubic link**
* Include a link to review the PR in cubic's AI-native diff viewer
* Enabled by default
4. **Skip when authors write descriptions**
* When enabled, cubic skips generating a description on new PRs whose author already wrote a substantive one
* Empty or template-only descriptions (unfilled headings, checklists, bare issue links) still get an AI description
* Disabled by default
Access these settings from the **Descriptions** tab in your [AI review settings](https://cubic.dev/ai-review?tab=descriptions).
## FAQ
Yes. Turn off AI reviews for the repository in **AI review settings**, or set `reviews.enabled:
false` in [cubic.yaml](/configure/cubic-yaml). Then comment `@cubic-dev-ai review this PR` when
you want a review. To stop only push-triggered reviews, turn off **Review incremental commits**
instead.
Yes. Branch, title, and label ignore patterns stop automatic reviews, including incremental
reviews after pushes. Comment `@cubic-dev-ai review this PR` to request a review manually. File
ignore patterns still apply, so excluded files stay out of the review.
## Next steps
* [Interactive comments](/ai-review/interactive-comments): Refine the AI's suggestions directly within PR comments.
* [Custom agents](/ai-review/custom-agents): Create domain-specific checks to expand beyond general analysis.
* [Auto-approval](/ai-review/auto-approval): Let cubic approve clean pull requests when your policy allows it.
# Auto-approval
Source: https://docs.cubic.dev/ai-review/auto-approval
Skip human review for clean, low-risk pull requests when your policy allows it.
Auto-approval lets you skip human review for pull requests that cubic determines are low risk and issue-free. When a PR matches your repository policy, cubic can submit the GitHub approval so the change can keep moving.
Not every PR needs a human reviewer. Documentation updates, test-only changes, small config edits, and other low-risk PRs can move faster when cubic has already reviewed them and found no issues. Human reviewers can spend their time on changes that need judgment: product logic, infrastructure, security, data models, and other high-impact code.
You stay in control by choosing the policy per repository. Auto-approval is disabled by default, and you can test it in shadow mode before cubic submits real GitHub approvals.
![Auto-approve PR settings showing Shadow behavior, Custom approval policy, a custom prompt, and never-auto-approve rules]()
## How it works
cubic treats auto-approval as part of the review outcome. If the review is clean and your settings allow approval, cubic can approve the PR. If the PR does not match your policy, cubic does not approve it.
Shadow mode is the safe way to start. It keeps cubic in comment-only mode, but adds a summary showing whether cubic would have approved the PR.
## Recommended workflow
Start with repositories where the risk is low, such as documentation, internal tools, test fixtures, or repos with narrow change types. Auto-approval settings are configured per repository, so you do not need to roll it out everywhere at once.
1. Open [AI review settings](https://www.cubic.dev/ai-review?tab=auto-approve) and select one repository.
2. Set **Behavior** to **Shadow**.
3. Choose **Low-risk only** or write a **Custom** policy for that repository.
4. Watch a few real PRs to see which ones cubic would approve.
5. Add never-auto-approve rules for sensitive paths, such as migrations or infrastructure, and for PR attributes such as authors or labels.
6. Switch **Behavior** to **Live** when the shadow results match your team's expectations.
Use different policies for different repositories. A docs repo might use live auto-approval much
sooner than a payments, auth, or infrastructure repo.
## Behavior and policy
Behavior controls whether cubic submits real approvals:
* **Disabled:** cubic only comments.
* **Shadow:** cubic comments and shows what it would have approved.
* **Live:** cubic submits a real GitHub approval when the policy allows it.
Approval policy controls which clean PRs are eligible:
* **Low-risk only:** recommended default for most repositories.
* **Custom:** your own approval criteria, such as "only approve tests and docs."
* **Always:** approves any clean review. Use this only for repositories where that is acceptable.
### Custom policy
The custom policy allows you to provide your own prompt for the auto-approval agent. When you select this option, cubic will first give you the prompt it uses for the low-risk policy. You can then edit the prompt to adapt it to your needs.
The custom policy only runs when no open cubic issues block approval. By default every open issue blocks; [Allow open issues](#allow-open-issues) lets issues at the priorities you choose stay open. If cubic finds issues in the first commit of the PR, but those issues are resolved in the next commit, the custom policy will run.
The custom approval agent receives the following context:
| Context | What cubic provides |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PR details | The title, author, description, total number of changed files, and total number of changed lines. |
| Current changes | Available diff patches with each file's name, status, additions, and deletions. Large descriptions and diffs may be truncated to fit the evaluation context. |
| Earlier decisions | On later reviews, the previous approval decision and the changes since that decision, when available. The agent still makes a fresh decision from the current PR diff. |
| Open issues | Open cubic issues that [Allow open issues](#allow-open-issues) lets through, with each issue's priority, location, and summary. |
## Allow open issues
By default, any open cubic issue blocks auto-approval. **Allow open issues** lets a repository approve PRs while issues at the priorities you choose stay open. Pick the priorities in the dropdown; picking one also picks every lower priority, so choosing **P2** allows P2 and P3. Nothing is selected by default.
| Open issues on the PR | Setting | Result |
| ------------------------------------------------------ | -------------- | ----------------------------------------- |
| This review finds a P3 | None | Comment only |
| This review finds a P3 | P3 | Findings review, then a separate approval |
| This review finds a P2 and a P3 | P3 | Comment only |
| This review finds a P0 | All | Findings review, then a separate approval |
| No new issues; a P3 from an earlier push is still open | P3 | Approval |
| An issue has no recorded priority | Any except All | Comment only |
* Priority is the P0–P3 label on each cubic comment.
* Only findings cubic posts count. Findings dropped by the inline comment limit never block approval.
* When new issues are allowed, cubic posts its findings as a normal review, then submits the approval as a separate review.
* Every other rule still applies: behavior, approval policy, never-auto-approve and only-auto-approve rules, and external contributors. With **Low-risk only** or **Custom**, the approval agent sees the open issues and still makes its own decision.
In `cubic.yaml`, set `reviews.auto_approve_rules.allow_open_issues` to `none`, `p3`, `p2_and_p3`, `p1_to_p3`, or `all`.
## Safety controls
Auto-approval is conservative by design:
* cubic only approves when no open review issues block it. By default, every open issue blocks approval.
* Shadow mode never submits a real approval.
* Never-auto-approve rules block approval when a PR changes sensitive files or matches a PR attribute rule.
* Changed-file allowlists restrict approval to explicitly approved paths.
* Public-repository PRs from external contributors can be reviewed without being auto-approved.
* GitHub branch protection still applies, including required checks, required reviewers, and code owner rules.
Use never-auto-approve rules for files that should always get human review, such as migrations, infrastructure, auth, billing, or production configuration. If any changed file in the PR matches one of those patterns, cubic does not approve the PR.
Use only-auto-approve file rules to start with a narrow set of trusted paths. Every changed path must match at least one configured glob. A PR that changes both `docs/**` and `cdk/**` does not qualify when the allowlist contains only `docs/**`. Renamed files must match on both their current and previous paths, and never-auto-approve rules always take precedence.
## Approval filters
Auto-approval can also filter on PR attributes: the author, the head or base branch, PR labels, and the PR title.
* **Never auto-approve when…** rules block approval when any rule matches. For example, exclude PRs labeled `do-not-auto-approve` or titled `WIP:*`.
* **Only auto-approve when…** rules are allowlists. Once an attribute has rules, PRs must match one of them. For example, only auto-approve PRs from `renovate[bot]` or `dependabot[bot]` that target `main`.
Authors, branches, and titles support glob patterns; labels match exactly, ignoring case. If cubic cannot verify a PR's metadata, it does not approve the PR.
Configure these settings in [AI review settings](https://www.cubic.dev/ai-review?tab=auto-approve), or version-control them with [`cubic.yaml`](/configure/cubic-yaml).
## Next steps
* [AI review settings](https://www.cubic.dev/ai-review?tab=auto-approve): Configure auto-approval in the dashboard.
* [Configure with cubic.yaml](/configure/cubic-yaml): Version-control auto-approval settings.
# Coding agents
Source: https://docs.cubic.dev/ai-review/coding-agents
Use Coding agents to asynchronously fix issues flagged in code review.
cubic can automatically fix issues identified during code review.
Request a targeted fix with one click.
![Fix with cubic button]()
## How it works
When cubic identifies an issue in your code, you can request an AI-generated fix that:
1. **Analyzes the issue** - Reviews the problem and relevant context
2. **Generates a solution** - Creates a targeted fix addressing the specific issue
3. **Applies the fix** - Pushes commits to your PR branch by default, or opens a fix PR when requested
4. **Preserves review flow** - Lets you review the changes before merging into your main PR
By default, cubic pushes commits directly to your PR branch. To override, include "open a fix PR"
in your request. If cubic opens a fix PR, it targets the branch of your original PR, not the main
branch.
## Triggering fixes
There are two ways to request an AI fix:
### Tagging cubic in Github or cubic
![Request AI fix demo]()
You can also request fixes for issues cubic didn’t flag. Tag cubic in any PR comment (including colleague comments) and ask for a fix:
* "@cubic fix this issue"
* "@cubic-dev-ai can you generate a fix for this?"
* "@cubic please fix the type error mentioned above"
cubic will acknowledge your request and begin generating the fix. If you want a separate PR instead
of direct commits, say "open a fix PR."
cubic only treats the current comment as permission to edit code when that comment explicitly tags
cubic. `@cubic`, `@cubic-dev-ai`, and other supported cubic tags work. Replying inside a
cubic-started thread without a fresh tag is treated as discussion, feedback, or questions, not
authorization to push changes.
### Using the fix button in cubic
For inline review comments, click the **Generate fix** button in the comment actions menu.
Dashboard-triggered fixes commit directly to the PR's branch by default.
This is available when:
* The comment identifies a specific issue in a file
* The comment includes file and line context
* Your installation has the fix feature enabled
## What to expect
### Fix generation process
1. **Acknowledgment** - cubic reacts with 👀 and comments
2. **Analysis** - The AI analyzes the issue and surrounding code
3. **Delivery** - cubic pushes commits to your PR branch by default, or opens a fix PR if requested. Claude Code runs in an
isolated container in the background. (typically 1-3 minutes)
4. **Notification** - cubic updates the original comment with the commit or PR details
### Reviewing changes
If cubic opens a fix PR, it includes:
* **Descriptive title** - AI-generated title explaining what's being fixed
* **Targeted changes** - Only the code needed to address the specific issue
* **Original context** - Reference to the original PR and issue comment
* **Clean diff** - Easy to review changes in isolation
If a fix PR is created, you can test the changes locally by checking out the fix branch before
merging.
If cubic pushes commits directly, review the new commits on your PR branch as usual.
## Best practices
### Tips for using AI fixes
* **Review carefully** - Always review AI-generated code before merging
* **Test locally** - Verify the fix works as expected in your environment
### Limitations
* Complex architectural changes may require manual intervention
* Fixes are scoped to the specific issue identified
* Some issues may require broader refactoring beyond a single fix
* Follow-up changes are not yet supported
* Generated PRs or pushed commits run through your existing GitHub CI checks
## Coding agent providers
You can choose which coding agent applies fixes. cubic supports two providers:
* **Default (cubic with Claude)** - cubic generates and applies fixes using Claude models. This works out of the box and needs no configuration.
* **Cursor cloud agents** - cubic hands off fixes to Cursor cloud agents running in your own Cursor account. This requires a one-time connection.
Set the provider per repository in **AI review → Fix with cubic → Coding agent provider**.
### Connect Cursor cloud agents
Before you can select Cursor cloud agents, connect them in **Settings → Integrations → Coding agent providers**.
In Cursor, create an API key or a service account key. See Cursor's [API
documentation](https://cursor.com/docs/api#creating-api-keys) for how to create keys.
Open **Settings → Integrations → Coding agent providers** and select **Cursor cloud agents**.
Choose the key type (**API key** or **Service account key**), paste the key (it starts with
`crsr_`), and save. cubic validates the key with Cursor and stores it encrypted.
In **AI review → Fix with cubic → Coding agent provider**, choose **Cursor cloud agents**. cubic
now routes fixes for that repository to Cursor cloud agents.
Disconnecting Cursor cloud agents removes the stored key and switches any repositories using it
back to the default provider (cubic with Claude models). You can reconnect at any time.
## Signed commits
Enable commit signing so GitHub marks commits pushed by cubic as **Verified**.
1. Open [AI review → Fix with cubic](https://www.cubic.dev/ai-review?tab=background-agents).
2. Turn on **Sign commits**.
This setting applies only to the default cubic coding agent. Cursor cloud agents always sign
their commits.
## Review the fix
Check the generated changes before merging. If cubic opened a separate fix PR, merge it into your original PR branch when you are satisfied with the changes.
# Cross-repo reviews
Source: https://docs.cubic.dev/ai-review/cross-repo-reviews
Review changes that affect related repositories.
Cross-repo reviews help cubic catch changes that need a matching update in another repository. Link
related repositories so reviews can check shared APIs, schemas, docs, or release work.
Both repositories must be installed in the same cubic GitHub installation. You need a Member or
Admin role to add, edit, or remove repository links. Viewers can see the configured links but cannot
change them. See [Roles and permissions](/account/roles-and-permissions) for details.
Cross-repo reviews are available on every plan.
## How it works
When cubic reviews a pull request in either linked repository, it:
1. **Checks whether the link applies** - Uses the changed files and your guidance to decide whether the linked repository matters for the PR.
2. **Reads the linked repository when needed** - If the link applies, cubic inspects the shared code or contract being changed.
3. **Posts cross-repo findings** - Adds comments to the reviewed PR with citations to affected files in the linked repository.
4. **Tracks companion fixes** - If the reviewed PR description references a PR in the linked repository, cubic updates the finding when the companion PR addresses it.
Cross-repo checks run as part of the normal review. You do not need to start a separate review.
## Setting up cross-repo reviews
![Cross-repo reviews card in AI review settings with several configured links]()
1. Open [AI review settings](https://cubic.dev/ai-review) and select the repository you want to configure.
2. Find the **Cross-repo reviews** card and select **Add link**.
3. Choose the related repository from the picker. Only repositories in the same installation appear.
4. Write one or two sentences describing what the repositories share and which changes need coordinated updates, then select **Link repository**.
Repository links work in both directions. Configure a pair once, and cubic can use the link when
reviewing either repository.
## Managing repository links
Open the **Cross-repo reviews** card for either linked repository. Select the pencil icon to update
the review guidance, or select the trash icon and confirm to remove the link. Because links work in
both directions, editing or removing a link affects reviews in both repositories.
## Limits and access
* Each repository can link to up to 5 other repositories. To link more, [contact us](mailto:contact@cubic.dev).
* Guidance is capped at 80 words. cubic reads it verbatim, so concise guidance works best.
* Both repositories must be in the same GitHub installation. Cross-installation links are not supported.
* Archived repositories, repositories cubic no longer has access to, and repositories that have moved installations show an inaccessible badge and are skipped during review.
## Writing good guidance
Guidance tells code review agents when another repository matters. Name the shared surface and the kinds of changes that need coordination.
### Good examples
> Frontend and backend share an HTTP API; route or response-shape changes need coordinated updates on both sides.
> Both services read from the same Postgres database. Schema migrations and column renames require matching updates in both repositories.
> The shared `@acme/types` package is consumed by both repositories. Breaking changes to exported types require updates wherever they're imported.
### What doesn't work
> They're related.
This is too vague to be useful. cubic may skip the linked repository or check it too often.
Name the shared surface (API, schema, types, events) and the coordination rule (what changes need
a matching update). Specific guidance makes relevance checks more accurate.
## Referencing companion PRs
Companion PR references are optional. They let cubic track fixes across repositories, but cubic can
find cross-repo issues without them.
When your change spans two repositories, add the companion PR to the reviewed PR description. cubic
recognizes two formats:
* Full URL: `https://github.com/myorg/backend/pull/456`
* Shorthand: `myorg/backend#456`
The referenced PR must be in a repository linked from **Cross-repo reviews**. Bare `#456` shorthand is intentionally not matched because same-repo references cannot be companions.
Editing the PR description re-runs discovery, so you can add or remove companion references at any time.
## What you'll see in reviews
![A cross-repo finding comment on a PR citing files in three related repositories]()
Cross-repo findings appear inline on the reviewed PR, the same way other AI review comments do. Each finding includes a citation pointing at the affected file in the linked repository, so you can jump to the code that needs a matching change.
When the companion PR pushes new commits that address the cited issue, cubic edits the original comment to show the addressed state and the commit SHA that fixed it. If a comment cites multiple cross-repo concerns and only some are addressed, the comment shows a partial resolution so you know what remains.
## Troubleshooting
cubic checks a linked repository only when the link applies to the PR. Confirm that your
guidance names the surface changing in the PR. For example, guidance that only mentions "API
routes" does not apply to a CSS-only change. If the guidance is already specific, the linked
repository may not be affected.
Confirm two things: the referenced PR is in a linked repository, and the
reference in the reviewed PR description uses one of the recognized formats (full GitHub URL or
`owner/repo#number`). Bare `#number` shorthand is ignored because it can't point at another
repository.
Each repository can link to up to 5 other repositories. Remove an unused link from the
**Cross-repo reviews** card to free a slot, or [contact us](mailto:contact@cubic.dev).
The target repository is archived, has been removed from the installation, has moved to a
different installation, or cubic has lost access to it. Restore access or remove the link.
# Custom agents
Source: https://docs.cubic.dev/ai-review/custom-agents
Discover, create, and manage custom agents across your repositories
Custom agents are review rules that enforce your organization's specific best practices across pull requests.
Use the rules library to create agents, adopt community rules, and choose which repositories use them.
![Rules library with categories and multi-repo management]()
## Rules library
Manage your agents from the [rules library](https://www.cubic.dev/rules-library).
## Creating custom agents
To create a new agent, navigate to the **[Rules library](https://www.cubic.dev/rules-library)** in cubic and click "Add rule". You can also adopt existing agents from the community library with a single click.
Each custom agent includes:
1. **A Name**\
A concise title, like "Prevent N+1 Queries" or "Require Sentry Error Handling."
2. **A Description**\
A clear, natural-language instruction the AI will use, such as "Flag code that may cause multiple database calls inside loops."
Be as clear and explicit as possible; the more specific you are, the better the results.
3. **Linked instruction files**
For repository-specific agents, open **Advanced** and enter one repo-relative path per line, such as `docs/style-guide.md` or `.cubic/review-agent.md`. You can use linked files together with text instructions. You can also define linked files in `cubic.yaml` with a `file_paths` list. cubic reads those files from the pull request head commit when the review runs, so updates to the file apply to future reviews without editing the agent.
File-backed agents are best when your team already maintains detailed style, framework, or architecture rules in the repository. General context files help cubic understand the codebase, but custom agents are the right place for checks you want cubic to actively flag.
The agent text and linked files share one 10,000 character limit. cubic uses the first 10,000
characters and ignores the rest. The multi-repository rules-library dialog still creates
text-only agents; use repository-scoped agents or `cubic.yaml` for linked files.
4. **Optional Path Filters**
Use [Glob patterns](https://en.wikipedia.org/wiki/Glob_\(programming\)) to limit where the agent applies (or exclude certain paths). This is especially helpful for monorepos, where different directories often require different agents. For example:
* **Include**: `backend/**` to apply the agent only to files under a `backend` folder.
* **Exclude**: `!tests/**` to ignore test files and focus on production code.
![Add agent]()
## Agent attribution in comments
When a custom agent flags an issue, the review comment will indicate which agent triggered it. This helps you understand which agents are working and allows you to iterate on your agent instructions over time.
![Review comment showing which custom agent triggered the feedback]()
## Managing agents across repositories
Create an agent once and select the repositories that use it. Updating the agent updates its instructions for all selected repositories. Enable or disable it for each repository independently.
## Limitations
* **Agent limit**: Each repository can have a maximum of 5 enabled custom agents at a time. The rules library allows you to define more agents but only 5 can be active per repository.
* **Instruction length**: Text instructions and resolved file instructions use the same 10,000 character limit per custom agent. cubic concatenates the text and files in order and uses only the first 10,000 characters; the rest is not included in the review prompt. The dashboard shows how many characters are left or truncated before you save.
* **File paths**: File-backed agents accept repo-relative file paths only. Absolute paths, globs, parent-directory traversal, directories, binary files, and unreadable files are rejected or shown as warnings. Markdown and YAML files are read as plain text; cubic does not parse them as structured rule definitions.
* **Potential false positives**: Occasionally, the AI might incorrectly flag or overlook certain scenarios. Consider AI feedback as helpful guidance rather than definitive judgments.
## Tips for effective custom agents
* Describe the code to flag and explain why it matters. Include examples when the rule is easy to misinterpret.
* Combine related checks when they share the same scope.
* Use path filters to keep rules relevant to the files being reviewed.
* Focus on checks that linters do not cover, such as business logic and team-specific conventions.
## Next steps
* [**Rules library**](https://www.cubic.dev/rules-library): Explore community agents and manage your custom agents across repositories.
* [**AI review settings**](/ai-review/ai-review-settings): Configure AI review behavior for your repositories.
* [**Introduction**](/ai-review/introduction): Understand how cubic reviews pull requests by default.
# Custom context
Source: https://docs.cubic.dev/ai-review/custom-context
Give cubic custom context to help it better understand your codebase.
You can give cubic more context about your codebase to help it understand your patterns, architecture, and conventions. You can do this in a couple of ways.
If you want a copy-paste `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` snippet for your coding
workflow, see [Local CLI review](/ide/cli-review).
## Context files in your repository
cubic automatically detects and uses context files in your repository, including `README.md`, `context.md`, `AGENTS.md`, `.cursorrules`, agent skills directories, and files in `.ai/` directories. These files help the AI understand your project structure, conventions, and guidelines without any additional configuration.
**README files**
* `README.md`, `readme.txt`, `ReadMe.rst` (any variation)
* `read.me`, `read-me.md`
**AI tool configuration files**
* `AGENTS.md` - OpenAI/Codex instructions
* `CLAUDE.md`, `claude.md` - Claude-specific guidelines
* `.cursorrules`, `.cursor.json` - Cursor editor rules
* `copilot-instructions.md`, `copilot.yaml` - GitHub Copilot configuration
* `.coderabbit.yaml` - CodeRabbit configuration
**AI tool skill directories**
* Files in the `.claude/skills/` directory - Claude Code skills
* Files in the `.codex/skills/` directory - OpenAI Codex skills
* Files in the `.opencode/skills/` directory - OpenCode skills
* Files in the `.cursor/skills/` directory - Cursor skills
* Files in the `.windsurf/skills/` directory - Windsurf skills
* Files in the `.gemini/skills/` directory - Gemini skills
* Files in the `.agents/skills/` directory - Cross-tool skills
**Generic context files**
* `context.md` - General project context
* `project_context.md` - Project-specific information
* `llm-context.md` - LLM-specific guidelines
* `ai_guidelines.md` - AI coding assistant instructions
* `CODEBASE-CONTEXT.md` - Codebase overview
* Any file ending with `-context.md` (e.g., `auth-context.md`, `api-context.md`)
**Other directories**
* Files in the `.ai/` directory
* Files in the `.cursor/` directory (including `.cursor/rules/`)
* Files in the `.github/` directory
* Files in the `.continue/` directory
### What to include in context files
Effective context files typically include:
* **Architecture overview**: High-level system design and component relationships
* **Coding conventions**: Team-specific patterns and practices
* **Domain knowledge**: Business logic and terminology
* **Common patterns**: Preferred approaches for common tasks
* **Dependencies**: Key libraries and their usage patterns
## Manual instructions via settings
For repository-specific guidelines that don't fit into files, you can add custom instructions directly in the cubic dashboard.
Navigate to [AI review settings](https://cubic.dev/ai-review) and use the **AI review instructions** field to provide plaintext instructions that will be included in every review.
![AI review settings with instructions field]()
This is useful for:
* Temporary guidelines during migrations or refactoring
* High-priority reminders that need immediate attention
* General review preferences that apply across the entire codebase
AI review instructions are configured at the repository level. Different repositories can have
different instructions based on their specific needs.
## One-off context in PR comments
You can also provide temporary context when manually triggering a review in GitHub comments.
For example:
* `@cubic-dev-ai review this and use https://docs.composio.dev/llms.txt`
* `@cubic-dev-ai rerun and focus on auth edge cases`
cubic will use this context for that run only. It does not change your saved settings.
## Custom agents for specific checks
When you want cubic to actively flag specific issues or patterns, use [custom agents](/ai-review/custom-agents) instead of general context.
If your team already has a style guide or review checklist in the repository, point a file-backed custom agent at that file from the dashboard or `cubic.yaml`. cubic will use the file as the enforceable agent instruction, while regular context files continue to provide background understanding.
Custom agents are ideal for:
* Enforcing specific coding standards
* Detecting anti-patterns unique to your codebase
* Preventing known security vulnerabilities
* Ensuring compliance with team conventions
Learn more about creating and managing custom agents in the [custom agents documentation](/ai-review/custom-agents).
## Best practices
Your main README is the most important context file. Ensure it clearly explains the project's purpose, architecture, and key conventions.
Outdated context can lead to incorrect suggestions. Review and update your context files
regularly, especially after major architectural changes.
Provide concrete examples and clear guidelines. Instead of "write good code," specify "use React
hooks instead of class components" or "prefer async/await over Promise chains."
For large projects, create separate context files for different domains (e.g.,
`frontend-context.md`, `backend-context.md`) to keep information focused and manageable.
Context files provide background information, while custom agents actively flag violations. Use
custom agents when you need cubic to consistently catch specific issues.
# Interactive comments
Source: https://docs.cubic.dev/ai-review/interactive-comments
Interact with cubic to ask questions, trigger reviews, and request fixes safely.
Interact with cubic in PR comments to ask questions, trigger reviews, and fix issues. You can tag
`@cubic-dev-ai` directly, or reply to cubic's existing comments to continue the conversation.
![Tagging cubic in a PR comment]()
## Why use interactive comments
* Ask follow-up questions about code changes without leaving the PR
* Re-trigger AI reviews after addressing feedback
* Get instant clarification on AI suggestions
* Build context through natural, threaded conversations
## How to interact with cubic
cubic responds when you:
### 1. Tag it directly
Mention `@cubic-dev-ai` anywhere in your comment.
cubic won't appear in GitHub's @ mention autocomplete dropdown. GitHub doesn't allow GitHub Apps
to be included in the autocomplete list. Just type the mention manually and it will work.
### 2. Reply to its comments
Simply reply to any of cubic's existing comments to continue the conversation. No @ mention is
needed for questions or feedback. cubic will react with 👀 to acknowledge your comment in both
cases.
Replying without explicitly tagging cubic does **not** authorize code changes. If you want cubic
to edit code, the current comment must explicitly include `@cubic-dev-ai`, or you can use the
**Fix with cubic** button.
## What you can do
### Ask questions
Get instant answers about code, design decisions, or implementation details:
* "@cubic-dev-ai will this color code work well in dark mode?"
* "@cubic-dev-ai can you explain how this function works?"
* "@cubic-dev-ai is there a better way to handle this error?"
### Trigger reviews
Tag `@cubic-dev-ai` to run a full or incremental AI review.
* **Full review:** `@cubic-dev-ai` or `@cubic-dev-ai review this PR`
* **Incremental review:** `@cubic-dev-ai incremental review` or
`@cubic-dev-ai review changes since the last review`
An incremental review covers only the changes since cubic's last completed review on the pull
request. Manual requests work even when automatic incremental reviews are disabled in settings or
`cubic.yaml`. If cubic cannot establish a safe range from a completed review, it explains why and
does not fall back to a full review.
### When cubic can't review
Manual review requests run regardless of the repository's maximum changed-lines setting. If a pull
request is above cubic's technical review maximum, cubic replies with the reviewable line count, the
largest files contributing to the diff, and what to do next: ignore generated or fixture files in
AI review settings or `cubic.yaml`, or split the change into smaller pull requests.
### Ultrareview
For high-risk or complex pull requests, ask cubic for an [ultrareview](/ai-review/ultrareview) —
a longer, deeper review using cubic's most capable review models:
* `@cubic-dev-ai ultrareview`
* `@cubic-dev-ai ultrareview: focus on auth edge cases`
[Ultrareview mode](/ai-review/ultrareview#availability-modes) needs to be set to **Manual** or **Automatic** for the repository in order for this trigger to work. Ultrareview mode is set to **Manual** by default.
Ultrareviews can also [start automatically](/ai-review/ultrareview#auto-trigger-ultrareviews)
based on file rules or a per-repository risk policy. See the
[ultrareview docs](/ai-review/ultrareview) for how it works, billing, and configuration.
### Add one-off context to a review run
You can include extra guidance in the same comment when you trigger a review. cubic forwards the
text from your `@cubic-dev-ai` comment as context for that specific run.
Examples:
* `@cubic-dev-ai review this and use https://docs.composio.dev/llms.txt`
* `@cubic-dev-ai rerun and focus on auth edge cases`
* `@cubic-dev-ai review this with the migration notes in https://internal.docs/migration`
This context is one-off. It only applies to the run triggered by that comment and does not update
your repository-level AI review instructions.
To stop an in-progress AI review, use the **Cancel AI review** button in the GitHub Checks UI.
### Request fixes
Ask `@cubic-dev-ai` to generate fixes for identified issues with the "Fix with cubic" button in
the GitHub comment, or by tagging `@cubic-dev-ai` in the current comment. For example:
* "@cubic-dev-ai fix this issue in this branch"
* "@cubic-dev-ai can you generate a fix for this in a new PR?"
By default, cubic pushes fix commits directly to your PR branch. To override, say "open a fix PR"
and cubic will create a separate PR targeting your feature branch. Learn more about
[AI-powered code fixes](/ai-review/coding-agents).
A reply like "can we change this to..." inside a cubic thread is treated as discussion unless that
same comment explicitly tags `@cubic-dev-ai`.
### Provide feedback and continue conversations
Reply directly to cubic's review comments (no @ mention needed) to:
**Continue the discussion:**
* "This would break our legacy API compatibility"
* "What about error handling in this case?"
* "Can you suggest an alternative approach?"
**Provide feedback for learning:**
* "This is a false positive, Next.js handles this automatically"
* "The rule is too strict for our use case"
* "This doesn't apply to React Server Components"
cubic will respond to your replies, maintaining the full context of the conversation thread.
## Tips and best practices
* **Natural conversations**: After cubic's initial comment, just reply normally for questions and feedback
* **Fixes require a fresh explicit tag**: Use `@cubic-dev-ai` or the **Fix with cubic** button whenever you want cubic to edit code
* **Context awareness**: cubic maintains the full thread context, understanding both the original suggestion and all previous replies
* **Be specific**: More detailed questions get more helpful answers
* **Natural language**: Write as you would to a teammate
* **Multi-turn discussions**: Feel free to have back-and-forth conversations to refine suggestions or explore alternatives
# Introduction
Source: https://docs.cubic.dev/ai-review/introduction
cubic is the top-ranked AI code reviewer on Code Review Bench for complex codebases on GitHub.
7 days free, no credit card required.
Learn more about cubic and how it works.
**Independent benchmark**: cubic is the [top-ranked AI code
reviewer](https://www.cubic.dev/blog/cubic-is-the-best-ai-code-reviewer-on-martian-s-benchmark) on
[Code Review Bench](https://codereview.withmartian.com/?mode=offline).
## Key features
* **Spots bugs and improvements**: Comments on bugs and improvements in pull requests
* **Auto-resolve threads**: Enable automatic thread resolution to close findings when the issue is fixed
* **Learns from you**: Improves over time by learning from your feedback
* **PR summaries**: Generates PR descriptions based on code changes
* **Custom agents**: Enforce your team's coding standards
* **Coding agents**: Generate fixes when requested, using your configured provider
![Example review]()
## Getting started
Sign up at [cubic.dev/sign-up](https://cubic.dev/sign-up). This will guide you through
installing the cubic GitHub App on the repositories you want to analyze.
Once installed, cubic automatically reviews new pull requests. See [example reviews for PostHog,
n8n, and more](https://cubic.dev/examples).
Follow the [Developer Quickstart](/ai-review/quickstart) to run your first review and respond to
findings.
Want cubic inside Cursor, Claude Code, Codex, or another coding agent? Start with [Connect cubic
to your IDE](/ide/agent-setup) and [Local CLI review](/ide/cli-review).
**Existing pull requests**: Reviews for new PRs start automatically. To review a PR that was
opened *before* you installed the app, comment: `@cubic-dev-ai review this PR`.
## Security and privacy
* **No third-party model training:** Our AI providers are contractually prevented from using your code to train their models.
* **SOC 2 compliant:** We are SOC 2 Type I compliant.
For more details, see our full [Privacy & Security documentation](/account/privacy-security).
## Frequently asked questions
Not yet. We currently only support **GitHub**.
cubic is language-agnostic and supports all popular programming languages, including JavaScript,
TypeScript, Python, Go, Ruby, PHP, Java, C#, C/C++, Rust, Kotlin, and Swift.
cubic uses multiple model providers, with different models for different review tasks.
If a pull request contains more than 200 eligible files, cubic selects up to 200 of the
highest-priority eligible files for this review.
Yes. cubic has access to library and framework documentation to check APIs and deprecations
during reviews.
## Next steps
* [**Developer Quickstart**](/ai-review/quickstart): Hands-on tutorial for interacting with AI reviews.
* [**Connect cubic to your IDE**](/ide/agent-setup): Install cubic in Cursor, Claude Code, VS Code, Codex, Gemini CLI, or another coding tool.
* [**Local CLI review**](/ide/cli-review): Add the advanced local-review loop before you push.
* [**Key features**](/ai-review/key-features): Discover what the AI reviewer can do.
* [**Custom review rules**](/ai-review/custom-agents): Tailor the AI to your team's coding standards.
# Issue tracker integration
Source: https://docs.cubic.dev/ai-review/issue-analysis
Track if PRs meet the requirements from your linked issues.
cubic can automatically analyze your pull requests to see if they meet the requirements from your linked Linear, Jira, Asana, or GitHub issues.
Connect cubic to your issue tracker (like Linear, Jira, or GitHub Issues) to verify your PRs meet the objectives laid out in the linked issue.
cubic also uses context from the linked issue to inform its AI code review and PR description.
![Issue analysis showing acceptance criteria results]()
## How it works
When you create a pull request with a linked issue, cubic:
1. **Finds your issue** - Looks for issue IDs like `ABC-123` in your PR title or branch name. For GitHub Issues, it uses the issue your PR closes, such as `Fixes #123`
2. **Reads requirements** - Extracts the requirements from your issue description
3. **Checks your code** - Compares your changes against those requirements
4. **Shows results** - Adds a table to your PR review showing what's done and what's missing
## Requirements
For issue analysis to work:
1. **Link an issue** - Include the issue ID in your PR title or branch name. For GitHub Issues, [link the issue on GitHub](/integrations/github-issues-integration#how-it-works)
2. **Add requirements** - Your issue must have a description with clear objectives
3. **Enable AI review and connect your issue tracker** - Make sure AI review is enabled and that you've connected your issue tracker in the [integrations page](https://www.cubic.dev/settings?tab=integrations)
If the linked issue doesn't have a description or requirements, the analysis won't run.
## Writing good requirements
cubic looks for requirements written as:
* Bullet points or numbered lists
* Sections labeled "Acceptance Criteria" or "Requirements"
* Clear action items starting with "Should", "Must", or "Can"
### Good example
```
## Acceptance Criteria
- User can submit the contact form
- Form shows validation errors for invalid email
- Form data is saved to the database
- User receives a confirmation message
```
### What won't work
```
Make the form work better
```
## Tips for better results
* **Be specific** - Write clear, testable requirements
* **Break it down** - Use multiple small requirements instead of one big one
* **Include details** - Mention specific features or behaviors
## Troubleshooting
**Not seeing the analysis?**
* Check that your issue ID is in the PR title or branch, or for GitHub Issues, that the PR closes the issue
* Make sure your issue has requirements in the description
* Verify AI review is enabled in settings
**Results seem wrong?**
* The analysis only checks files changed in the PR
* Very general requirements might be hard to verify
* Try making your requirements more specific
# Key features
Source: https://docs.cubic.dev/ai-review/key-features
Explore the core features of cubic’s AI-powered code review.
## Spots bugs and suggests improvements
The AI automatically scans every pull request for a wide range of issues, including logic errors, style inconsistencies, and potential security vulnerabilities.
Comments and suggestions are added directly to the pull request, making them easy to review and address.
![AI code review flag]()
## Ultrareview
When a pull request needs extra scrutiny, you can ask cubic for an Ultrareview. Ultrareview runs a
longer review using cubic's most capable review models, which is useful for risky migrations,
security-sensitive changes, or complex refactors.
Learn how to request one in [Interactive comments](/ai-review/interactive-comments).
## Background agents
cubic can automatically fix issues in the background. When the AI spots a problem, you can click
the **Fix with cubic** button or explicitly tag cubic in the current comment, for example with
`@cubic` or `@cubic-dev-ai`, to generate and apply fixes without manual intervention.
## Coding agents and local workflow
You can run cubic locally as well as on GitHub. Connect cubic to Cursor, Claude Code, VS Code, Codex, Gemini CLI, or another coding agent to run local reviews, inspect PR feedback, and ask codebase questions without leaving your workflow.
* Start with [Connect cubic to your IDE](/ide/agent-setup) when you're ready to install cubic in the tool you already use
* Use [Local CLI review](/ide/cli-review) if you want cubic to review code before you open a pull request
## CLI for local reviews
Run AI code reviews locally before pushing to GitHub. The [cubic CLI](/ide/cli-review) is intentionally faster and less thorough than cubic's cloud PR review, so treat it as a pre-flight check for uncommitted changes, branches, or specific commits rather than expecting identical findings.
```bash theme={null}
curl -fsSL https://cubic.dev/install | bash
cubic review
```
![cubic CLI results]()
## Learns from you
The AI adapts to your team's feedback. When you react to a suggestion or provide a correction, the AI remembers.
This helps reduce false positives over time and tailors advice to your specific codebase and coding standards.
## Always up to date
When you push new commits to an open PR, cubic reviews only the incremental changes. Comments are only posted when new issues are discovered—you won't see repeated feedback on previously reviewed code.
This makes reviews faster and reduces noise as you iterate on your PR.
## Auto-approval
cubic can approve clean pull requests automatically when your repository policy allows it. Start in shadow mode to see which PRs cubic would approve, then switch to live mode when the policy matches your team's expectations.
Learn more in [Auto-approval](/ai-review/auto-approval).
## Up-to-date library knowledge
cubic has access to current documentation for the libraries and frameworks in your stack. This means suggestions account for the latest APIs, deprecations, and best practices—not outdated patterns from months-old training data.
## AI wiki
Automatically generate searchable documentation for your codebase. The [AI wiki](/wiki/ai-wiki) indexes your repository and answers questions in plain English—great for onboarding, understanding unfamiliar code, or getting architecture diagrams on demand.
![Wiki documentation]()
## PR summaries
Automatically generate clear and concise descriptions for your pull requests to help reviewers quickly understand the purpose and impact of the changes.
The AI analyzes your code changes and creates comprehensive summaries that include what was changed, why it was changed, and any potential impacts.
![AI-generated PR descriptions]()
## Custom agents
Define custom agents to enforce team-specific standards and domain-specific guidelines.
This allows you to check for internal API usage patterns, adherence to architectural decisions, or deprecated functions. You can create agents using natural language or code patterns.
![Custom agents library]()
## Cross-repo reviews
Cross-repo reviews help cubic catch changes that need a matching update in another repository. Link
related repositories so reviews can check shared APIs, schemas, docs, or release work.
Learn more in [Cross-repo reviews](/ai-review/cross-repo-reviews).
# Memory and learning
Source: https://docs.cubic.dev/ai-review/memory-and-learning
Teaching cubic to provide increasingly relevant suggestions.
cubic learns your team's unwritten rules from two sources: direct feedback on its comments, and patterns extracted from your senior engineers' historical code reviews.
![Memory and learning]()
## How cubic learns
cubic automatically learns when you:
* **Reply to its comments:** Type a response explaining what cubic should do differently, and it remembers for next time
* **Provide context in threads:** Explain why something matters to your team, and cubic incorporates that knowledge
* **React to suggestions:** Thumbs up/down help cubic calibrate what's useful vs noise for your specific codebase
## Senior reviewer learnings
During onboarding, you can select your team's most experienced reviewers. cubic analyzes their historical PR comments to extract learnings from the patterns they consistently enforce. These become senior reviewer learnings that help cubic match your team's review style.
All senior reviewer learnings appear in your [Learnings Tab](https://www.cubic.dev/ai-review?tab=learnings) grouped under "Team patterns" showing you exactly what cubic learned from your engineers' reviews.
![Senior reviewer learnings]()
## What cubic remembers
* **Team-specific patterns:** "We always use early returns" or "Integration tests required for API endpoints"
* **Technical constraints:** "This library causes performance issues in our stack"
* **Process requirements:** "Check with platform team before modifying auth service"
Each learning is scoped to your team. Your feedback trains your instance of cubic, not everyone else's.
## How feedback improves existing learnings
Feedback can become a learning when it describes a rule that cubic can apply in future reviews. For example, "Require pagination for endpoints that return lists" can become a learning, while "Rename this variable in this PR" applies only to the current pull request.
cubic compares qualifying feedback with the repository's existing learnings. It can:
* **Create** a new learning when the feedback adds new guidance.
* **Improve** an existing learning, such as adding "except in generated parsers" to "Use early returns."
* **Remove** an outdated learning, such as an Axios warning after your team approves Axios.
* **Keep** an existing learning when it already covers the feedback.
Broad feedback and short replies such as "thanks" or "done" do not become learnings.
## How cubic applies learnings
During reviews, cubic uses relevant learnings to find issues and avoid repeating known false positives.
The **Do not apply when** section records exceptions. For example, a learning that says "Require authentication middleware for API routes" might say "Do not apply when the route is a public health check."
## Weekly learning cleanup
Each week, cubic reviews your learnings to keep the guidance useful. It combines duplicates, archives guidance that no longer improves reviews, and keeps guidance that needs more evidence. Archived learnings stop affecting reviews and disappear from the active Learnings list.
## Review and manage learnings
* Open [AI review settings](https://www.cubic.dev/settings?tab=ai-review) → Memory & Learning to browse everything cubic has learned, and to edit or delete learnings
* Search and filter by rule to pinpoint the guidance that matters to specific parts of your codebase
## Privacy and control
* **Explicit learning only:** cubic only learns from feedback directly addressed to it in comments
* **Team-scoped:** Learnings never leak between different organizations or repositories
* **Transparent history:** View and manage all learnings in the AI review settings dashboard
## Import learnings from other AI code review tools
You can import a CSV of learnings exported from another service:
* Start by exporting existing learnings from other services. Check the docs on how to [export from CodeRabbit](https://docs.coderabbit.ai/knowledge-base/learnings#export-learnings).
* Open the [Learnings Tab](https://www.cubic.dev/ai-review?tab=learnings) and select **Import CSV** from the three-dot menu.
* Drag and drop a CSV file (max 5MB) with column names. We'll auto-detect properties based on column names for you, or you can use our downloadable [CSV template](https://www.cubic.dev/templates/learnings-import-template.csv). Note that 'repository' and 'description' columns are required.
* Review that all data is correct and click Import. We'll process the learnings in the background and send you an email once the import is complete.
# Developer quickstart
Source: https://docs.cubic.dev/ai-review/quickstart
Get started with cubic AI code review in minutes.
## 1. Install the cubic GitHub App
Go to [cubic.dev/sign-up](https://cubic.dev/sign-up) and sign in with your GitHub account.
Select the repositories you want cubic to review. You'll get 7 days free, no credit card
required.
## 2. Trigger your first review
**Open a new pull request**
cubic automatically starts reviewing new pull requests in your selected repositories.
**Or review an existing PR**
Post this comment on GitHub to start a review:
```text theme={null}
@cubic-dev-ai review this PR
```
You'll see inline comments pointing out bugs and improvements, with explanations and
suggested fixes.
For complex PRs, trigger an [Ultrareview](/ai-review/ultrareview) for a deeper review.
**Automatically approve clean PRs.** Enable [auto-approval](/ai-review/auto-approval) to let cubic
approve PRs that meet your review policy.
## 3. Interact with cubic
### Ask follow-up questions
Reply to a review comment to ask for clarification:
```text theme={null}
@cubic-dev-ai Can you explain why this is a concern?
```
cubic responds with more context. Tell it when a finding isn't relevant to help it
[learn your team's preferences](/ai-review/memory-and-learning).
### Request a fix
Click **Fix with cubic** on a review comment, or ask cubic directly:
```text theme={null}
@cubic-dev-ai Please fix this
```
cubic generates the fix and pushes it to your PR branch. Review the changes before
merging. To get a separate PR, ask: `@cubic-dev-ai open a fix PR`.
See [Coding agents](/ai-review/coding-agents) for setup and
[Interactive comments](/ai-review/interactive-comments) for more ways to work with cubic.
## 4. Review locally with the CLI
Run a review before you push to catch issues while you're working.
Install the cubic CLI:
```bash theme={null}
curl -fsSL https://cubic.dev/install | bash
```
```powershell theme={null}
npx @cubic-dev-ai/cli install -g
```
Run `cubic` and sign in through your browser. Then, from your repository, review
your uncommitted changes:
```bash theme={null}
cubic review
```
To review all changes on your branch against its base, run `cubic review -b`.
Use the findings to fix issues yourself or pass them to your coding agent, then
push your changes for a GitHub review.
See [Local CLI review](/ide/cli-review) for more commands and model options.
## 5. Review the PR in cubic
Open your pull request on [cubic.dev](https://www.cubic.dev) to review the code yourself.
cubic helps you understand how the changes fit together and where to focus your attention:
* **Review related changes together.** File groups organize the diff by what changed, with explanations of the intent and behavior behind each group.
* **Get a guided walkthrough.** Ask chat to "tour this PR" for a step-by-step review of the changes and what to check.
* **Ask questions beside the code.** Select code and choose **Add to AI chat** to ask about it with the diff and codebase as context.
* **Submit your review.** Leave comments, approve, or request changes from cubic. Your review is published to GitHub.
Use the grouped diff to get oriented, then dig into the changes that need your judgment
before merging.
## Next steps
* [Connect your IDE](/ide/agent-setup) to work with review findings from your coding agent.
* [Create custom agents](/ai-review/custom-agents) for team-specific review rules.
* [Configure reviews](/ai-review/ai-review-settings) for your repositories.
* [Contact support](/account/support) if you need help.
# Ultrareview
Source: https://docs.cubic.dev/ai-review/ultrareview
A deep, multi-pass review for the pull requests where a missed bug hurts the most.
Ultrareview is cubic's deepest review. It runs a longer, multi-pass analysis using cubic's most capable review models, and typically takes around 30 minutes. The standard review is built for every PR; ultrareview is built for the ones where the blast radius of a missed bug is severe — migrations, auth, payments, concurrency, large refactors.
Ultrareview is available on paid and trial plans and uses your team's reviewed-lines allowance at 3× the standard rate, reflecting the extra compute of its multi-pass analysis.
## Availability modes
The **Ultrareview** card at the top of [AI review → Ultrareview](https://www.cubic.dev/ai-review?tab=ultrareview) (or `reviews.ultrareview` in [cubic.yaml](/configure/cubic-yaml)) controls whether ultrareviews can run at all:
* **Disabled** — no ultrareviews. Comment commands get a reply explaining that ultrareview is turned off, dashboard triggers show an error, and automatic triggers never fire.
* **Manual** (default) — ultrareviews run only when someone triggers them, via `@cubic-dev-ai ultrareview` or the PR page in the cubic app.
* **Automatic** — the file rules and risk policy below are active. Manual triggers stay available — Automatic includes everything Manual allows.
## Run one manually
Tag cubic on any pull request:
* `@cubic-dev-ai ultrareview`
* `@cubic-dev-ai ultrareview: focus on auth edge cases`
Anything you write after the command is forwarded to the reviewer as one-off guidance for that run. You can also start an ultrareview from the PR page in the cubic app.
cubic posts a comment when the ultrareview starts and posts its findings when it completes. Pushing new commits does not restart it.
## Auto-trigger ultrareviews
You can have cubic start an ultrareview automatically when a PR is opened or marked ready for review. Set the ultrareview mode to **Automatic**, then configure the triggers per repository in [AI review → Ultrareview](https://www.cubic.dev/ai-review?tab=ultrareview).
There are two independent mechanisms, and they compose:
1. **File rules** — glob patterns checked against the PR's changed files. If any file matches, the ultrareview starts. Deterministic, free to evaluate, and active whenever the mode is **Automatic** and the list is non-empty — remove all patterns to turn them off.
2. **A risk policy** — cubic reads the PR's diffs and decides whether it warrants an ultrareview.
### Risk policies
* **Off** (default): cubic never decides on its own to run an ultrareview. File rules still apply — they are a separate trigger.
* **High-risk PRs** (recommended): cubic triggers only when a missed bug would be severe — schema changes, auth, payments, concurrency, public API contracts, cross-cutting refactors. Most PRs stay on the standard review.
* **Custom prompt**: describe the criteria in your own words, for example "PRs touching auth, payments, or database migrations." cubic evaluates each PR against your description.
File rules are checked first — a glob match never costs an AI evaluation.
### What to expect
* Auto-triggers fire only when a PR is opened or marked ready for review. Pushes to an open PR get standard reviews; the ultrareview is not re-triggered per push.
* Auto-triggered ultrareviews post a PR comment explaining why they started, so the decision is never a mystery.
* The trigger is conservative: when cubic is unsure, the PR gets the standard review. If the evaluation fails for any reason, the standard review runs as usual.
Start with file rules for the paths you already know are sensitive (for example
`**/migrations/**`), then add the **High-risk PRs** policy to catch risky changes outside those
paths.
## Configure via cubic.yaml
All of this is also configurable in [cubic.yaml](/configure/cubic-yaml), which overrides the UI settings per field:
```yaml theme={null}
version: 1
reviews:
# disabled | manual | automatic — the triggers below only fire in automatic
# mode. Configuring them without this key implies automatic.
ultrareview: automatic
# disabled | high_risk_only | custom
auto_ultrareview: high_risk_only
auto_ultrareview_custom_prompt: |
Run an ultrareview when auth or payment flows change.
# In automatic mode, file rules trigger independently of auto_ultrareview —
# remove the list entirely to turn them off.
auto_ultrareview_file_patterns:
- '**/migrations/**'
- 'infra/**'
```
`auto_ultrareview_custom_prompt` is only used when `auto_ultrareview` is `custom`.
## Billing
Every ultrareview — manual or auto-triggered — uses your team's reviewed-lines allowance at 3× the standard rate. Track usage on the [usage page](https://www.cubic.dev/settings?tab=usage).
# AI coding
Source: https://docs.cubic.dev/analytics/ai-coding
Understand how AI tools contribute to your codebase with authorship breakdowns, tool usage, and team adoption metrics.
The AI coding tab shows how AI assistants contribute to merged pull requests in your repositories.
cubic detects AI contributions from commit metadata (git notes) attached to merged PRs. Install the
[cubic CLI](/ide/cli-review) to automatically set up [git-ai](https://usegitai.com) attribution
tracking. Without git-ai or a tool that emits its own notes, contributions may not appear. See
[AI attribution tracking](#ai-attribution-tracking) for details.
## What you see
* **Authorship over time**: trend of Human, Mixed, and AI-authored lines.
* **Usage breakdown**: percentage split across Human, Mixed, and AI.
* **Tools and models**: which assistants and models generated code.
* **Team members**: per-developer AI adoption and top tool.
* **Attribution card**: percent of commits that include AI metadata.
## Authorship categories
| Category | Meaning |
| --------- | -------------------------------------------- |
| **Human** | Written without AI assistance. |
| **Mixed** | Generated by AI, then edited by a developer. |
| **AI** | Generated by AI and accepted without edits. |
This model helps teams distinguish AI-first output from AI-assisted editing.
## Team members
The team members table includes:
| Column | Meaning |
| ------------------ | ------------------------------------------------------------------- |
| **% AI code** | Share of this developer's lines authored with AI help (AI + Mixed). |
| **Lines by AI** | AI-attributed lines for this developer. |
| **Lines by human** | Human-authored lines for this developer. |
| **Top tool** | Most-used AI coding tool in the selected period. |
Filter by username to find specific team members. Click column headers to sort.
### CSV export
You can export the current team members view as CSV for reporting or sharing. The export includes
the rows currently shown in the table and respects your active sort order.
## Tools and models
Use the tools and models tables to answer two questions quickly:
* Which assistants or models are used most?
* Are suggestions accepted as-is, or usually edited before merge?
## AI attribution tracking
**% of commits with AI attribution** is the share of merged-PR commits that include AI git note metadata.
Low attribution usually means one of three things: your tool/version does not emit git notes, code was copied manually from chat tools, or web-UI squash merges created new commits without authorship logs (a CI workflow can reconstruct them).
cubic starts collecting AI attribution data from the date you install it. Historical commits
before installation are not retroactively analyzed.
### Automatic setup with cubic CLI
The [cubic CLI](/ide/cli-review) automatically installs [git-ai](https://usegitai.com) during setup to maximize attribution coverage. git-ai attaches AI authorship notes to commits so contributions are captured even when AI tools don't emit their own metadata.
You can opt out at install time with `CUBIC_DISABLE_GIT_AI=true`, or toggle tracking afterwards with `cubic stats enable` / `cubic stats disable`. See the [CLI docs](/ide/cli-review#ai-attribution-tracking) for details.
## Supported tools
cubic currently detects contributions from:
* Cursor
* GitHub Copilot
* Claude Code
* Windsurf
* Aider
* JetBrains AI
The list of detected tools expands over time. If your tool is missing, [contact us](mailto:contact@cubic.dev?subject=AI%20tool%20detection%20request).
# AI review
Source: https://docs.cubic.dev/analytics/ai-review
Measure cubic's code review impact — comments posted, issues fixed, merge time improvements, and critical issues caught.
The AI review tab shows whether cubic reviews are helping your team ship better code faster.
## Top-level metrics
The top metrics focus on:
* **Comments posted**: how much review activity cubic generated.
* **Issues fixed after comment**: how often developers acted on findings.
* **Average time to merge**: merge speed compared against a pre-cubic baseline.
The **average time to merge** comparison uses every eligible merged PR in the selected period.
Sample counts and availability states show when the comparison has limited or incomplete evidence.
## Critical issues
The critical issues section highlights high-impact findings across recent PRs. Use it for quick triage and recurring-pattern detection.
## Your team in numbers
The sidebar summarizes team-level usage and quality:
* **PRs reviewed**
* **Downvote rate** (lower is better)
* **CLI sessions**
* **Fix PRs merged**
Downvotes also help cubic learn. When you downvote a suggestion, cubic remembers that feedback and
adjusts future reviews accordingly. See [Memory and learning](/ai-review/memory-and-learning) for
details.
## Custom agents
The custom agents table shows which agents flag the most issues and how many of those issues were fixed.
## Tips for interpreting these metrics
* **Prioritize fixed issues over raw comment volume.**
* **Use downvote rate as a quality signal for prompt/rule tuning.**
* **Compare trends over 30+ days instead of one short window.**
* **Treat merge-time change as directional, not absolute truth.**
# Analytics API
Source: https://docs.cubic.dev/analytics/api
Analyze cubic adoption using your own tools.
You may need to measure impact of cubic, but already have a set of analytics tools. The Analytics API gives you PR-level data on how many issues were flagged, how many were fixed, how much AI code was authored, etc.
## Get an API key
Analytics API access requires a Pro plan.
Go to [Settings → Integrations → Analytics API](https://www.cubic.dev/settings?tab=integrations\&integration=analytics).
Click **Generate API key**. Analytics API keys start with `cak_`, and cubic only shows the full value once.
Save the key in your secret manager or local environment. If you revoke or regenerate the key, the previous value stops working immediately.
API keys are personal. Each team member should generate their own key, and every request is limited to the organizations and repositories that key owner can already access in cubic.
## Endpoint
Use this endpoint to fetch merged pull requests that have completed cubic reviews in the selected time window.
Analytics responses may reflect normal read-replica lag. Recent reviews, pull request updates, and custom-rule changes can take a short time to appear, so do not use these responses for immediate read-after-write verification.
| Method | Endpoint |
| ------ | -------------------------------------------- |
| `GET` | `https://www.cubic.dev/api/analytics/v1/prs` |
### Authentication
Send the Analytics API key in the `Authorization` header as a bearer token.
```http theme={null}
Authorization: Bearer cak_your_api_key
```
### Example requests
```bash cURL theme={null}
curl --request GET \
--url 'https://www.cubic.dev/api/analytics/v1/prs?org=your-org&perPage=100' \
--header 'Authorization: Bearer cak_your_api_key' \
--header 'Accept: application/json'
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://www.cubic.dev/api/analytics/v1/prs?org=your-org&perPage=100',
{
headers: {
Authorization: 'Bearer cak_your_api_key',
Accept: 'application/json',
},
},
);
if (!response.ok) {
throw new Error('Failed to fetch pull request analytics');
}
const payload = await response.json();
console.log(payload.data);
console.log(payload.nextCursor);
```
## Query parameters
| Parameter | Required | Description |
| ----------- | -------- | ---------------------------------------------------------------------------------------------- |
| `org` | Yes | GitHub organization or owner whose pull request analytics you want to fetch. |
| `repo` | No | Limit the request to a single repository inside the selected owner. |
| `startDate` | No | Start of the time window. Supports ISO 8601 timestamps and date-only values like `2026-04-01`. |
| `endDate` | No | End of the time window. Supports ISO 8601 timestamps and date-only values like `2026-04-30`. |
| `perPage` | No | Number of results per page. Defaults to `100` and is capped at `100`. |
| `cursor` | No | Cursor from the previous response. Use it to fetch the next page. |
If you do not send `startDate` or `endDate`, cubic picks a default window based on how much data is available for that installation: the last 30 days, last 7 days, or last 24 hours.
Date-only values are interpreted in UTC. For example, `endDate=2026-04-30` includes the full day through `23:59:59.999Z`.
If you send only one date bound, cubic fills in the other one for you:
* `startDate` only: `endDate` defaults to the current time
* `endDate` only: `startDate` defaults to the start of available data
## Response format
The API returns one page of PR rows plus an optional cursor for the next page.
```json theme={null}
{
"data": [
{
"org": "acme",
"repo": "backend",
"prNumber": 4645,
"author": "john-doe",
"createdAt": "2026-04-16T12:00:00.000Z",
"mergedAt": "2026-04-17T12:00:00.000Z",
"linesAdded": 543,
"linesDeleted": 12,
"numberOfCubicIssuesFlagged": 5,
"numberOfCubicIssuesFixed": 4,
"cubicFirstReviewedAt": "2026-04-17T00:00:00.000Z",
"totalAiLinesAuthored": 523
}
],
"nextCursor": "2026-04-16T12:00:00.000Z|102"
}
```
### Top-level fields
| Field | Description |
| ------------ | ------------------------------------------------------------------- |
| `data` | The current page of pull request analytics rows. |
| `nextCursor` | Cursor for the next page, or `null` when there are no more results. |
### Pull request row fields
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org` | GitHub owner used for the request. |
| `repo` | Repository name. |
| `prNumber` | Pull request number. |
| `author` | GitHub login of the pull request author. |
| `createdAt` | Pull request creation timestamp in ISO 8601 format. |
| `mergedAt` | Pull request merge timestamp in ISO 8601 format. |
| `linesAdded` | Lines added in the pull request, or `null` when unavailable. |
| `linesDeleted` | Lines deleted in the pull request, or `null` when unavailable. |
| `numberOfCubicIssuesFlagged` | Posted cubic findings on the merged pull request, created within the requested date range. |
| `numberOfCubicIssuesFixed` | Posted findings in the requested date range with a detected code change (`aiAddressed = true`). Positive feedback alone does not count as a fix, and downvotes do not erase detected fixes. |
| `cubicFirstReviewedAt` | Timestamp of the first completed cubic review for the pull request. |
| `totalAiLinesAuthored` | Total AI-authored lines attributed to the pull request, or `null` when no AI authorship data is available. |
## Pagination
When `nextCursor` is present, send it back in the next request to continue from the previous page.
```bash theme={null}
curl --request GET \
--url 'https://www.cubic.dev/api/analytics/v1/prs?org=your-org&perPage=100&cursor=2026-04-16T12%3A00%3A00.000Z%7C102' \
--header 'Authorization: Bearer cak_your_api_key' \
--header 'Accept: application/json'
```
## Common errors
| Status | When it happens |
| ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Missing `org`, invalid query parameters, invalid cursor, or invalid date range. |
| `401` | Missing bearer token, invalid API key, or expired API key. |
| `403` | The API key owner does not have access to the requested organization or repository, or the requested organization is not on Pro. |
| `404` | cubic cannot resolve the `org` to an installation. |
## Dashboard trends endpoint
The signed-in cubic dashboard loads chart series from `GET /api/analytics/trends`. This endpoint
uses the current dashboard session rather than an Analytics API key.
| Parameter | Required | Description |
| ---------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
| `installationId` | Yes | Installation to load; the signed-in user must have access. |
| `repositoryId` | No | Limit results to one authorized repository. |
| `teamSlugs` | No | Comma-separated team slugs used to scope members. |
| `period` | Yes | `24h`, `7d`, `30d`, `all`, or `custom`. |
| `startDate`, `endDate` | For `custom` | Inclusive UTC date bounds. |
| `view` | No | `full` (default) returns all nine series; `dashboard` omits the two adjusted merge-time series. |
Successful responses contain `series` entries with metric, unit, bucket, comparison metadata,
summary values, and points, plus `meta` with computation, stale, unavailable, and refresh state.
Every response includes `X-Correlation-ID`; error bodies include the same ID. The endpoint returns
`400` for invalid parameters, `401` for a missing session, `403` for inaccessible scope, `404` for a
missing installation, `429` for rate limits, `504` for deadline expiry, and `500` for other failures.
Trend points for `merged_prs_per_day` and `changed_lines_per_day` use the number of UTC calendar
days in each daily or weekly bucket. They include only pull requests merged after the installation
was created for the current period; buckets that end before installation are unavailable. Summary
rates use the elapsed selected window after applying the same installation boundary.
For buckets that end before installation, `comments_posted`, `issues_fixed`, and `fix_rate` points
also have `result.status: "unavailable"` and `result.value: null`. After installation, zero
`comments_posted` and `issues_fixed` counts are ready values; `fix_rate` has status
`insufficient_data` when no comments were posted.
# Delivery and effectiveness
Source: https://docs.cubic.dev/analytics/delivery-and-effectiveness
Track PR velocity, review cycle times, throughput per developer, and code output across your team.
The Delivery and effectiveness tab focuses on how quickly PRs move from creation to merge and where bottlenecks appear.
## Velocity metrics
The top velocity metrics are:
* **Median wait-to-first-review**: median time for merged PRs from ready for review to first human review. Falls back to PR creation when ready-for-review events are unavailable.
* **Average review cycles until merge**: how many revision rounds PRs go through.
* **Average PR cycle time**: total creation-to-merge time.
* **Average time in review**: first review to final approval.
* **Average time from approval to merge**: post-approval operational delay.
A decreasing trend is positive — it means PRs are getting reviewed faster. The trend indicator
reflects this: a downward change appears in green.
## Throughput metrics
* **PRs merged per developer**: average merged output for active authors.
* **PRs reviewed per developer**: average review load for active reviewers.
## Code volume
Track **lines added** and **lines deleted** as activity context, not as a quality score.
Lines of code are a measure of activity, not productivity. A large refactor that deletes more
lines than it adds can be more valuable than a feature with thousands of new lines. Use code
volume as context alongside the other metrics, not as a standalone indicator.
## Team members table
The team members table includes per-developer delivery and review metrics:
| Column | Definition |
| ------------------------- | -------------------------------------------------------------------- |
| **PRs reviewed by cubic** | Merged PRs by this author that received a cubic AI review. |
| **Total cubic comments** | Number of review comments cubic posted on this author's PRs. |
| **Comments addressed** | Number of cubic comments the author subsequently fixed. |
| **Reviews given** | Number of PR reviews this developer submitted on other people's PRs. |
| **Avg review cycles** | Average number of review cycles for this author's merged PRs. |
| **Lines added** | Total lines of code added by this author. |
| **Lines deleted** | Total lines of code deleted by this author. |
Click column headers to sort. Use the search field to filter by GitHub username.
### CSV export
Click the download button above the table to export the current view as a CSV file. The export respects your active filters and time period selection. The filename includes the export date for easy tracking.
Use this export for lightweight reporting or trend tracking outside cubic.
## Tips for interpreting delivery metrics
* **Compare trends, not absolutes.**
* **Read metrics together to find bottlenecks.**
* **Large PRs naturally increase cycle times and review rounds.**
# Analytics
Source: https://docs.cubic.dev/analytics/overview
Track your team's AI adoption, code review performance, and delivery velocity.
The analytics dashboard shows how your team ships code across three lenses: AI coding usage, AI review impact, and delivery speed. Data updates automatically from your GitHub activity.
![Analytics dashboard overview]()
## Dashboard tabs
The [analytics page](https://www.cubic.dev/analytics) has three tabs:
* **[AI Coding](/analytics/ai-coding)**: Human vs AI authorship, tool/model usage, and team adoption by developer.
* **[AI Review](/analytics/ai-review)**: cubic's review volume, issues fixed, merge-time trend, and critical findings.
* **[Delivery and effectiveness](/analytics/delivery-and-effectiveness)**: review speed, cycle time, throughput, and delivery by team member.
Switch between tabs with keyboard shortcuts: press **c** (AI Coding), **a** (AI Review), or **d**
(Delivery and effectiveness).
## Filtering and time periods
### Repository filtering
Focus on specific repositories to understand performance at a granular level. Switch between individual repos or view aggregate data across all repositories in your organization.
![Repository filter]()
### Flexible time periods
cubic supports quick ranges plus custom dates:
* Last 24 hours
* Last 7 days
* Last 30 days
* All time
* Custom range
Available time periods depend on when you installed cubic. Data collection starts from your
installation date, so some longer periods may not be available initially.
### Period-over-period comparisons
Most metrics include automatic period-over-period comparisons when enough historical data is available.
![Metric comparison]()
Comparisons are hidden when the previous period has no data or falls before your installation date.
## What cubic tracks
cubic automatically collects metrics about:
* AI tool adoption and code authorship patterns
* Pull request activity and merge velocity
* Review times and feedback loops
* AI review effectiveness and issue resolution
* CLI review activity
* Team member contributions
We frequently add new metrics. [Contact us](mailto:contact@cubic.dev?subject=Requesting%20a%20new%20metric) with suggestions.
## Team performance metrics
![Team performance metrics]()
The [Delivery and effectiveness](/analytics/delivery-and-effectiveness) tab includes a team members table with per-developer metrics: PRs reviewed, comments addressed, review cycles, and lines of code changed. Click column headers to sort, and filter by GitHub username.
You can export team member data as CSV from both [AI coding](/analytics/ai-coding#csv-export) and [Delivery and effectiveness](/analytics/delivery-and-effectiveness#csv-export) for reporting and sharing with stakeholders.
# Codebase scans
Source: https://docs.cubic.dev/codebase-scan/codebase-scans
Run thousands of agents that find validated bugs and vulnerabilities across your repository.
Codebase scans deploy thousands of AI agents to find bugs and vulnerabilities across your repository. They complement PR reviews: PR reviews check new diffs quickly, while scans inspect the wider codebase for serious bugs, security vulnerabilities, data integrity risks, and edge cases.
cubic validates each potential issue before reporting it, then helps you route, ticket, or fix the findings. Scans run in the background and separately from synchronous PR reviews, so your PR workflow stays fast.
Even with AI reviews on every PR, much of your codebase may have been written before you had review coverage, or reviewed years ago under different standards.
The first scan audits the repository. Later scheduled scans focus on changes since the last successful scan, so you get continuous coverage without starting from scratch every time.
Scans take hours, sometimes 24+ for large codebases, because agents verify findings across files and context before reporting them. You can keep working while they run.
## The overnight workflow
1. You start a scan at the end of the day, or a scheduled scan starts automatically
2. cubic scans in the background, often for 6 to 12 hours
3. You wake up to validated findings and, optionally, auto-created fix PRs with reviewers assigned
4. Review the results, tickets, or PRs in the morning
Codebase scans are in beta and are available by request.
![Codebase scan results table]()
## What you get
* **Validated findings with evidence:** agents focus on serious issues and investigate each potential finding before it shows up in your results.
* **Issue ownership + routing:** each finding is attributed to an issue owner so it lands with the right person or team.
* **Learns from your team:** scans apply [learnings from PR reviews](/ai-review/memory-and-learning), and you can steer scans with custom instructions and triage feedback.
* **Clear next steps:** fix issues with cubic, open them in Cursor, create Jira, Linear, or GitHub tickets, or notify owners in Slack or email.
* **Automation when you want it:** enable automatic issue creation or auto remediation for findings that match your guardrails.
## Issues that codebase scans find
Codebase scans focus on high impact issues:
* **Business logic flaws**: billing edge cases that lose money, incorrect permission checks, broken invariants, off by one errors
* **Data integrity risks**: race conditions that corrupt state, missing validations, unsafe database operations
* **Edge cases**: null pointer exceptions, unhandled error paths, boundary conditions that break functionality
* **Secret scanning**: hardcoded API keys, credentials, tokens, and other secrets that should not be in your codebase
* **Vulnerability scanning**: known CVEs in your dependencies, unsafe version ranges, and security advisories
* **Infrastructure as Code scanning**: misconfigurations in Terraform, Kubernetes manifests, Dockerfiles, and CloudFormation templates
* **Security vulnerabilities**: authentication bypasses, injection points, insecure configurations
Unlike traditional scanners that flood you with noise, every finding is investigated by AI agents before being reported. This means you see only actionable issues, not a backlog of false positives to triage.
## How it works
cubic clones your repository into an isolated sandbox and runs thousands of parallel AI agents plus static analysis across the codebase.
These agents:
* Navigate across files to trace data flows
* Follow call chains to verify issues
* Check external documentation (framework docs, security advisories)
* Access up-to-date documentation for the libraries and frameworks in your stack
* Apply [learnings from PR reviews](/ai-review/memory-and-learning) (feedback from your team, senior reviewers, and prior corrections) so scans reflect your codebase's standards
* Test multiple hypotheses before confirming findings
* Use your repository's [AI Wiki](/wiki/ai-wiki) to understand product context and prioritize investigations
The scan process:
1. Maps your repository structure
2. Checks for an up-to-date [AI Wiki](/wiki/ai-wiki). If one doesn't exist, cubic generates it automatically
3. Runs parallel checks informed by the wiki's understanding of your product
4. Investigates suspicious patterns before reporting them
5. Deduplicates overlapping findings
6. Scores confirmed issues by severity and confidence
This takes hours because agents verify each finding across files and external sources. The result is validated issues you can immediately act on.
### First scan vs continuous scans
Your first scan audits the repository broadly. After that, scheduled scans are continuous: they focus on what changed since the last successful scan.
If there are no changes to scan, cubic can skip the scheduled run automatically.
## Why findings are actionable
Traditional static analysis tools are notorious for false positives. That includes security scanners, dependency scanners, secret scanners, and rule based linters. Teams report that up to 90% of findings can turn out to be non issues when investigated in context.
cubic takes a different approach. Instead of pattern matching and dumping results, AI agents investigate each potential issue:
* **Contextual analysis**: Agents assess whether a finding is real and impactful in your specific codebase
* **Cross reference verification**: Findings are validated against actual code paths, not just syntactic patterns
* **Severity scoring**: Only issues that pass investigation are reported, with confidence scores based on evidence
The result: high signal findings you can act on immediately, not another backlog to triage.
## Starting a scan
Once codebase scans are enabled:
1. Navigate to your repository's **Codebase scan** page
2. Click **Start scan**
3. Continue working. Scans run in the background
Start a scan before leaving for the day, then review results (and fix PRs) in the morning.
## Working with results
Every finding appears in a sortable, filterable table:
* **Issue**: summary of what's wrong, plus file path and line number
* **Category**: Security, Business logic, Data integrity, or Stability
* **Owner**: the issue owner, the person or team that should own the fix
* **Risk**: a combined score (severity + reachability + likelihood)
* **Fix effort**: estimated difficulty to fix (1 to 10)
* **Status**: Open, In review, Resolved, False positive, Won't fix, Intended Behavior, or Accepted risk
Filter by status, category, or owner. Sort by any column.
### Owner attribution
cubic automatically identifies who's responsible for each finding using your repository's **CODEOWNERS file**. This lets you route issues to the right team, for example `@frontend-team`, `@security`, or a specific engineer.
If your repository has a CODEOWNERS file (in the root, `.github/`, or `docs/` directory), cubic uses it to determine ownership. If no CODEOWNERS match exists, cubic falls back to git history attribution.
This is especially useful for large codebases where different teams own different parts of the code. Filter by owner to see only your team's issues, or export filtered results to share with specific teams.
### Notify issue owners
You can notify owners when scans find issues in their code, via:
* Email notifications
* Slack DM notifications (when Slack is connected)
### Auto resolution
Scan violations don't just sit there forever. When a PR is merged that fixes a scan finding, whether intentionally or as a side effect of other work, cubic automatically detects the resolution and marks the violation as resolved.
Here's what happens:
1. A PR merges into your default branch
2. cubic checks the merged diff against any open scan violations in the affected files
3. AI agents analyze whether the code change actually fixes each issue
4. Resolved violations are marked with an audit trail: which PR fixed it, which commit, and an AI generated explanation of how the fix addresses the original finding
This means your scan results stay current without manual triage. Issues that your team fixes through normal development work are automatically cleared, so your open violations list always reflects what's actually still a problem.
You can also link a fix PR manually from the issue drawer:
* Open the violation
* Click the **More actions** menu (`⋮`)
* Select **Link fix PR** and paste a PR number or a GitHub PR URL
Click any issue for:
* Full explanation with code context
* **AI sidebar** to explore the finding interactively
* **Copy prompt** button for a ready to paste fix prompt
* **Create Jira/Linear tickets** to track remediation work
![Codebase scan issue details]()
## Ways to act on findings
Scan findings do not have to sit in a dashboard. You can turn them into PRs, tickets, prompts, or owner notifications.
* **Fix with cubic:** creates fix PRs for selected findings.
* **Open in Cursor:** opens Cursor with a prefilled fix prompt for selected findings.
* **Create tickets:** sends findings to Linear, Jira, or GitHub Issues.
* **Notify owners:** sends email or Slack notifications to the issue owner.
* **Auto remediation:** automatically creates PRs for findings that match your guardrails.
* **Automatic issue creation:** automatically creates Linear, Jira, or GitHub tickets after scans complete.
### Fix with cubic
Use **Fix with cubic** when you want cubic to create PRs for selected findings.
1. Use the checkboxes to select issues in the results table
2. Click **Fix with cubic** in the bulk actions bar
3. cubic spins up background agents that investigate each issue, then create PRs with fixes
Each issue gets its own PR, so you can review and merge them independently. The fixes run in parallel in the background. You can close the tab and come back later.
You can also fix issues one at a time from the issue details panel. Click any issue, then click **Fix with cubic** in the toolbar.
### Open in Cursor
Select findings in the results table, then choose **Open in Cursor** from the bulk actions bar to open Cursor with a prefilled prompt containing the issue summary, analysis, and relevant code context.
### Create Jira, Linear, or GitHub tickets
If your repo is connected to [Jira](/integrations/jira-integration) or [Linear](/integrations/linear-integration), or you enabled [GitHub Issues](/integrations/github-issues-integration), you can create tickets directly from a finding.
GitHub issues are created in the scanned repository, and only when that repository is private, so findings are never disclosed publicly.
### Automatic issue creation
Enable **Issue creation** in the repository's codebase scan configuration when you want scan results to land directly in your team's backlog.
When enabled, cubic:
* Creates issues only for findings that meet your minimum risk score
* Filters by the categories you selected
* Routes issues to your configured Linear team, Jira project and issue type, or the scanned repository for GitHub
* Respects your **Max issues per day** limit
* Skips findings that are already linked or no longer open
### Auto remediation
Auto remediation creates PRs for your highest risk violations without manual selection.
When a scan completes, cubic evaluates each violation against your configured guardrails (risk, confidence, category, max fix difficulty) and triggers fixes for eligible issues. PRs are created in the background, with reviewers automatically assigned based on your settings.
## Scheduling scans
Most teams run scans on a biweekly, daily, or monthly cadence:
* **Biweekly scans:** the default cadence for steady coverage without scanning every week
* **Daily scans:** best for fast-moving repos that want continuous coverage
* **Monthly scans:** a lightweight option for steady repos
* **On demand scans:** before major releases, after architecture changes, post dependency updates
To schedule recurring scans, go to your repository's **Codebase scan** page and configure the schedule dropdown.
## Custom instructions
Guide what cubic focuses on during scans. Custom instructions let you define **security invariants**, baseline policies that should always hold true in your codebase.
**Security & compliance examples:**
* "All traffic must be encrypted, flag any HTTP endpoints without TLS"
* "Storage in infrastructure as code must have encryption enabled"
* "All user input must pass through our `sanitize()` function before database queries"
* "Authentication tokens must never be logged or exposed in error messages"
**Focus & context examples:**
* "Focus on authentication flows and payment processing"
* "We use a custom ORM that wraps Prisma, account for this in SQL injection checks"
* "Our `validatePermissions()` helper is the authoritative access control check"
**To configure:**
1. Go to your repository's **Codebase scan** page
2. Click the schedule dropdown, then **Custom instructions**
3. Enter your instructions (up to 10,000 characters)
4. Save
Your instructions apply to all scans, both manual and scheduled. This is especially valuable for compliance teams who need to enforce specific security requirements across the codebase without writing unit tests for each policy.
***
## FAQ
Open your repository's **Codebase scan** page and set a schedule using the schedule dropdown.
After the first scan, scheduled scans check changes since the last successful scan and update
the existing results. Opening a completed scan shows its results; it does not start a new run.
Contact [support](/account/support) if you need an additional scan immediately.
No. Codebase scans have separate limits and do not consume the reviewed lines included in your
PR review plan. See [AI review usage](/account/ai-review-usage#faq).
Traditional SAST tools use pattern matching rules that generate massive false positive rates. Teams report up to 90% of findings are non issues. cubic is fundamentally different in two ways:
**1. Exploitability analysis**: Instead of just flagging patterns, AI agents trace code paths to verify whether each finding is actually reachable and exploitable. Dependency vulnerabilities are only reported when the vulnerable code path is called. CVEs are assessed for real world impact, not just version matching.
**2. Business logic bugs**: SAST tools can only find what rules exist for, SQL injection, XSS, etc. cubic finds issues that pattern matching fundamentally cannot detect: billing edge cases that lose money, broken permission checks, race conditions, incorrect state transitions, and other logic flaws specific to your codebase.
No. PR reviews remain fast and inline. Scans run completely separately in the background.
Very high signal to noise ratio. Unlike traditional scanners that flood you with false positives, every finding is validated by AI agents before being reported. Teams report immediately actionable results without the triage burden.
Small repos: 2 to 6 hours. Medium: 6 to 12 hours. Large enterprise codebases: 24 to 48 hours. You get progress updates throughout.
For many teams, yes. cubic covers static code analysis (SQL injection, XSS, auth bypasses), dependency vulnerability scanning with exploitability analysis, secret detection, and infrastructure as code scanning. The key advantage is that cubic validates whether vulnerabilities are actually reachable and exploitable, not just pattern matching on version numbers. Teams using traditional scanners often report 90%+ false positive rates; cubic's validation approach eliminates that triage burden. You may still want specialized tools for dynamic scanning, malware detection in dependencies, or SBOM generation.
Scans are included in your cubic subscription. Pro includes scans for up to 3 repositories in a rolling 90-day window. A repository counts toward that limit if scheduled scans are enabled for it, or if it has had a pending, running, or completed scan in the last 90 days.
Usage is also subject to fair use to keep background scanning reliable for everyone.
# Configure with cubic.yaml
Source: https://docs.cubic.dev/configure/cubic-yaml
Version-control your AI review settings with a single YAML file in each repository.
## Repository configuration
`cubic.yaml` lives in the root of your repository and becomes the source of truth for AI review behavior, ignore patterns, PR descriptions, and custom agents. Commit the file, open a PR, and cubic automatically applies those settings to every future review.
## Organization configuration
You can also manage cubic settings for your entire organization from a single repository. Create a repository named `cubic-config` in your organization and add a `cubic.yaml` file to the root directory. cubic automatically applies these settings to any repository that doesn't have its own configuration.
Organization configuration uses the same schema as repository configuration, including auto-approve settings such as `reviews.auto_approve_behavior`, `reviews.auto_approve`, and `reviews.auto_approve_custom_prompt`.
You must add the `cubic-config` repository to your cubic installation. cubic needs access to read the configuration file.
Individual repositories can still override organization settings by adding their own `cubic.yaml` file. The `cubic-config` repository itself is always treated as organization configuration. Its `cubic.yaml` is never interpreted as a repo-level override.
## Branches
cubic reads configuration only from the default branch:
* For repository configuration, this is the default branch of that repository.
* For organization configuration, this is the default branch of the `cubic-config` repository.
cubic does not read configuration from feature branches. Changes are picked up automatically when you push to the default branch.
## Configuration hierarchy
cubic checks for configuration in this priority order:
| Priority | Source | Description |
| ----------- | ------------------------- | --------------------------------------------------------- |
| 1 (Highest) | Repository `cubic.yaml` | Settings defined in the repository root |
| 2 | Organization `cubic.yaml` | Settings from `{org}/cubic-config` repository |
| 3 | UI settings | Per-repository settings configured in the cubic dashboard |
| 4 (Lowest) | Defaults | Built-in cubic defaults |
UI settings are stored per-repository. The "All repositories" option in the dashboard applies changes to all **existing** repositories at once, but new repositories start with built-in defaults. Use organization `cubic.yaml` to ensure consistent defaults across all repositories, including new ones.
### Merging behavior
Partial YAML is supported at every level. Any field you set overrides lower-priority sources. Anything you leave out falls through to the next level.
When both repository and organization YAML exist, cubic **merges** them:
* The organization config acts as a base
* Repository settings override organization settings field-by-field
* Settings not defined in the repository YAML inherit from organization YAML
* Custom agents are **additive**: repository agents come first, then organization agents fill remaining slots
This allows you to define organization-wide defaults in the organization config while letting repositories customize specific settings.
To opt out of custom agents defined in organization config entirely, set `custom_rules: []` in your repository config. This explicitly clears inherited agents rather than adding to them.
**Organization config** (`cubic-config/cubic.yaml`):
```yaml theme={null}
version: 1
reviews:
enabled: true
sensitivity: high
custom_instructions: "Outline any project-specific guidance you want included in reviews."
custom_rules:
- name: No console logs in production
description: Ensure that console.log statements are removed before merging. These should not be present in production code to prevent leaking sensitive information and to improve performance.
```
**Repository config** (`my-repo/cubic.yaml`):
```yaml theme={null}
version: 1
reviews:
sensitivity: low # Override org's "high"
custom_rules:
- name: API validation
description: Check API contracts
- name: React style guide
file_paths:
- docs/react-style-guide.md
- docs/component-rules.md
```
**Effective config** (what cubic uses):
* `enabled: true` — inherited from organization
* `sensitivity: low` — overridden by repository
* `custom_instructions: "Outline any project-specific guidance..."` — inherited from organization
* Custom agents: "API validation" and "React style guide" (from repo), then "No console logs" (from organization)
### Error handling
Validation errors do not block reviews. If the YAML has an issue, cubic falls back to UI settings and shows the exact error on the AI review settings page so you can fix it on your next commit. Note that an invalid repository `cubic.yaml` falls back to UI settings, not to organization configuration—this keeps failure modes predictable.
## Exporting current UI settings
If you've already configured AI review settings in the UI, you can export them as a `cubic.yaml` file instead of creating one manually.
1. Go to the [AI review settings page](/ai-review/ai-review-settings) and select a repository.
2. In the tabs area at the top, you'll see two buttons:
* **Copy button:** Copies the YAML configuration to your clipboard
* **Download button:** Downloads a `cubic.yaml` file with your current settings
3. Paste the copied content or use the downloaded file as a starting point for your repository configuration.
The exported YAML includes all your current UI settings. You can then commit this file to your repository root and customize it as needed.
![Export Yaml Buttons Pn]()
## Template `cubic.yaml`
Copy this template into the root of your repository to get started, then delete any sections you don’t need to customize.
```yaml theme={null}
# yaml-language-server: $schema=https://cubic.dev/schema/cubic-repository-config.schema.json
version: 1
# Review settings control AI review behavior.
reviews:
enabled: true
sensitivity: medium
incremental_commits: true
check_drafts: false
architecture_diagrams: false
external_contributors_require_manual_review: false
resolve_threads_when_addressed: true
auto_approve_behavior: disabled
auto_approve: disabled
auto_approve_custom_prompt: |
Approve only documentation, test, and configuration changes.
auto_approve_rules:
exclude_external_contributors: false
allow_open_issues: none # none | p3 | p2_and_p3 | p1_to_p3 | all
exclude:
- '**/migrations/**'
- infra/**
only_files:
- docs/**
# PR metadata gates. exclude_* blocks on any match, only_* is an allowlist.
exclude_labels:
- do-not-auto-approve
only_authors:
- renovate[bot]
- dependabot[bot]
only_base_branches:
- main
# Master switch: automatic triggers below only fire when this is `automatic`.
ultrareview: manual # disabled | manual | automatic
auto_ultrareview: disabled
auto_ultrareview_custom_prompt: |
Run an ultrareview when auth or payment flows change.
# When ultrareview is automatic, file patterns trigger even when auto_ultrareview is disabled —
# remove this list entirely to fully turn auto-trigger off.
auto_ultrareview_file_patterns:
- '**/migrations/**'
custom_instructions: |
Outline any project-specific guidance you want included in reviews.
# Optional ignore filters; PR filters suppress automatic reviews when they match.
ignore:
files:
- path/to/generated/**
head_branches:
- wip/*
pr_labels:
- skip-review
max_changed_lines: 5000
# Optional YAML-defined custom agents.
custom_rules:
- name: Example rule
description: Describe what this rule should flag.
# include/exclude lists are optional—delete them to apply everywhere.
include:
- src/**
exclude:
- src/**/*.test.*
- name: Enforce style guide
description: Enforce the repository style guide.
file_paths:
- docs/style-guide.md
- docs/review-rules.md
pr_descriptions:
generate: true
instructions: |
Add reminders or release notes here.
# Issues block (delete if you don't use PR comment fixes or "Fix with cubic" buttons).
issues:
fix_with_cubic_buttons: true
pr_comment_fixes: true
fix_commits_to_pr: true
auto_fix_sign_commits: false
coding_agent_provider: cubic # cubic | cursor_cloud_agent
```
1. Create the file at the repo root.
2. Commit it to a branch and open a PR.
3. Watch the AI review settings page or PR timeline for validation errors or warnings.
See the [AI review settings page](/ai-review/ai-review-settings) for the UI view of these values.
## IDE validation
Editors such as VS Code, Cursor, and JetBrains detect the `# yaml-language-server: $schema=…` directive at the top of `cubic.yaml`. Keep that line (or add it yourself) and the editor downloads [`https://cubic.dev/schema/cubic-repository-config.schema.json`](https://cubic.dev/schema/cubic-repository-config.schema.json) to validate the file structure and surface inline errors before you commit.
## Configuration reference
| Key | Required | Purpose |
| ----------------- | -------- | ----------------------------------------------------------------- |
| `version` | Yes | Schema version. Must be `1`. |
| `reviews` | No | Mirrors AI review settings and lets you define custom agents. |
| `pr_descriptions` | No | Controls AI-authored PR summaries and optional instructions. |
| `issues` | No | Controls "Fix with cubic" buttons and PR comment-requested fixes. |
If you add a top-level key cubic doesn’t recognize yet, the value is ignored and an `unknown_top_level_key` warning appears on the [AI review settings page](/ai-review/ai-review-settings) so you know it had no effect.
## Reviews section
Set `reviews.senior_reviewers` to GitHub usernames (without `@`) to choose whose review patterns cubic learns from:
```yaml theme={null}
version: 1
reviews:
senior_reviewers: [alice, bob]
```
Repository YAML replaces the organization YAML list. YAML selections override dashboard selections and appear read-only in the dashboard with their YAML source. Omit the field to inherit defaults, or use `senior_reviewers: []` to stop learning from senior reviewers in that scope. Existing learnings are retained.
Pushing a configuration with senior reviewers to the default branch queues historical learning through the same one-hour debounce used for organization reviewer changes. Subsequent learning runs read the current YAML configuration. Exporting dashboard settings includes the saved reviewer selection.
### Core options
| Field | Description |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Master toggle for AI reviews on the repository. |
| `senior_reviewers` | Up to five GitHub usernames to learn review patterns from, matching the dashboard limit. An empty list disables senior reviewer learning. |
| `sensitivity` | `low`, `medium`, or `high`—controls how picky the AI is about surfacing issues. |
| `incremental_commits` | `true` automatically reviews new commits pushed to open PRs (only new issues are posted); `false` skips automatic incremental reviews. Manual requests with `@cubic-dev-ai incremental review` work with either value. Default: `true`. |
| `check_drafts` | `true` reviews draft PRs immediately when opened; `false` skips them. Default: `false`. |
| `architecture_diagrams` | `true` includes AI-generated architecture diagrams in review summaries; `false` skips them. Default: `false`. |
| `external_contributors_require_manual_review` | `true` skips automatic reviews for public-repository PRs from external contributors until a trusted installation member manually triggers one. Default: `false`. |
| `resolve_threads_when_addressed` | `true` automatically resolves GitHub threads when cubic detects an issue has been addressed; `false` only updates the comment. Default: `true`. |
| `auto_approve_behavior` | Controls whether auto-approval is disabled, simulated in `shadow` mode, or submitted live to GitHub. Values: `disabled`, `shadow`, `live`. |
| `auto_approve` | Controls when cubic approves clean reviews. Values: `disabled`, `always`, `low_risk_only`, `custom`. |
| `auto_approve_custom_prompt` | Custom approval criteria. cubic only uses this field when `auto_approve` is `custom`. |
| `auto_approve_rules.exclude` | File or directory globs that block auto-approval. If any changed file in a PR matches, cubic will not auto-approve that PR. |
| `auto_approve_rules.only_files` | File or directory globs that allow auto-approval. Every current and previous changed path must match at least one glob. Never-auto-approve rules take precedence. |
| `auto_approve_rules.exclude_external_contributors` | `true` keeps reviewing public-repository PRs from external contributors, but prevents cubic from auto-approving them. Default: `false`. |
| `auto_approve_rules.allow_open_issues` | Open cubic issues that don't block auto-approval, by priority. Values: `none`, `p3`, `p2_and_p3`, `p1_to_p3`, `all`. Issues without a recorded priority block unless `all`. See [Allow open issues](/ai-review/auto-approval#allow-open-issues). Default: `none`. |
| `auto_approve_rules.exclude_authors` / `only_authors` | Gate auto-approval on the PR author. `exclude_*` blocks any match; `only_*` is an allowlist. Logins match case-insensitively, and brackets are literal so both `renovate[bot]` and `*[bot]` work. |
| `auto_approve_rules.exclude_head_branches` / `only_head_branches` | Same gates on the PR source branch. |
| `auto_approve_rules.exclude_base_branches` / `only_base_branches` | Same gates on the branch the PR targets. |
| `auto_approve_rules.exclude_labels` / `only_labels` | Same gates on PR labels. Labels match exactly (case-insensitive) rather than as globs. |
| `auto_approve_rules.exclude_titles` / `only_titles` | Same gates on the PR title, matched as glob patterns. |
| `ultrareview` | Master switch for ultrareviews. `disabled` blocks all ultrareviews (manual and automatic), `manual` allows only manual triggers (default), `automatic` also enables the automatic triggers below. |
| `auto_ultrareview` | Controls when cubic auto-triggers an [ultrareview](/ai-review/ultrareview). Values: `disabled`, `high_risk_only`, `custom`. |
| `auto_ultrareview_custom_prompt` | Custom criteria describing which PRs warrant an ultrareview. cubic only uses this field when `auto_ultrareview` is `custom`. |
| `auto_ultrareview_file_patterns` | File or directory globs that always trigger an ultrareview. If any changed file in a PR matches, cubic runs an ultrareview. |
| `custom_instructions` | Free-form guidance for the reviewer. Whitespace is trimmed; empty strings clear the value. |
### Ignore filters
Ignore filters control when cubic skips running reviews. They map directly to the “Ignore patterns” controls in the [AI review settings UI](/ai-review/ai-review-settings). All lists accept glob strings, and duplicates/blank entries are dropped automatically. Pull request filters suppress automatic reviews; an explicit `@cubic-dev-ai review` request can still start a review on a matching PR. File filters continue to apply during manually requested reviews.
| YAML path | Effect |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reviews.ignore.files` | Skip matching files entirely (same syntax as `.gitignore`). |
| `reviews.ignore.head_branches` | Suppress automatic review based on the PR source branch. |
| `reviews.ignore.base_branches` | Suppress automatic review for PRs targeting specific branches. |
| `reviews.ignore.pr_labels` | Suppress automatic review when a PR label matches. Supports wildcards. |
| `reviews.ignore.pr_titles` | Suppress automatic review when the PR title matches a wildcard pattern. |
| `reviews.ignore.max_changed_lines` | Store a positive-integer automatic-review threshold (up to 2,147,483,647) for reviewable added plus deleted lines. cubic preserves values above 50,000 but applies an effective 50,000-line ceiling to every review. Manual triggers can bypass a lower configured threshold, but not the effective ceiling. |
### Common ignore recipes
Use labels or branch names to control when cubic jumps into a review.
#### Review agent PRs only when requested
Use a title prefix or branch namespace for agent-authored PRs. cubic will skip automatic reviews, including push-triggered incremental reviews, for matching PRs, while a teammate can request one when the PR is ready with `@cubic-dev-ai review`.
```yaml theme={null}
reviews:
ignore:
head_branches:
- 'agent/**'
pr_titles:
- 'no-auto-review:*'
```
`agent/**` matches nested branch paths such as `agent/batch/change`; `agent/*` only matches one path segment. The title prefix avoids bracket syntax, which glob matchers interpret specially.
#### Skip review with a label
The most common way to skip a review is by adding a specific label to your PR.
```yaml theme={null}
reviews:
ignore:
max_changed_lines: 5000
pr_labels:
- skip-review
- WIP
- draft
```
#### Skip entire categories of labels
You can use wildcards to ignore any label matching a pattern.
```yaml theme={null}
reviews:
ignore:
pr_labels:
- 'no-ai-*'
```
### Custom agents
* Each agent needs a `name` plus inline `description` text, an ordered `file_paths` list, or both. Optional `include`/`exclude` glob lists apply to both modes.
* Order matters. When you exceed the installation’s rule limit, only the first *N* agents take effect.
* Identical patterns are deduplicated. If an exclude matches an include, the exclude wins.
* Agents defined in YAML appear in the dashboard as read-only “Managed by cubic.yaml” entries so teammates can still see them. Learn more about how agents behave in the UI on the [Custom agents page](/ai-review/custom-agents).
* File-backed agents use repo-relative paths only. Absolute paths, globs, parent-directory traversal, directories, binary files, and unreadable files are rejected or surfaced as warnings.
* The description and file contents are concatenated in the order listed. cubic uses only the first 10,000 characters per custom agent; characters after that limit are not included in the review prompt.
* YAML and Markdown files referenced by file-backed agents are treated as plain text, not parsed as structured rule definitions.
* In organization config, `file_paths` entries are relative to each target repository, not to the `cubic-config` repository. The files must exist in every repository where the org-level agent should apply.
```yaml theme={null}
reviews:
custom_rules:
- name: Enforce style guide
description: Enforce the repository style guide.
file_paths:
- docs/style-guide.md
- docs/react.md
include:
- "src/**/*.tsx"
```
## PR descriptions
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `generate` | Toggle AI-authored PR descriptions. |
| `instructions` | Extra guidance for the summary. Only applied when `generate` is `true`; otherwise it is ignored with a warning. |
| `cubic_review_link` | Include a "Review in cubic" link. Default: `true`. |
| `skip_if_author_description` | Skip AI description generation on new PRs when the author already wrote a substantive description. Empty or template-only descriptions still get an AI description. Default: `false`. |
Some installations disable PR descriptions globally for compliance reasons. If that applies to you, the UI will show a warning even if the YAML enables the feature.
## Issues
| Field | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fix_with_cubic_buttons` | Enable or disable AI-generated “Fix with cubic” calls-to-action inside the issue UI. |
| `pr_comment_fixes` | Allow cubic to make code changes when someone asks for a fix in a PR comment thread. |
| `fix_commits_to_pr` | When `true`, fix commits are pushed directly to the PR branch instead of opening a new PR. |
| `auto_fix_sign_commits` | When `true`, cubic signs the commits it pushes so GitHub marks them as verified. This applies only to the `cubic` coding agent; the Cursor agent always signs its commits. |
| `coding_agent_provider` | Which coding agent applies automatic fixes: `cubic` (built-in agent) or `cursor_cloud_agent` (dispatches a Cursor cloud agent; requires Cursor configuration). |
# Connect cubic to your IDE
Source: https://docs.cubic.dev/ide/agent-setup
Install and connect cubic in Cursor, Claude Code, VS Code, Codex, Gemini CLI, or another coding tool.
Connect cubic's MCP server to your coding agent to read review findings and codebase context,
request PR reviews, and triage PR or codebase scan issues.
Use the exact endpoint `https://www.cubic.dev/api/mcp`. Some OAuth clients reject
`https://cubic.dev/api/mcp` because the protected resource origin does not match.
Add cubic to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project.
If the file already has servers, add the `cubic` entry inside its `mcpServers` object:
```json theme={null}
{
"mcpServers": {
"cubic": {
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
Open Cursor's MCP settings, connect cubic, and complete the browser sign-in flow.
Add this to `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
Run these commands from the project where you use Cursor Agent:
```bash theme={null}
agent mcp enable cubic
agent mcp login cubic
```
```bash theme={null}
agent mcp list-tools cubic
```
```bash theme={null}
claude mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
```
Open Claude Code and run:
```text theme={null}
/mcp
```
Choose cubic and complete the browser OAuth flow.
```bash theme={null}
claude mcp list
```
Install the cubic plugin to add skills and namespaced slash commands:
```text theme={null}
/plugin marketplace add mrge-io/skills
/plugin install cubic@cubic
```
```bash theme={null}
codex mcp add cubic --url https://www.cubic.dev/api/mcp
```
```bash theme={null}
codex mcp login cubic
```
```bash theme={null}
codex mcp list
```
```bash theme={null}
gemini mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
```
Open Gemini CLI and run:
```text theme={null}
/mcp auth cubic
```
```text theme={null}
/mcp
```
Add this to `~/.config/opencode/opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"cubic": {
"type": "remote",
"url": "https://www.cubic.dev/api/mcp",
"enabled": true
}
}
}
```
```bash theme={null}
opencode mcp auth cubic
```
```bash theme={null}
opencode mcp list
```
```bash theme={null}
droid mcp add cubic https://www.cubic.dev/api/mcp --type http
```
Open Droid, run `/mcp`, choose cubic, and complete the browser OAuth flow.
The `/mcp` panel should show cubic as connected.
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --to pi
```
The installer writes Pi's MCP config to `~/.config/mcp/mcp.json`.
```bash theme={null}
pi install npm:pi-mcp-adapter
```
Skip this step if `pi-mcp-adapter` is already installed.
The adapter reads `~/.config/mcp/mcp.json` automatically. Confirm the config contains:
```json theme={null}
{
"mcpServers": {
"cubic": {
"auth": "oauth",
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
```text theme={null}
/mcp-auth cubic
```
```text theme={null}
/mcp reconnect cubic
```
Open the Command Palette, run **MCP: Add Server**, choose HTTP, and enter:
```text theme={null}
https://www.cubic.dev/api/mcp
```
Name the server `cubic` and choose **Global** or **Workspace** for the configuration.
Run **MCP: List Servers**, start cubic, and complete OAuth when prompted.
Run **MCP: List Servers** and confirm cubic is running.
## What you can ask
Try "use cubic to show open review issues on this PR". The agent should retrieve the findings
with file locations and descriptions. See [MCP tools and examples](/ide/mcp-server#try-your-first-prompt)
for a prompt using an explicit PR URL.
* "start a cubic review of this PR"
* "list wiki pages for this repo"
* "what review learnings apply here?"
* "show scan findings with severity at least 7"
## Skills and slash commands
MCP gives your agent access to cubic tools. For agents that also support skills or slash commands, install those separately:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --skills-only
```
The installer detects supported agents in your home directory. Add `--to codex`, for example,
to choose one target. See [Skills](/ide/skills) for prerequisites, verification, and
[command names for each installation](/ide/skills#slash-commands).
To ask your agent to "review my code" locally, install and sign in to the [cubic
CLI](/ide/cli-review). MCP setup alone does not install the CLI.
# Local CLI review
Source: https://docs.cubic.dev/ide/cli-review
Run a fast local cubic AI code review from the command line before you push.
The **cubic CLI** reviews local changes before you push. It finds bugs and generates a prompt that your coding agent can use to fix them.
We recommend [connecting ChatGPT (Codex) or Claude Code](#bring-your-coding-subscription) for
access to more capable review models. You can also get started with cubic's included model.
Local reviews give you quick feedback while you work. Use GitHub PR review as the final pass:
it uses a different model and review pipeline for a more thorough review and may find issues
the CLI misses.
## Get started
### 1. Install the CLI
Install the cubic CLI for your operating system.
```bash theme={null}
curl -fsSL https://cubic.dev/install | bash
```
```powershell theme={null}
npx @cubic-dev-ai/cli install -g
```
### 2. Sign in
Open a terminal in your Git repository and run:
```bash theme={null}
cubic
```
The first launch opens your browser so you can sign in with your cubic.dev account. You can
also sign in explicitly with `cubic auth login`. If authentication fails, press `Ctrl+L` in the
CLI to log out and sign in again.
For CI and cloud agents, where no browser is available, use a personal API key instead. See
[Run in CI and cloud agents](#run-in-ci-and-cloud-agents).
![cubic CLI home screen showing review preset options]()
### 3. Run your first review
From your repository, run this command in your terminal to review uncommitted changes:
```bash theme={null}
cubic review
```
To review your branch against its base instead, run:
```bash theme={null}
cubic review -b
```
The CLI detects the base branch automatically. To choose one explicitly, use
`cubic review --base main`, replacing `main` with your base branch.
### 4. Use the findings
The CLI groups findings by priority. Fix the issues yourself or give the generated prompt to
your coding agent. Review the fixes, then run the review again to check them before you push.
After pushing, check cubic's GitHub review for additional findings.
![cubic CLI review results showing prioritized issues]()
The CLI syncs supported cubic cloud context, including [custom agents](/ai-review/custom-agents),
past feedback, and repository settings. CLI usage appears in your
[analytics dashboard](https://www.cubic.dev/analytics) as **CLI sessions**.
## Bring your coding subscription
Connect your existing **ChatGPT Plus/Pro** or **Claude Code** subscription to use its models
for local reviews. This is optional: cubic handles inference when you use the included model.
Connect your ChatGPT account to use Codex models with your existing plan:
```bash theme={null}
cubic auth connect codex
```
Sign in through the browser, then choose a Codex model in the CLI.
Connect your Claude Code account to use Claude models with your existing plan:
```bash theme={null}
cubic auth connect claude-code
```
Choose `opus` for the most thorough review, `sonnet` for everyday reviews, or `haiku` for speed.
cubic runs your local Claude Code as a subprocess and talks to it over the [Agent Client
Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol), the same pattern
[Zed](https://zed.dev/docs/ai/external-agents#claude-agent) uses for its Claude Agent. Your
Claude Code installation authenticates with Anthropic, makes every model call, and bills you
directly. cubic never sees, stores, or proxies your credentials, and does not call Claude's API,
use the Agent SDK, or offer Claude.ai login.
Reviews are interactive: you start each session and drive it from the UI. cubic does not run
autonomous loops in the background. This is the "ordinary use of Claude Code" that Anthropic's
[usage policy](https://code.claude.com/docs/en/legal-and-compliance) permits for Pro/Max
subscribers.
In the CLI, press `Ctrl+P` to choose a connected provider, then press `m` to choose a model.
You can switch without signing in again.
Run `cubic auth logout` to disconnect a provider. Disconnecting Claude Code from cubic does
not sign you out of Claude Code.
## Review with your coding agent
[Connect cubic to your IDE](/ide/agent-setup) and [install the skills](/ide/skills#install-skills),
then ask your coding agent to "review my code" to run a local review.
To include local review in your agent's workflow, add this to `AGENTS.md`, `CLAUDE.md`, or
`.cursorrules`:
```markdown theme={null}
## cubic review workflow
Before committing, run `cubic review` to review uncommitted changes.
Fix the validated issues and run the local review again.
Repeat until the local review is clean or only disputed issues remain.
After pushing, wait for cubic's GitHub review and check its comments.
Fix the validated issues and push the changes.
Use GitHub review as the final pass; it may find issues the local review misses.
```
## Command reference
Run `cubic review` without options to review uncommitted changes.
| Task | Command |
| -------------------------- | ----------------------------------------------- |
| Review uncommitted changes | `cubic review` |
| Compare with a base branch | `cubic review --base [branch]` (`-b`) |
| Review a specific commit | `cubic review --commit [` (`-c`) |
| Add custom instructions | `cubic review --prompt ""` (`-p`) |
| Return one JSON object | `cubic review --json` (`-j`) |
| Stream JSON events | `cubic review --output-format stream-json` |
Omit the branch from `--base` to detect it automatically. The `--base`, `--commit`, and `--prompt` options are mutually exclusive. Use `--output-format text`, `json`, or `stream-json` to select an output format explicitly.
### Output formats
The default text output shows human-readable findings with colored priority labels.
Run `cubic review --json` when an integration needs one JSON object after the review finishes.
Run `cubic review --output-format stream-json` when an agent, CI job, or integration needs progress
before the review finishes. The command writes compact NDJSON events to stdout, including finding
updates, retries, heartbeats, and a final `review.completed` or `review.failed` event.
## Run in CI and cloud agents
The CLI normally signs in through your browser. In CI and cloud agents there is no browser, so
authenticate with a personal API key instead. Requires cubic CLI v1.12 or later.
API keys are personal and grant the same access as your account, so each team member uses their
own key. Reviews require a seat on an active subscription.
Open [Settings > Integrations > cubic CLI](https://www.cubic.dev/settings?tab=integrations\&integration=cli)
and click **Generate API key**. Copy the key: it starts with `cbk_` and cubic shows the full
value only once.
This is the same personal key the [MCP server](/ide/mcp-server#advanced-api-key) uses.
Regenerating or revoking it replaces the key for your MCP clients and CI at the same time.
Add the key to your CI or cloud environment as a secret named `CUBIC_API_KEY`. When the
variable is set, the CLI uses it and skips the browser sign-in.
```bash theme={null}
cubic review --base main --json
```
Use `--output-format stream-json` instead of `--json` when the job needs progress events
before the review finishes. `cubic review` exits with code 1 when it reports findings, so a
CI step fails on findings; append `|| true` to publish them without failing the job.
1. In the Cursor dashboard, open the **Secrets** tab for your cloud agent environment and add
`CUBIC_API_KEY`.
2. Install the CLI in the environment's install command in `.cursor/environment.json`:
```json theme={null}
{
"install": "curl -fsSL https://cubic.dev/install | CUBIC_INSTALL_DIR=/usr/local/bin bash"
}
```
3. The agent, or you over the VM shell, can then run `cubic review --json`.
1. In the cloud environment dialog, add `CUBIC_API_KEY=cbk_...` under **Environment variables**.
2. Set the setup script to install the CLI:
```bash theme={null}
CUBIC_DISABLE_GIT_AI=true npm i -g @cubic-dev-ai/cli
```
3. Set **Network access** to **Custom**, allow `www.cubic.dev`, `cubic.dev`, and
`mcafvrhahbqdwfrtncql.supabase.co`, and keep the default package-manager list ticked so `npm`
can install the CLI. If the environment does not ship ripgrep (`rg`), also allow `github.com`
and the GitHub release-asset hosts `release-assets.githubusercontent.com` and
`objects.githubusercontent.com`: the CLI downloads ripgrep from GitHub releases on its first
run, and the download redirects to one of those hosts.
Environment variables are visible to everyone who uses that environment. Because keys are
personal, keep the environment to yourself or have each teammate create their own.
Export the key in any headless shell, such as a container or a remote VM:
```bash theme={null}
export CUBIC_API_KEY=cbk_...
cubic review --json
```
In PowerShell:
```powershell theme={null}
$env:CUBIC_API_KEY = "cbk_..."
cubic review --json
```
Recommended environment variables for headless runs:
* `CUBIC_DISABLE_AUTOUPDATE=1` skips the npm registry version check and the binary download from
cubic's release storage.
* `CUBIC_DISABLE_LSP_DOWNLOAD=1` skips downloading language servers from GitHub.
* `CUBIC_DISABLE_GIT_AI=true` at install time skips the git-ai installer, which downloads from
GitHub releases and starts a background daemon on the runner.
### Revocation and limits
Revoke or regenerate the key from the same settings page. CI jobs that use a revoked key stop
immediately. API key traffic is rate limited per user: 300 requests per 15 minutes for session,
config, and settings calls, and 2,000 requests per 15 minutes for model calls. This comfortably
covers a few parallel CI jobs.
## Advanced settings
The CLI checks for a newer version in the background whenever you run a command. When an update is
available, the CLI installs it before running the command.
Run `cubic upgrade` to update immediately, or `cubic upgrade ` to install a specific
version.
Add `disable_auto_updates` to `~/.config/cubic/config.json` to receive update notifications without
installing them automatically:
```json theme={null}
{
"disable_auto_updates": true
}
```
Set `CUBIC_DISABLE_AUTOUPDATE=1` to skip both the update check and automatic installation:
```bash theme={null}
export CUBIC_DISABLE_AUTOUPDATE=1
```
This environment variable is useful in CI, on machines without outbound internet, or when you
need to pin a version.
The CLI installs [git-ai](https://usegitai.com) to tag AI-assisted commits with git notes. These
notes power the [AI coding analytics](/analytics/ai-coding) dashboard. Attribution tracking is
enabled by default, and git-ai shows an AI-versus-human authorship summary after each commit.
Set `CUBIC_DISABLE_GIT_AI` during installation to skip git-ai:
```bash theme={null}
curl -fsSL https://cubic.dev/install | env CUBIC_DISABLE_GIT_AI=true bash
```
```powershell theme={null}
$env:CUBIC_DISABLE_GIT_AI = "true"
npx @cubic-dev-ai/cli install -g
```
```cmd theme={null}
set CUBIC_DISABLE_GIT_AI=true
npx @cubic-dev-ai/cli install -g
```
Manage tracking after installation with `cubic stats`:
```bash theme={null}
cubic stats status
cubic stats disable
cubic stats enable
```
`cubic stats disable` removes git-ai hooks and preserves your preference during future upgrades.
`cubic stats enable` reinstalls git-ai and clears the opt-out preference.
## Limitations
CLI usage is unlimited during alpha, subject to rate limits that ensure fair access.
* API key requests are rate limited per user; see
[Revocation and limits](#revocation-and-limits). Spread larger CI fleets across team members'
own keys.
# MCP server
Source: https://docs.cubic.dev/ide/mcp-server
Connect your coding agent to cubic reviews, documentation, scans, billing, and team management.
cubic's MCP server lets your coding agent read review findings, look up codebase documentation,
request PR reviews, triage PR or codebase scan issues, and manage billing and team access.
You can use these tools directly from your agent. [Skills](/ide/skills) add workflows for tasks
such as fixing review comments. To review changes in your local checkout, use the
[cubic CLI](/ide/cli-review).
Sign in with your cubic account. Repository tools require access to the repository's installation.
Billing and team tools check your access to the requested organization. Connecting MCP does not
grant access to additional organizations or repositories.
## Endpoint
Use this exact URL:
```text theme={null}
https://www.cubic.dev/api/mcp
```
Some MCP clients compare the protected resource URL exactly. Use `https://www.cubic.dev/api/mcp`,
not `https://cubic.dev/api/mcp`.
## Authentication
Use OAuth for new MCP connections. Your MCP client opens a browser, you approve cubic access, and the client stores and refreshes tokens.
OAuth is the recommended path and needs no `Authorization` header or API key in your configuration.
### Advanced: API key
For scripts, CI, or MCP clients that cannot complete an OAuth flow, you can use a personal API key instead. Open [Settings > Integrations > MCP](https://www.cubic.dev/settings?tab=integrations\&integration=mcp), expand **API key**, and click **Generate API key**. Keys start with `cbk_` and cubic only shows the full value once.
Send the key as a bearer token in the `Authorization` header and skip your client's OAuth login step:
```json theme={null}
{
"mcpServers": {
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp",
"headers": {
"Authorization": "Bearer cbk_..."
}
}
}
}
```
API keys are personal and grant the same access as the user who created them. Each team member should generate their own key, and you can revoke or regenerate it from the same settings page at any time. The same personal key also authenticates the [cubic CLI in CI and cloud agents](/ide/cli-review#run-in-ci-and-cloud-agents), and regenerating it replaces the key for both.
## Install and log in
Cursor and VS Code support one-click MCP install links. For other clients, use the CLI or manual config steps below.
1. Click [Add cubic to Cursor](https://cursor.com/en-US/install-mcp?name=cubic\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vd3d3LmN1YmljLmRldi9hcGkvbWNwIn0%3D).
2. Confirm the install in Cursor.
3. Click **Connect** and complete OAuth.
Manual fallback:
Add cubic to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project.
If the file already has servers, add the `cubic` entry inside its `mcpServers` object:
```json theme={null}
{
"mcpServers": {
"cubic": {
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
Open Cursor's MCP settings, connect cubic, and complete the browser sign-in flow.
If Cursor IDE is installed, first click [Add cubic to Cursor](https://cursor.com/en-US/install-mcp?name=cubic\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vd3d3LmN1YmljLmRldi9hcGkvbWNwIn0%3D). Cursor Agent reads the same MCP config.
Manual fallback:
Add cubic to `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
```bash theme={null}
agent mcp enable cubic
agent mcp login cubic
agent mcp list-tools cubic
```
1. Click [Add cubic to VS Code](vscode:mcp/install?%7B%22name%22%3A%22cubic%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.cubic.dev%2Fapi%2Fmcp%22%7D).
2. Confirm the MCP install in VS Code.
3. Complete the OAuth prompt.
4. Run **MCP: List Servers** and confirm cubic is running.
Manual fallback:
1. Open the Command Palette.
2. Run **MCP: Add Server**.
3. Choose **HTTP**.
4. Enter `https://www.cubic.dev/api/mcp`.
5. Name it `cubic`.
6. Choose **Global** or **Workspace** for the configuration.
7. Run **MCP: List Servers**, start cubic, and complete OAuth when prompted.
Notion MCP connections are available on Notion Business and Enterprise plans. A workspace admin
must enable custom MCP servers before an agent can connect to cubic.
1. Ask a workspace admin to open **Settings** > **Connections** > **Manage** and turn on **Enable custom MCP servers**. If connections are restricted, the admin also needs to approve cubic's MCP URL.
2. Open your Custom Agent's **Settings**.
3. Go to **Tools & Access**.
4. Click **Add connection** > **Custom MCP server**.
5. Enter `https://www.cubic.dev/api/mcp`.
6. Name the connection `cubic`.
7. Connect with OAuth and complete the cubic sign-in flow.
8. Select which cubic tools the agent can use.
Read tools such as `list_wikis`, `get_wiki_page`, `list_scans`, and `get_pr_issues` can run
automatically if that matches your agent workflow.
See [Notion's MCP setup guide](https://www.notion.com/help/mcp-connections-for-custom-agents)
for workspace connection settings.
```bash theme={null}
claude mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
```
Open Claude Code and run:
```text theme={null}
/mcp
```
Choose cubic and complete the browser OAuth flow.
Run `claude mcp list` in your terminal to check the connection.
Add the server, sign in through your browser, then list configured servers:
```bash theme={null}
codex mcp add cubic --url https://www.cubic.dev/api/mcp
codex mcp login cubic
codex mcp list
```
```bash theme={null}
gemini mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
```
Open Gemini CLI and run:
```text theme={null}
/mcp auth cubic
/mcp
```
Add this to `~/.config/opencode/opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"cubic": {
"type": "remote",
"url": "https://www.cubic.dev/api/mcp",
"enabled": true
}
}
}
```
Then authenticate and verify:
```bash theme={null}
opencode mcp auth cubic
opencode mcp list
```
```bash theme={null}
droid mcp add cubic https://www.cubic.dev/api/mcp --type http
```
Open Droid, run `/mcp`, choose cubic, and complete the browser OAuth flow.
Install cubic's Pi target:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --to pi
```
The installer writes Pi's MCP config to `~/.config/mcp/mcp.json`.
Install the Pi MCP adapter if it is not already installed:
```bash theme={null}
pi install npm:pi-mcp-adapter
```
The adapter reads `~/.config/mcp/mcp.json` automatically. Confirm the config contains:
```json theme={null}
{
"mcpServers": {
"cubic": {
"auth": "oauth",
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
Open Pi and run:
```text theme={null}
/mcp-auth cubic
/mcp reconnect cubic
```
Use these details for any hosted MCP client that supports remote MCP OAuth and dynamic client
registration.
```text theme={null}
Transport: Streamable HTTP
URL: https://www.cubic.dev/api/mcp
Authentication: OAuth
```
Your client should open a browser for cubic consent, store the returned tokens, and send the
OAuth access token as a bearer token when calling the MCP endpoint.
## Try your first prompt
After connecting, ask your agent:
```text theme={null}
Use cubic to list the open review issues on https://github.com/OWNER/REPO/pull/NUMBER.
```
Replace the URL with a PR you can access. The agent should call `get_pr_issues` and show the
open findings with their file locations, severity, and descriptions. An empty result means
there are no open cubic findings on that PR; it does not trigger a new review.
For workflows that also investigate and fix the findings, [install cubic's skills](/ide/skills).
## Available tools
| Tool | Description |
| :----------------------------- | :----------------------------------------------------------------------------------------------- |
| `get_pr_issues` | List open cubic PR review issues, excluding resolved or addressed findings |
| `trigger_pr_review` | Start a full PR review; an already queued or running review continues without restarting |
| `update_pr_issue_status` | Resolve, reopen, or dismiss a PR issue on its GitHub review thread and queue an attributed reply |
| `list_wikis` | List all wikis you have access to |
| `list_wiki_pages` | List all available wiki pages for a repository |
| `get_wiki_page` | Retrieve the content of a specific wiki page |
| `list_scans` | List repository scan summaries |
| `get_scan` | List aggregated scan issues with filters and pagination |
| `resolve_github_user_contacts` | Resolve GitHub usernames to email and Slack mentions |
| `get_issue` | Get full details and code context for a codebase scan issue |
| `update_issue_status` | Update a codebase scan issue's triage status, with optional feedback for future scans |
| `list_learnings` | List AI review learnings for a repository |
| `get_learning` | Get full details of a specific learning |
| `list_organizations` | List accessible organizations and your billing and team-management permissions |
| `get_subscription` | Get the current plan, purchased and assigned seats, review usage, and pending changes |
| `list_members` | List organization members, their roles, and seat assignments |
| `update_member_seat` | Enable or disable an existing member's seat, change their role, or both |
| `update_subscription` | Increase purchased seats or upgrade Team to Pro |
| `update_flex_capacity` | Enable or disable automatic flex purchases and set a spending cap |
Use issue IDs from `get_pr_issues` with `update_pr_issue_status`. For codebase scans, use IDs
from `get_scan` with `get_issue` or `update_issue_status`.
The two update tools change issue state. `update_pr_issue_status` also changes the GitHub
review thread and posts its reply asynchronously. `trigger_pr_review` starts a cloud review.
## Billing and team management
Start with `list_organizations` and use the returned GitHub organization login in the
`organization` argument. Use `get_subscription` to check purchased capacity and pending changes,
and `list_members` to find a member's ID and current role and seat state. Member lists support
search; organization and member lists support pagination using the returned `nextCursor`.
### Permissions and supported subscriptions
Your MCP client uses your cubic permissions. Reading billing and member information requires
organization access. Changing subscriptions, seats, or roles requires an organization admin;
cubic checks current permissions on every mutation. Admins retain billing access when their
own review seat is disabled.
MCP mutations require an active paid Stripe subscription. Free customers receive a link to
upgrade in cubic. Vercel customers must make changes through the cubic UI or Vercel Marketplace.
Reads remain available subject to organization access.
### Assign seats and change roles
`update_member_seat` uses existing purchased capacity and never buys seats. Supply `memberId`
from `list_members`, plus either or both of these pairs:
* `enabled` and `expectedEnabled`: the desired seat state and the current `seatEnabled` value.
* `role` and `expectedRole`: the desired and current role, each one of `admin`, `member`, or `viewer`.
Combined seat and role changes either both apply or neither applies. If the member's state
has changed, refresh `list_members` before submitting another change. Repeating a change that
already matches the desired state returns a no-op.
Admins cannot remove their own admin role or disable the last active human admin. Bots cannot
be admins. If no purchased seats are available, increase capacity with `update_subscription`
before enabling another billable member.
### Buy seats or upgrade the plan
`update_subscription` accepts `seats`, `plan: "pro"`, or both, plus an `idempotencyKey` for the
purchase. `seats` is the desired total, not the number to add: to go from 5 seats to 8, pass
`seats: 8`. The billing interval stays the same. Pro upgrades must meet the organization's
minimum seat requirement; an error tells you the required count.
A subscription can cover multiple organizations through a shared billing account. Purchases
apply to that subscription; the result reports the number of affected organizations.
Use the cubic UI for seat reductions, downgrades, billing-interval changes, or subscriptions
with an existing scheduled, pending, or cancellation change.
### Payments and retries
Check the returned status before treating a purchase as complete:
| Status | Meaning |
| :------------------------ | :------------------------------------------------------------------------------------------------------ |
| `applied` | Stripe has applied the requested subscription change |
| `no_change` | The subscription already matches the requested state |
| `payment_action_required` | Complete payment using the returned action link; the requested capacity is not yet available |
| `processing` | The outcome is uncertain; check the subscription and the returned action before making another purchase |
For a retry, reuse the same `idempotencyKey` with identical arguments. After a timeout, check
`get_subscription` before proceeding; do not generate a fresh key merely because the response
was lost. Retry deduplication follows Stripe's key-retention limits. Reusing a retained key
with different purchase parameters can be rejected.
## Common prompts
* "Show open cubic review issues on PR #42 in acme/backend"
* "Start a cubic review of PR #42 in acme/backend"
* "List wiki pages for acme/backend"
* "Show me the authentication system wiki page"
* "List codebase scan issues in acme/backend with severity at least 7"
* "Mark scan issue abc as false positive with feedback"
* "What review learnings apply to this repository?"
* "How many purchased and available seats does acme have?"
* "Enable Alice's review seat in acme using our available capacity"
* "Make Alice an admin in acme"
* "Increase acme's total purchased seats from 5 to 8"
* "Upgrade acme from Team to Pro with 8 seats"
## Troubleshooting
Confirm your configured URL is exactly `https://www.cubic.dev/api/mcp`. Replacing `www.cubic.dev`
with `cubic.dev` can cause OAuth clients to reject the connection.
Run your client's login command again and complete the browser flow. If you still use a legacy
API-key config, migrate it to OAuth.
Restart your AI client after updating configuration. For Cursor Agent, make sure the server is in
`~/.cursor/mcp.json` or project `.cursor/mcp.json`, not only Cursor's `settings.json`.
Confirm the repository has an [AI Wiki generated](/wiki/ai-wiki), verify you have access to the
repository's installation, and check that `owner` and `repo` match GitHub exactly.
MCP provides cloud findings and context. Install and sign in to the [cubic CLI](/ide/cli-review)
to run a local review. If you want to start it from your agent, also [install the skills](/ide/skills).
### Automatic flex capacity
`get_subscription` includes flex availability, spending settings, configured purchase size and price, and paid/pending usage. `list_organizations` reports `canUpdateFlexCapacity`; mutations still check current permissions and billing eligibility.
Use `update_flex_capacity` with `organization` and at least one of `enabled` or `spendingLimitCents`. The cap is an **absolute USD-cent amount per quota period**, not an increment or a charge amount; it carries forward into future periods. Omitting a field preserves it. For example, `spendingLimitCents: 10000` sets a \$100 cap. Changing the cap alone does not enable flex.
An organization admin can enable flex on an eligible active paid Stripe subscription. Free, trial, and Vercel customers must use the UI. Disable-only requests remain available after a Stripe billing lapse and preserve the saved cap. Any request that edits the cap requires an active paid subscription, including requests that also disable flex. This version does not change purchase size or support unlimited spending.
Flex and automatic seat purchases can both be enabled. Changing one setting preserves the other. Saving settings does not initiate a charge, but ongoing or subsequent review processing can purchase capacity automatically. Obtain an explicit user instruction before enabling flex or increasing its cap. The result reports `applied` or `no_change` for settings, not a completed purchase. Disabling or lowering the cap does not cancel existing invoices, refund spending, or stop in-flight purchases. Pending invoices consume budget but grant no capacity until paid. Retry blocked reviews separately.
# Skills
Source: https://docs.cubic.dev/ide/skills
Review local changes, fix PR comments, and use cubic codebase context from your coding agent.
cubic skills give your coding agent instructions for reviewing code, handling PR comments,
and using your team's codebase context. Ask for a task in natural language, and your agent
can select the relevant skill. You can also name the skill explicitly.
Skills run in your coding agent. They use the [cubic CLI](/ide/cli-review) for local reviews,
the GitHub CLI for PR comment workflows, and the [MCP server](/ide/mcp-server) for wikis,
codebase scan findings, and review learnings.
## Before you start
Set up the tools needed for the workflows you want to use:
| Workflow | Requirement |
| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| Local review | Install the [cubic CLI](/ide/cli-review#get-started) and sign in |
| PR comments and PR review loops | Install the [GitHub CLI](https://cli.github.com), sign in with `gh auth login`, and open your repository locally |
| Wiki, codebase scans, and review patterns | [Connect cubic's MCP server](/ide/mcp-server#install-and-log-in) with OAuth using an account that can access the repository |
For local reviews, we recommend [connecting ChatGPT (Codex) or Claude
Code](/ide/cli-review#bring-your-coding-subscription) for access to more capable review models.
You can also use cubic's included model.
## Install skills
With Node.js and npm installed, run:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --skills-only
```
The installer detects supported agents from their configuration files in your home directory
and installs skills and commands for each one it finds. `--skills-only` leaves your MCP
configuration unchanged; authenticate MCP separately for the workflows that need it.
To choose one agent explicitly, add `--to`. For example, to install for Codex:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --to codex --skills-only
```
Supported targets are `claude`, `codex`, `cursor`, `gemini`, `opencode`, `droid`, and `pi`.
Use `--to universal` for agents that read `~/.agents/skills`; this target is opt-in.
You can also install the cubic plugin from inside Claude Code:
```text theme={null}
/plugin marketplace add mrge-io/skills
/plugin install cubic@cubic
```
This includes skills, namespaced slash commands, and the MCP connection. Run `/mcp`,
choose cubic, and complete the browser sign-in flow.
### Check the installation
Check the installer's summary for your target and any errors. Start a new agent session in
your repository, then ask:
```text theme={null}
Use cubic's run-review skill to review my changes.
```
With the cubic CLI installed and signed in, the agent should run a local review, group
findings by priority, and offer to fix them. If your working tree is clean, the skill reviews
your branch against its base.
## Prompts to start with
| Prompt | What happens |
| :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| "Review my code" | Runs a local review, shows findings, and offers to fix them |
| "Loop until clean" | Reviews, fixes, commits, and repeats using local or PR review; see [review loops](#review-loops) |
| "Check cubic comments" | Investigates unresolved PR threads, fixes worthwhile issues, commits and pushes changes, and resolves handled threads |
| "Show open codebase scan findings for this repo" | Lists scan findings through MCP |
| "Fix the codebase scan issues in ./scan.csv" | Loads full reports, checks the current code, and fixes the requested issues |
| "How does authentication work in this repo?" | Looks up cubic's AI Wiki to explain the codebase |
| "What does this team care about in reviews?" | Retrieves team review learnings |
### PR comments
"Check cubic comments" and the `comments` command both handle review feedback. They wait for
the review to finish, inspect unresolved GitHub review threads, apply and verify worthwhile
fixes, then commit and push if code changed. They resolve handled threads, including findings
confirmed as false positives or already fixed, without posting replies by default.
To only read cubic's open findings, ask your agent to use the MCP tool directly:
```text theme={null}
Use cubic's get_pr_issues tool to summarize the open findings on this PR. Do not change anything.
```
### Review loops
The `cubic-loop` skill uses PR review when the current branch has an open PR or you request
PR mode. Otherwise, it runs local CLI reviews. It commits fixes between iterations and pushes
the branch in PR mode.
The default limit is five iterations. The loop can stop earlier when no issues remain or
when only low-priority P3 findings remain. Check the final summary for remaining findings.
### Codebase scan findings
You can provide a repository, a scan issue ID, or an exported CSV. Listing findings does not
change your code. When you request fixes, the skill verifies each finding against your current
checkout before editing. Commits, pushes, PR creation, and scan triage updates require a
separate request.
## Available skills
| Skill | Purpose |
| :--------------------- | :--------------------------------------------------------------------- |
| `run-review` | Review uncommitted changes or the current branch through the cubic CLI |
| `check-pr-comments` | Investigate and handle unresolved PR review feedback |
| `cubic-loop` | Repeat review and fixes up to an iteration limit |
| `codebase-context` | Retrieve architectural context from cubic's AI Wiki |
| `review-patterns` | Apply team review learnings while writing or reviewing code |
| `handle-codebase-scan` | Inspect scan findings and fix requested issues |
## Slash commands
Command names depend on the agent and how you installed cubic:
| Installation | Example |
| :---------------------------------------------------------------- | :------------------ |
| Claude Code plugin marketplace | `/cubic:run-review` |
| Claude Code with the CLI installer | `/run-review` |
| Cursor, OpenCode, Droid, Gemini CLI, or Pi with the CLI installer | `/cubic-run-review` |
In Codex, use the installed skills by name or describe the task in natural language.
[Custom prompt slash commands are deprecated](https://developers.openai.com/codex/custom-prompts).
The same naming pattern applies to these commands:
| Command | What it does |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run-review [flags]` | Run a local review and offer to fix findings; accepts cubic CLI review flags |
| `comments [pr-number]` | Investigate PR comments, fix worthwhile issues, commit and push changes, and resolve handled threads; detects the PR from the current branch if omitted |
| `wiki [page-name]` | Browse codebase documentation |
| `scan [issue-id]` | List codebase scan findings or read a full issue report |
| `learnings [learning-id]` | Read team review learnings |
## Troubleshooting
Start the agent once so it creates its configuration, or specify the target explicitly with
`--to`, for example `--to codex`.
Check the installer's summary for the target you use, then restart your agent session. If
needed, reinstall for that target with `--force`:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --to codex --skills-only --force
```
For local reviews, complete [CLI setup](/ide/cli-review#get-started). For PR comment
workflows, run `gh auth status`. For wiki, scan, or learning requests, check your agent's
MCP connection and complete OAuth if prompted.
See [Local CLI review](/ide/cli-review#review-with-your-coding-agent) for copy-paste
`AGENTS.md` and `CLAUDE.md` workflow instructions.
# Asana
Source: https://docs.cubic.dev/integrations/asana-integration
Connect Asana to add task context to AI reviews and PR descriptions.
Add task context from Asana to make AI reviews understand your requirements, generate accurate PR descriptions and analyze if your code meets the acceptance criteria from your Asana tasks.
]![Asana integration settings page]()
## Setup
### Connect Asana
1. Navigate to [integration settings](https://cubic.dev/settings?tab=integrations).
2. Follow the instructions to connect your Asana account.
3. Authorize cubic to access your Asana projects.
### Configure AI behavior
Toggle these options based on your workflow:
* **Use context when reviewing code** - AI reviews check if code matches task requirements
* **Show linked issue analysis in reviews** - Post acceptance criteria assessment in PR review comments. When disabled, task context still improves AI review quality but is not shown publicly. Requires "Use context when reviewing code" to be enabled
* **Use context when writing PR descriptions** - Generate descriptions from linked Asana tasks
# Confluence
Source: https://docs.cubic.dev/integrations/confluence-integration
Connect Confluence to bring documentation context into AI reviews and PR descriptions.
Pull documentation from Confluence to provide the AI with better context for code reviews, helping it understand your architecture decisions and technical specifications.
## Setup
### Connect Confluence
1. Navigate to [integration settings](https://cubic.dev/settings?tab=integrations).
2. Click **Configure** on the Confluence integration card.
3. If you already have a Jira connection, cubic enables Confluence access automatically. Otherwise, follow the OAuth flow to connect your Atlassian account.
### Configure AI behavior
Toggle these options based on your workflow:
* **Use context when reviewing code** — The AI reviewer reads linked Confluence pages to understand architecture and requirements before reviewing your code
* **Use context when writing PR descriptions** — Generate descriptions that reference relevant documentation from linked Confluence pages
* **Automatically associate pages** — cubic detects Confluence page URLs in your PR and links them without manual intervention
## How it works
cubic finds Confluence pages by looking for page URLs in your PR description. The URL format looks like:
```
https://your-team.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title
```
Add a Confluence page URL to your PR description and cubic automatically imports the page content for the AI reviewer. The AI uses this documentation context to write more informed reviews and check that your code aligns with documented architecture decisions.
## Best practices
* Link architecture decision records (ADRs) and design docs to PRs that implement those designs
* Reference API specification pages when reviewing endpoint changes
* Include onboarding or setup documentation for PRs that change developer workflows
* Keep Confluence pages up to date so the AI reviewer works with accurate context
# GitHub Issues
Source: https://docs.cubic.dev/integrations/github-issues-integration
Use the GitHub issues your pull requests close as context for AI reviews and PR descriptions.
Add issue context from GitHub Issues to make AI reviews understand your requirements, generate accurate PR descriptions and analyze if your code meets the acceptance criteria in the issue.
GitHub Issues works through the cubic GitHub App you already installed, so there is no separate account to connect.
## Setup
### Enable GitHub Issues
1. Navigate to [integration settings](https://cubic.dev/settings?tab=integrations).
2. Open **GitHub Issues** and click **Connect**.
If cubic reports that it can't access issues, accept the updated permissions for the cubic GitHub App in your GitHub organization settings, then try again.
### Configure AI behavior
Toggle these options based on your workflow:
* **Use context when reviewing code** - AI reviews check if code matches issue requirements
* **Show linked issue analysis in reviews** - Post acceptance criteria assessment in PR review comments. When disabled, issue context still improves AI review quality but is not shown publicly. Requires "Use context when reviewing code" to be enabled
* **Use context when writing PR descriptions** - Generate descriptions from the linked GitHub issue
## How it works
cubic uses the issue GitHub links to your pull request. Link an issue the way you normally would on GitHub:
* Add a closing keyword to the PR description, such as `Fixes #123`.
* Link the issue from the **Development** section of the PR sidebar on GitHub.
For pull requests that target a branch other than the default branch, such as stacked PRs, GitHub doesn't link issues from closing keywords. cubic reads the closing keywords in the PR description itself in that case, for issues in the same repository.
The linked issue appears in the cubic PR sidebar. To change it, update the link on GitHub.
Issue content can appear in AI review comments and PR descriptions, which everyone who can see the
pull request can read. cubic uses issues from the pull request's own repository. It only uses an
issue from another repository when that issue is public and an organization member opened the PR,
because people who can read the pull request might not have access to the other repository.
## Create GitHub issues from codebase scans
With GitHub Issues enabled, you can file [codebase scan](/codebase-scan/codebase-scans) findings as GitHub issues, one at a time, in bulk, or automatically after each scan.
Issues are created in the scanned repository. cubic only files findings in private repositories, because scan findings can include security issues that shouldn't be disclosed publicly.
## Best practices
* Write clear acceptance criteria in the issue for better AI feedback
* Use bullet points or numbered lists for requirements to enable automatic issue analysis
* Include specific, testable criteria that cubic can verify in your code changes
# Jira
Source: https://docs.cubic.dev/integrations/jira-integration
Connect Jira to add issue context to AI reviews and PR descriptions.
Add issue context from Jira to make AI reviews understand your requirements, generate accurate PR descriptions and analyze if your code meets the acceptance criteria from your Jira issues.
![Jira integration settings page]()
## Setup
### Connect Jira
1. Navigate to [integration settings](https://cubic.dev/settings?tab=integrations).
2. Follow the instructions to connect your Jira instance.
3. Authorize cubic to access your Jira projects.
### Configure AI behavior
Toggle these options based on your workflow:
* **Use context when reviewing code** - AI reviews check if code matches issue requirements
* **Show linked issue analysis in reviews** - Post acceptance criteria assessment in PR review comments. When disabled, issue context still improves AI review quality but is not shown publicly. Requires "Use context when reviewing code" to be enabled
* **Use context when writing PR descriptions** - Generate descriptions from linked Jira issues
## How it works
cubic finds Jira issues by looking for issue keys in your PR title or description. The format looks like `PROJ-123` where PROJ is your project key.
Include the Jira key in your PR title (`[PROJ-123] Add authentication system`) or description for cubic to pull in issue context.
Once connected, you can also manually link Jira issues directly in the cubic PR interface.
## Best practices
* Write clear acceptance criteria and user stories in Jira for better AI feedback
* Use Jira's Description and Acceptance Criteria fields to provide comprehensive context
* Format requirements as bullet points or numbered lists for automatic issue analysis
* Be specific with testable criteria that cubic can verify against your code changes
* Create custom agents that reference Jira context for specific checks
* Link related issues and epics in Jira for complete context
# Linear
Source: https://docs.cubic.dev/integrations/linear-integration
Connect Linear to add issue context to AI reviews and PR descriptions.
Add issue context from Linear to make AI reviews understand your requirements, generate accurate PR descriptions and analyze if your code meets the acceptance criteria from your Linear issues.
![Linear integration settings page]()
## Setup
### Connect Linear
1. Navigate to [integration settings](https://cubic.dev/settings?tab=integrations).
2. Follow the instructions to connect your Linear workspace.
### Configure AI behavior
Toggle these options based on your workflow:
* **Use context when reviewing code** - AI reviews check if code matches issue requirements
* **Show linked issue analysis in reviews** - Post acceptance criteria assessment in PR review comments. When disabled, issue context still improves AI review quality but is not shown publicly. Requires "Use context when reviewing code" to be enabled
* **Use context when writing PR descriptions** - Generate descriptions from linked Linear issues
## How it works
cubic finds Linear issues by looking for issue IDs in your PR title or description. The format looks like `ABC-123` where ABC is your team key.
Include the Linear ID in your PR title (`[LIN-123] Add rate limiting`) or description for cubic to pull in issue context.
Once connected, you can also manually link Linear issues directly in the cubic PR interface.
## Best practices
* Write clear acceptance criteria in Linear for better AI feedback
* Use bullet points or numbered lists for requirements to enable automatic issue analysis
* Include specific, testable criteria that cubic can verify in your code changes
* Create custom agents that reference Linear context for specific checks
# Notion
Source: https://docs.cubic.dev/integrations/notion-integration
Connect Notion to add page context to AI reviews and PR descriptions.
Add page context from Notion to make AI reviews understand your requirements and generate accurate PR descriptions.
## Setup
### Connect Notion
1. Navigate to [integration settings](https://cubic.dev/settings?tab=integrations).
2. Click **Connect** on the Notion integration card.
3. Authorize cubic to access your Notion workspace through the OAuth flow.
### Configure AI behavior
Toggle these options based on your workflow:
* **Use context when reviewing code** — The AI reviewer reads linked Notion pages to check whether code matches page requirements
* **Use context when writing PR descriptions** — Generate descriptions from linked Notion pages
* **Automatically associate pages** — cubic detects Notion page URLs and unique ID codes in your PR and links them without manual intervention
## How it works
cubic searches across all accessible pages in your connected Notion workspace. It finds pages through two methods:
### Page URLs
Add a Notion page URL to your PR title, branch name, or description. cubic extracts the page ID and imports the content automatically. Supported URL formats:
```
https://www.notion.so/Page-Title-b55c9c91384d452b81dbd1ef79372b75
https://www.notion.so/workspace/Page-Title-b55c9c91384d452b81dbd1ef79372b75
https://www.notion.so/aabbccdd00112233aabbccdd00112233?p=11223344556677881122334455667788
https://app.notion.com/p/Page-Title-b55c9c91384d452b81dbd1ef79372b75
```
### Unique IDs
If your Notion database uses the [unique ID property](https://www.notion.so/help/database-properties#unique-id), cubic detects codes like `TASK-123` in your PR title or branch name. It searches across all accessible databases in your workspace for a matching prefix and resolves the page automatically.
Include the identifier in your branch name (`feature/TASK-123-add-auth`) or PR title (`[TASK-123] Add authentication`) for cubic to link the page.
Once connected, you can also manually link Notion pages directly in the cubic PR interface.
## Best practices
* Write clear requirements in Notion pages for better AI feedback
* Use Notion's unique ID property in databases so cubic can detect task codes in branch names and PR titles
* Link architecture and design documents to PRs that implement those designs
* Create custom agents that reference Notion context for domain-specific checks
# Overview
Source: https://docs.cubic.dev/integrations/overview
Connect cubic to your issue trackers for enhanced code reviews.
cubic integrates with issue trackers and documentation tools to bring context directly into your code reviews.
## Issue tracker integrations
Connect your issue tracker to bring business context directly into code reviews. Once connected, cubic automatically detects if your PRs meet the acceptance criteria from your issues. [Learn more](/ai-review/issue-analysis).
![Issue analysis showing acceptance criteria results]()
### Available integrations
Verify acceptance criteria, and provide more context for AI reviews and PR descriptions.
Verify acceptance criteria, and provide more context for AI reviews and PR descriptions.
Verify acceptance criteria, and provide more context for AI reviews and PR descriptions.
Use the issues your PRs close to verify acceptance criteria and add context, with no extra
account to connect.
Pull documentation from Confluence to provide context for AI reviews.
Bring Notion page context into AI reviews and PR descriptions.
Issue tracker integrations give the AI reviewer access to the full content of linked issues. We
don't recommend enabling these integrations if you don't want sensitive information from your
issues (e.g., customer names, internal data) to risk being mentioned in AI review comments on
GitHub, particularly for open source projects.
# AI wiki
Source: https://docs.cubic.dev/wiki/ai-wiki
Transform your repository into a searchable knowledge base with AI-generated documentation.
cubic's AI wiki automatically indexes your codebase and produces searchable wikis, complete with links to source code, architecture diagrams, and more.
Use it to get up to speed with unfamiliar codebases or to answer questions about your codebase.
It's especially valuable for onboarding new team members, enabling customer success teams to quickly understand product architecture, and helping anyone navigate complex codebases without deep tribal knowledge.
![Wiki documentation viewer showing agent lifecycle and data flow]()
## Getting started
Go to [cubic.dev/wiki](https://cubic.dev/wiki) or click **Wiki** in the main navigation.
Select a repository and click **Generate**. Public repositories can generate wikis on the free
plan. Private repositories require a paid plan. cubic analyzes your codebase and creates
documentation in about 3 minutes.
Browse the documentation or ask questions in natural language to get instant answers.
## Auto-refresh
Keep your wiki documentation automatically up to date without manual intervention. When enabled, cubic periodically regenerates your wiki to reflect the latest code changes.
Scheduled auto-refresh is available on paid plans. Public repositories can still be refreshed
manually on the free plan, while private repository generation and refresh require a paid plan.
Weekly refresh works well for actively developed repositories. Monthly refresh is ideal for stable
codebases with less frequent changes.
## Repo sync
Bring the wiki to where your team and coding agents already work: your repository. When enabled, cubic exports the wiki as markdown files into a directory in your repo (default `.cubic/wiki`) and keeps them current through a rolling pull request.
Each export contains one markdown file per wiki page organized by section, an `index.md` table of contents, and an `AGENTS.md` entry point so coding agents like Claude Code and Cursor can discover and use your docs without any extra setup.
To enable it, open your wiki and turn on **Repo sync** on the wiki card. Confirm the target directory, and cubic opens a pull request from the `cubic/wiki-sync` branch. From then on:
* Every wiki refresh, scheduled or manual, updates the same rolling PR — merge it whenever you want the repo copy updated
* If the wiki content didn't change, cubic skips the commit, so there's no PR churn
* Use **Sync to repo now** from the wiki card's ••• menu to trigger a sync manually
* Sync status — including a link to the open PR — shows directly on the wiki card
The sync directory is managed by cubic: edits you make inside it are overwritten on the next sync.
To change the content, update your custom instructions and regenerate the wiki.
Repo sync requires a paid plan (the same entitlement as auto-refresh) and the cubic GitHub App needs write access to repository contents. If a sync fails with a permissions error, update the app's permissions from your GitHub installation settings.
## Custom instructions
Add custom instructions to guide how your wiki is generated (for example, "Focus on API docs" or "Write for beginners").
Open the ••• menu on a wiki and choose **Custom instructions**. Instructions are saved per repository and applied on the next regeneration. Custom instructions are capped at 10,000 characters.
## Wiki MCP
Your wiki is available through cubic's [MCP server](/ide/mcp-server). Connect Claude Code, Cursor, Windsurf, or any MCP-compatible tool and your AI assistant can query your wiki directly while you code.
This is especially useful when working across multiple repositories. Your AI agent can pull documentation from any repo's wiki without you leaving your editor.
Combine MCP access with auto-refresh to give your AI tools always-current documentation.
## Asking questions
Ask questions about your codebase in plain English and get comprehensive answers with code references. You can even request visual diagrams to better understand complex architectures and flows.
### Chat best practices
* **Be specific** - "How does the OAuth2 refresh token work?"
* **Include context** - "In the checkout flow, how are payments processed?"
* **Request visual outputs** - "Show me a diagram of the authentication flow"
* **Ask for examples** - "Show me examples of error handling"
* **Avoid vague questions** - "How does it work?"
* **Don't be too broad** - "Explain the entire codebase"
* **Don't expect real-time updates** - Regenerate for the latest code changes
### Sharing answers
Every search generates a shareable URL. Share the link with teammates. Anyone in your GitHub organization with repository access can view it.
## Frequently asked questions
No. Wiki generation and refreshes have separate limits and do not consume your GitHub PR
reviewed-line allowance. See [AI review usage](/account/ai-review-usage#faq).
When enabled, cubic automatically regenerates your wiki on your chosen schedule (weekly or
monthly). This runs in the background, so your documentation stays current without any manual
effort. Scheduled auto-refresh requires an active paid subscription. Public repositories can
still be refreshed manually on the free plan.
Yes, every search generates a shareable URL for your team members with repository access.
Yes. Wiki works with both public and private repositories, and access still follows GitHub
permissions. Public repositories can generate and refresh wikis on the free plan. Private
repositories require a paid plan for generation and refresh.
Wiki is especially valuable for new team members getting up to speed, customer success teams
understanding product architecture, and anyone who needs to navigate unfamiliar codebases
quickly. It eliminates the need to hunt through code or rely on tribal knowledge.
Private wiki slots can be reassigned 90 days after the wiki's first successful generation. To
reuse a slot, open the wiki's ••• menu and delete the wiki. Deleting it on or after day 90 frees
the slot immediately. If you delete it earlier, the slot remains reserved until the original
90-day period ends.
Wikis do not expire automatically. Refreshing a wiki or disabling auto-refresh does not reset
the 90-day period or free its slot.