# 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 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).
* **[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 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 review, or set `reviews.ignore.base_branches` in [`cubic.yaml`](/configure/cubic-yaml).
* **Avoid unnecessary full reruns.** Pushing commits triggers incremental reviews (only new lines count). Manually re-triggering with `@cubic-dev-ai review this PR` runs a full review again — use it deliberately.
* **[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).
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
Genuine large refactors and monorepo-wide changes do count close to their full size. If recurring large PRs are coming from generated files or fixtures, add them to your ignore patterns in [`cubic.yaml`](/configure/cubic-yaml).
Pushing new commits triggers an incremental review and only the new lines count. Manually re-triggering a review with `@cubic-dev-ai review this PR` runs a fresh review and counts again — so use it deliberately.
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, you can ignore PRs labelled `wip` or `skip-review` until the label is removed.
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.
For paid teams, eligible public-repository PRs from external contributors are handled separately from the team's reviewed-line pool, so external OSS traffic does not spend capacity intended for private and internal work. 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 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 |
| -------------- | ------------------------------------------- |
| Block size | 10,000 extra reviewed lines |
| Price | \$20 per block |
| 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
Flex capacity is bought in whole \$20 blocks. cubic buys enough blocks to cover the current overage, and it never buys a partial block.
| Current overage | Blocks bought | Charge | Extra capacity granted |
| --------------------- | ------------- | ------ | ---------------------- |
| 4,000 reviewed lines | 1 block | \$20 | 10,000 reviewed lines |
| 15,000 reviewed lines | 2 blocks | \$40 | 20,000 reviewed lines |
| 30,000 reviewed lines | 3 blocks | \$60 | 30,000 reviewed lines |
If a review is 15,000 reviewed lines over the included limit, cubic needs two blocks. If your remaining monthly flex spend limit is only \$20, cubic does not buy one block because that would charge you without unblocking the review.
## 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 two more blocks, cubic will not charge $40 and reviews will stay paused because that would exceed the $60 limit.
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 with a secure Stripe invoice link. The extra capacity is granted after the payment is confirmed.
A failed flex capacity payment stops additional automatic flex purchase attempts for the same billing period. Update the payment method in billing settings to resume automatic flex capacity.
## 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. Enter a monthly dollar amount in \$10 increments.
5. Save the limit.
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 whole 10,000-line blocks. A PR that is 10,001 reviewed lines over the limit requires two blocks, because one block would not unblock the review.
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. The sandbox has no network egress.
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 (currently OpenAI and Anthropic). 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 Amazon gift cards 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 Amazon gift cards 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 a \$240 Amazon gift card.
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
## 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.
cubic offers both a free plan and paid subscriptions to fit every team's needs.
## How cubic works
**Standard signups start with a 7-day free trial:**
* **AI reviews included** during the trial period
* **Full platform access** to all features
* **No credit card required** to get started
**When your trial ends, you choose:**
* **Continue free:** Get 20 AI reviews per month with full platform access
* **Upgrade to paid:** Get AI reviews with the same full platform access
**Important:** Regardless of which plan you choose, you always get complete access to cubic's platform—PR management, analytics, notifications, and all features. Free plans have a fixed monthly AI review quota, while paid plans include a shared monthly AI review allowance across paid seats.
## Free plan
Get started with cubic immediately—no credit card required:
* **Unlimited platform access:** View and manage all your pull requests in cubic
* **20 AI reviews per month:** Get intelligent feedback on your most important PRs across all repositories
* **Full feature access:** Analytics, code reviews, issue tracker integrations, background agents, and more;
* **Monthly quota reset:** Your AI review limit resets on the 1st of each month
Perfect for personal projects, or evaluating cubic for your team.
### How the free plan quota works
* **Organization-wide limit:** The 20 AI reviews per month are shared across all repositories in your GitHub organization
* **Automatic tracking:** AI review comments show how many reviews you have remaining
* **Monthly reset:** Your quota automatically resets to 20 on the 1st of each month
## 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.
### Flex capacity
Paid workspaces can use [flex capacity](/account/flex-capacity) to keep GitHub PR AI reviews running after included reviewed-line usage runs out. Flex capacity costs **\$20 per 10,000 extra reviewed lines** and is billed only when cubic needs extra capacity for a review.
Admins set a monthly spend limit in **Settings → Subscription**. cubic never spends past that limit; if the next required purchase would exceed the limit, reviews pause until you raise the limit or the billing period resets.
### Automatic seat management
Admins can enable automatic seat management to handle team changes automatically.
When enabled in your subscription settings, cubic will automatically assign and remove seats as your team changes.
How it works:
* When a new developer joins your GitHub organisation, they’ll automatically get a cubic seat. You’ll see this reflected in your billing.
* If a developer leaves your organisation, their seat is removed and you’ll stop being billed for them.
**Manual and automatic work together:**
You can still manually assign seats if you want. For example:
* If you’ve already given seats to 3 out of 10 developers, and then turn on automatic assignment, the next (11th) developer who joins will automatically get a seat—bringing your total to 4.
* This gives you flexibility to mix and match manual and automatic seat assignment, based on what works best for your team.
## Bot seat management
### Devin-bot support
cubic recognizes and provides special handling for automated coding assistants like Devin. When Devin opens a pull request in your repository:
* **Automatic detection:** PRs authored by `devin-ai-integration[bot]` are automatically identified.
* **Dedicated bot row:** Devin is assigned a bot row that's kept separate from regular developer seats.
* **No paid developer seat:** Enabling the bot allows its PRs to receive AI reviews without increasing your paid developer seat count.
* **Shared reviewed-line allowance:** Bot-authored reviews use the same pooled reviewed-line allowance as the rest of your team.
* **No manual configuration needed:** The system automatically creates and manages the Devin bot seat when it first contributes to your repository.
This feature ensures that teams using AI coding assistants can integrate them into their workflow without adding a paid developer seat for the bot account.
## Free trial
During the free trial period, you can assign as many developer seats as you like to evaluate cubic with your team. When you choose a paid plan at checkout, billing starts immediately and is based on the number of seats you select.
If you have any further questions about billing, please [contact support](mailto:contact@cubic.dev).
## Frequently asked questions
To choose paid seats, go to **Settings → Subscription** and click "Upgrade".
1. **Choose Seat Count:** At checkout, on the left side of the checkout page, specify the *total number* of developer seats you need.
2. **Assign Seats:** After purchasing, return to **Settings → Subscription**. You'll find a list of your GitHub organization members with several ways to manage seats:
### Individual seat assignment
* Toggle the switch next to each developer's name to assign or unassign their seat
* Changes take effect immediately
### Bulk seat assignment
* Select multiple users using the checkboxes next to their names
* Click "Update seat status" in the bulk action bar
* Choose "Assign seats to X users" or "Unassign seats from X users"
If you see a "Manage Subscription" button instead of "Upgrade," you may need to cancel your initial trial subscription via Stripe before proceeding.
Yes. We offer an annual subscription at a 20% discount off the monthly rate.
Simply 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]()
Absolutely. 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—just reach out to support to get set up.
Yes! We're proud to support nonprofits and schools with a special 50%
discount. Please [contact
support](mailto:contact@cubic.dev?subject=Nonprofit%20Discount) to verify your
eligibility.
cubic is automatically free for all public repositories. You don't need to
contact us or apply - just install cubic on your public repositories and
start using it immediately at no cost. Very high-volume usage may be subject
to fair-use limits.
When you increase seats, we calculate the unused portion of your month and
charge only for the prorated difference. If you remove seats, your credit
will apply to your next invoice.
Paid AI review usage is measured in reviewed lines rather than a fixed number of reviews.
Your allowance is pooled across all paid seats on your team, so each paid seat adds to a shared monthly usage pool.
Most teams never get close to these limits unless they are among the heaviest AI users.
In practice, that means a 1- or 2-person team shipping a very high volume of code is more likely to approach the limit than a 20-person team, because the larger team has a much bigger shared pool.
Flex capacity is optional extra reviewed-line capacity for paid workspaces. It costs \$20 per 10,000 extra reviewed lines, is charged only when a review needs more capacity, and stops at the monthly spend limit an admin sets. See [Flex capacity](/account/flex-capacity) for detailed examples.
Reviewed lines are the PR code changes cubic actually reviews, not repository size, total file size, or lines generated by AI. For most PRs, this means the added and deleted lines in the diff that cubic reads during review.
Generated files, vendored code, binaries, ignored files, skipped files, and failed or cancelled reviews do not count. Incremental reviews only count newly reviewed changes; manual reruns count again. For more detail, see [AI review usage and limits](/account/ai-review-usage).
**During your 7-day trial:** You get AI reviews and full platform access.
**When your trial ends:** You automatically transition to cubic's free plan, which includes:
* 20 AI reviews per month (resets monthly)
* Unlimited platform access (same as trial)
* All features remain available (analytics, PR management, notifications, etc.)
**No interruption:** You keep using cubic exactly as before, just with a monthly AI review limit. Upgrade anytime for paid AI review access with a larger shared allowance across paid seats.
Yes! cubic offers a permanent free plan with 20 AI reviews per month and unlimited
access to the platform. This includes all features like analytics, stacked PRs, and
notifications. Only the number of AI reviews per month is limited—everything else is
unlimited. Perfect for personal projects and small teams getting started.
In [**Settings → Subscription**](https://www.cubic.dev/settings?tab=subscription), admins have multiple ways to manage seat assignments:
**Individual management:**
* Toggle the switch next to any team member to assign/unassign their seat
* Changes apply instantly
**Bulk management:**
* Select multiple users with checkboxes
* Use "Update seat status" dropdown to assign or unassign seats for all selected users
* Perfect for onboarding new teams or managing large groups
Members and viewers can view the team list but cannot change seats or roles. Only admins see checkboxes and management controls.
No. Seats are assigned per GitHub organization. If the same developer needs cubic access in two organizations, assign that developer a seat in each organization.
The subscription seat limit is checked against the selected organization, not the combined total across every linked organization.
cubic has three roles: **Admin**, **Member**, and **Viewer**.
**Admins** can manage seats, change user roles, configure auto-assign settings, and manage billing.
**Members** have full access to all cubic features and can manage non-billing settings, but they cannot change seats, roles, or billing details.
**Viewers** can view cubic settings and review surfaces, but they cannot change settings, integrations, seats, roles, or billing details.
The first user who creates an installation becomes an admin automatically. You need
at least one admin per team, and admins cannot remove their own admin role. Bot
accounts cannot be promoted to admin.
See the [Roles and permissions](/account/roles-and-permissions) page for complete details.
cubic automatically detects and manages seats for recognized bots like Devin
(`devin-ai-integration[bot]`). These bot seats are:
* **Created automatically** when the bot first opens a PR
* **Not billed as developer seats** when enabled
* **Disabled by default** but can be enabled if you want the bot's PRs to receive AI reviews
* **Counted against your normal reviewed-line allowance** when their PRs are reviewed
* **Visible in your subscription settings** alongside regular team members
This lets admins enable bot-authored PR reviews without increasing the paid
developer seat count.
# Support
Source: https://docs.cubic.dev/account/support
Contact cubic support for help, questions, and feedback.
If you have any questions, require help, or want to share feedback, please reach out to [contact@cubic.dev](mailto:contact@cubic.dev).
# 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**: Ignore PRs from specific branches (e.g., `feature/*`, `hotfix/*`)
* **Base branch patterns**: Skip PRs targeting certain branches (e.g., `staging`, `develop`)
* **PR label patterns**: Bypass review for PRs with specific labels (e.g., `wip`, `skip-review`)
* **PR title patterns**: Ignore PRs with titles matching patterns (e.g., `Draft:*`, `WIP:*`)
* **Maximum changed lines**: Skip automatic reviews when a PR's added plus deleted lines exceed the repository limit. The default is 50,000 changed lines; you can override it in either direction, up to cubic's technical maximum. Leaving the setting absent or blank uses the 50,000 default. Manual `@cubic-dev-ai review` requests are not limited by this repository setting.
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 issues are found 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
* **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.
* **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
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
* 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** (Beta)
* Allow cubic to read selected repositories during PR review
* Configured per repository from the **Cross-repo reviews** card
* Available on every plan during beta; plan access may change at general availability
* 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).
## 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 leaves a normal review comment instead.
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.
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.
## Safety controls
Auto-approval is conservative by design:
* cubic only approves when it finds no review issues.
* Shadow mode never submits a real approval.
* Never-auto-approve rules block approval when a PR changes sensitive files.
* 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 leaves a normal review comment instead of approving.
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.
## Integration with your workflow
Fixes integrate seamlessly with your existing review process:
1. **Review the change** (fix PR or new commits on your PR branch)
2. **Merge when satisfied** if a fix PR was opened
3. **Continue with your original PR** now including the fix
4. **Single deployment** - Everything ships together
This keeps git history clean while enabling granular review.
# Cross-repo reviews (Beta)
Source: https://docs.cubic.dev/ai-review/cross-repo-reviews
Allow cubic to read selected repositories during PR review.
Cross-repo reviews allow cubic to read selected repositories during PR review. Use them when changes in one repository affect another, such as frontend/backend APIs, shared schemas, docs, or companion releases. Add repository links to choose which repositories are available as context.
Both repositories must be installed in the same cubic GitHub installation.
Cross-repo reviews are available on every plan during beta. Plan access may change at general
availability.
## How it works
When you link two repositories and open a pull request in either one, cubic:
1. **Checks whether the link applies** - Uses the changed files and your guidance to decide whether the linked repository matters for this PR.
2. **Reads the linked repository on demand** - If the link applies, code review agents inspect the shared surface being changed.
3. **Posts cross-repo findings** - Issues that affect the linked repository appear as comments on the original PR, with citations to the affected files.
4. **Tracks companion PRs** - If you reference a PR in the linked repository from the original PR description, cubic watches it and updates findings once the companion PR pushes a fix.
## 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 click **Add**.
3. Choose the related repository from the picker. Only repositories in the same installation appear.
4. Write 1-2 sentences describing what the repositories share and what changes need coordination, then click **Link repository**.
Repository links are bidirectional. Configure a pair once, and code review agents can use the
link from either repository.
### Constraints
* 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. Aim for around 50. Code review agents read guidance verbatim, so concise text 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 companion PR). Specific guidance makes relevance checks more accurate.
## Referencing companion PRs
When your change spans two repositories, link the companion PR in the original 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 original 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 along with the commit SHA that fixed it. If a comment cites multiple cross-repo concerns and only some are addressed, the comment notes partial resolution so you know what's still outstanding.
## Troubleshooting
cubic decided the repository link does not apply to this PR. Check that your
guidance names the surface that's actually changing in the PR — for example, guidance
that only mentions "API routes" does not apply to a CSS-only change. If guidance
is already specific, the linked repository may not be affected by this PR.
Confirm two things: the referenced PR is in a linked repository, and the
reference in the original 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.
The rules library lets you discover proven agents from other successful teams, apply one agent to multiple repositories, and manage everything from a central dashboard.
![Rules library with categories and multi-repo management]()
## Rules library
The rules library enables teams to share and adopt best practices efficiently. Instead of creating the same agent for each repository, you can create an agent once and apply it to any number of repositories.
Manage all 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]()
Custom agents can be applied to multiple repositories from a single definition. You can enable
different combinations of agents for each repository while managing them all from one central
location.
## 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
The multi-repository management capability streamlines how teams handle custom agents at scale:
### One agent, many repositories
When you create or edit an agent, you can select which repositories it applies to:
* Use the repository selector to choose multiple targets
* Apply the same security check to all 150 microservices with one agent
* Maintain consistency without duplication
### Repository-specific control
While agents are centrally managed, you maintain granular control:
* Enable or disable agents per repository as needed
* Different repositories can use different combinations of agents
* Changes propagate instantly across all selected repositories
### Benefits for teams at scale
This approach dramatically simplifies agent management:
* **Before**: Creating 150 separate agents for 150 microservices
* **After**: One agent applied to all 150 repositories
* **Time saved**: Hours of setup reduced to minutes
* **Maintenance**: Update once, apply everywhere
## 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
* **Start with the library**: Before creating a new agent, check if a similar one already exists in the community library. You can adopt and customize popular agents to fit your needs.
* **Combine related checks**: With a limit of 5 active agents per repository, combine multiple related checks into a single agent where it makes sense. The multi-repository feature means you only need to define this once.
* **Leverage path filters in monorepos**: When working with monorepos, use Glob patterns to target specific files or folders. The "glob wizard" and "glob testing" tools help ensure your patterns work correctly.
* **Use repository groups**: Apply agents to logical groups of repositories (e.g., all frontend repos, all microservices) to maintain consistency across similar projects.
* **Learn from others**: Browse popular agents in the library to see what other successful teams are checking for. This can inspire new agents or improvements to your existing ones.
* **Complement existing tools**: Custom agents should focus on checks that standard tools like ESLint or Prettier might miss, such as business logic validations or 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 trigger a new AI review:
* `@cubic-dev-ai`
* "@cubic-dev-ai review this PR"
* Or simply tag `@cubic-dev-ai` with any request - it will understand you want a 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
* *Stays out of your way*: Only surfaces issues worth your attention, with minimal verbosity, and auto-resolves addressed issues. No poems or pointless noise.
* **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
* **Background agents**: Automatically fix issues in the background using Claude Code in a Sandboxed environment.
![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 will automatically review new new pull requests. See an [example reviews
for Posthog, n8n and more](https://cubic.dev/examples).
Follow the [Developer Quickstart](/ai-review/quickstart) for a hands-on tutorial on interacting
with AI reviews, setting up custom agents, and using background agents.
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
We take the security of your code seriously. Our systems are built with the following principles in mind:
* **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.
We use a mix of leading model providers. Our system is designed to select the best model for a
given task, and we continuously upgrade our models to ensure the highest quality suggestions.
If a pull request contains more than 200 files (excluding binary files and those matching ignore
patterns), cubic will review the highest-priority 200 eligible files.
Yes. cubic has access to current documentation for the libraries and frameworks in your stack,
so suggestions account for the latest APIs, deprecations, and best practices—not outdated
patterns from stale training data.
## 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 or Jira issues.
Connect cubic to your issue tracker (like Linear or Jira) 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
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
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
* 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 allow cubic to read selected repositories during PR review. Use them when changes in one repository affect another, such as frontend/backend APIs, shared schemas, docs, or companion releases.
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.
## 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 hands-on with cubic AI code review in minutes.
This guide walks you through setting up and using cubic's AI code reviewer for the first time. By the end, you'll know how to install the app, trigger reviews, interact with AI comments, and set up custom agents.
## 1. Install the cubic GitHub App
Go to [cubic.dev/sign-up](https://cubic.dev/sign-up) and sign in with your GitHub account.
Authorize cubic to access the repositories you want to review. You'll get 7 days free, no credit card required.
## Share with your team
Copy and paste this message into Slack after you install cubic:
```text theme={null}
Heads up: we've enabled cubic (https://cubic.dev) on our repositories — the [top-ranked AI code reviewer](https://codereview.withmartian.com/?mode=offline) on independent benchmarks.
What this means day to day:
- New PRs get an automatic AI review on GitHub. Expect inline comments when it spots something worth a look.
- Reply to its comments like you would to a teammate — including when something isn't useful. Replies tune it for our codebase over time.
- Run reviews locally before you push with the CLI — https://docs.cubic.dev/ide/cli-review
- Tag @cubic-dev-ai in a PR comment to re-run a review, ask for clarification, or request a fix.
More info: https://docs.cubic.dev/ai-review/quickstart
```
## 2. Trigger your first review
To get your first AI review, you have two options:
**Option 1: Open a new pull request**
cubic automatically reviews new pull requests within a few minutes.
```bash theme={null}
git checkout -b feature/my-feature
# Make some changes
git add .
git commit -m "Add new feature"
git push origin feature/my-feature
```
Open the PR on GitHub, and cubic will automatically start the review.
**Option 2: Tag cubic in an existing PR**
For existing pull requests, add a comment tagging `@cubic-dev-ai` to trigger a review. cubic will start within a few minutes.
**What you'll see:**
* A comment from `@cubic-dev-ai` with the PR summary
* Inline comments on specific code changes pointing out bugs and improvements
* Actionable suggestions with explanations
## 3. Interact with cubic
You can reply to cubic, provide feedback, and request changes.
Reply to any AI comment to ask for clarification:
```
@cubic-dev-ai Can you explain why this is a concern?
```
The AI will respond with more context.
Help cubic learn by reacting to comments:
* **Thumbs up** if the suggestion is helpful
* **Thumbs down** if it's not relevant
cubic remembers your feedback and improves over time.
Ask cubic to generate a fix:
```
@cubic-dev-ai Can you fix this?
```
If [background agents](/ai-review/key-features#background-agents) are enabled, cubic can automatically apply the fix.
You can also ask cubic to explain code directly in PR comments, for example
`@cubic-dev-ai explain this function`.
## 4. Use cubic in your editor
Once the GitHub review flow is working, add cubic to your coding agent so you can fix PR issues without leaving the editor and optionally add local reviews later.
* Use [Connect cubic to your IDE](/ide/agent-setup) to install cubic in Cursor, Claude Code, VS Code, Codex, Gemini CLI, or another coding tool.
* Use [Local CLI review](/ide/cli-review) if you want the advanced local-review loop in the terminal.
* Use [What to ask your agent](/ide/skills) for the best prompts and slash commands.
## 5. Set up your first custom agent
Custom agents are review rules that enforce team-specific standards. Let's create a simple one.
1. Go to [cubic.dev/dashboard](https://cubic.dev/dashboard)
2. Select your repository
3. Click **Custom Agents** in the sidebar
Click **New Rule** and define it using natural language:
**Example rule:**
```
All API endpoints must include error handling with try-catch blocks
```
You can also use code patterns:
```regex theme={null}
Avoid using `any` type in TypeScript function parameters
```
Open a new PR that violates the rule. cubic will flag it:
```typescript theme={null}
// This will trigger the rule
function apiCall(data: any) {
return fetch('/api', { body: data })
}
```
cubic will comment: "This function parameter uses `any` type, which violates the custom agent."
For more advanced rule configurations, see [Custom review rules](/ai-review/custom-agents).
## 6. Use background agents
Background agents automatically fix issues without manual intervention.
In your repository settings on [cubic.dev](https://cubic.dev), enable **Background Agents**.
When cubic identifies an issue, you can request a fix by clicking the **Fix with cubic** button in the GitHub comment, or by tagging cubic:
```
@cubic Please fix this
```
Use any supported cubic tag in the current comment when you want cubic to edit code:
* `@cubic Please fix this`
* `@cubic-dev-ai Please fix this`
* `@cubic open a fix PR`
Replying inside an existing cubic thread without a fresh cubic tag is treated as discussion,
not permission to push changes.
By default, cubic pushes commits to your PR branch. If you want a separate PR instead, include
"open a fix PR."
cubic will:
1. Generate the fix
2. Push commits to your PR branch by default, or open a fix PR when requested
3. Update the comment with the result
Check the new commit to verify the changes. You can always:
* Request modifications
* Revert the commit if needed
* Provide feedback for future fixes
## 7. Explore PR summaries
cubic automatically generates PR descriptions based on your code changes.
When you create a PR, cubic will:
1. Analyze the diff
2. Generate a summary including:
* What changed
* Why it changed
* Potential impacts
3. Post it as the first comment
You can also request a summary update:
```
@cubic-dev-ai update the PR summary
```
## What's next?
Now that you've experienced the basics, explore more features:
* [**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
* [**What to ask your agent**](/ide/skills): Learn the best prompts and slash commands
* [**Key features**](/ai-review/key-features): Deep dive into all AI review capabilities
* [**Custom review rules**](/ai-review/custom-agents): Advanced rule configurations and patterns
* [**Memory and learning**](/ai-review/memory-and-learning): How cubic adapts to your codebase
* [**Interactive comments**](/ai-review/interactive-comments): Full list of AI commands and interactions
* [**Settings**](/ai-review/ai-review-settings): Configure review behavior and preferences
Have questions? Check out the [FAQ section](/ai-review/introduction#frequently-asked-questions) or
[contact support](/account/support).
# 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** metric requires at least 10 merged PRs in the selected period. Below
that threshold, a message prompts you to merge more PRs before the metric becomes available.
## 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.
| 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` | Number of cubic issues flagged on the pull request. |
| `numberOfCubicIssuesFixed` | Number of cubic issues fixed on the pull request. |
| `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. |
# 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 or Linear 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 or Jira.
* **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 or Jira 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 or Linear tickets
If your repo is connected to [Jira](/integrations/jira-integration) or [Linear](/integrations/linear-integration), you can create tickets directly from a finding.
### 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 or Jira project and issue type
* 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
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.
> **Public Beta:** `cubic.yaml` configuration is now available in public beta.
## 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`.
Organization configuration is read from the default branch of `cubic-config`. Changes are picked up automatically when you push to the default branch, and cubic invalidates its cache so the next review on any repository in the org uses the updated settings.
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.
## 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
exclude:
- '**/migrations/**'
- infra/**
# 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; cubic skips reviews when these 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
### Core options
| Field | Description |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Master toggle for AI reviews on the repository. |
| `sensitivity` | `low`, `medium`, or `high`—controls how picky the AI is about surfacing issues. |
| `incremental_commits` | `true` reviews new commits pushed to open PRs (only new issues are posted); `false` reviews only when the PR is first opened. 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.exclude_external_contributors` | `true` keeps reviewing public-repository PRs from external contributors, but prevents cubic from auto-approving them. Default: `false`. |
| `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.
| YAML path | Effect |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reviews.ignore.files` | Skip matching files entirely (same syntax as `.gitignore`). |
| `reviews.ignore.head_branches` | Ignore PRs based on their source branch. |
| `reviews.ignore.base_branches` | Ignore PRs targeting specific base branches. |
| `reviews.ignore.pr_labels` | Ignore PRs with one of these labels. Supports wildcards. |
| `reviews.ignore.pr_titles` | Ignore PRs whose titles match the provided wildcard patterns. |
| `reviews.ignore.max_changed_lines` | Skip automatic reviews when added plus deleted lines exceed this positive integer. Manual review triggers can still override it unless cubic's hard infrastructure cap is also exceeded. |
### Common ignore recipes
Use labels or branch names to control when cubic jumps into a review.
#### 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 so it can read PR review issues, use codebase wikis, inspect scan results, triage scan issues, and read team review learnings while you work.
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.
Open Cursor **Settings**.
Go to **Tools and MCP**.
In MCP, use **Home MCP Servers** or your project-specific MCP section.
Click **New MCP server**.
Add this to the config and save:
```json theme={null}
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp"
}
```
Click **Connect**.
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}
cursor-agent mcp enable cubic
cursor-agent mcp login cubic
```
```bash theme={null}
cursor-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 cubic's Claude Code skills separately:
```bash 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.
Run Pi's guided setup:
```bash theme={null}
pi-mcp-adapter init
```
Confirm the MCP 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
```
Follow VS Code's OAuth prompt for the cubic MCP server.
Run **MCP: List Servers** and confirm cubic is running.
## What you can ask
* "show cubic issues on 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
```
| Command | Description |
| :----------------------------------------- | :------------------------------------------------------------------------- |
| `/cubic-run-review` or `/cubic:run-review` | Run a local cubic AI code review from your editor. Requires the cubic CLI. |
The `/cubic-run-review` and `/cubic:run-review` commands require the cubic CLI. See [Local CLI review](/ide/cli-review)
for installation.
# 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** runs a lightweight version of cubic's AI code review directly into your terminal. It's designed as a fast pre-flight check before you push, not a replacement for cubic's cloud PR review.
The CLI detects bugs in your local changes and generates a prompt for you to paste into your AI IDE (like Cursor) to automatically fix them. It syncs with supported cubic cloud context such as your [custom agents](/ai-review/custom-agents), past feedback, and repository settings, but it does **not** use the same models or review pipeline as cubic's cloud PR review.
Do not expect identical results between `cubic review` and cubic's cloud PR reviews. The CLI is
intentionally faster and less thorough for local iteration, while cloud PR reviews are more thorough
and may find issues that the CLI did not flag.
CLI usage shows up in your [analytics dashboard](https://www.cubic.dev/analytics) as **CLI sessions** so you can track adoption across your team.
## Getting started
Install the cubic CLI with the command for your operating system.
### macOS and Linux
Use the shell installer:
```bash theme={null}
curl -fsSL https://cubic.dev/install | bash
```
### Windows
Use `npx`:
```powershell theme={null}
npx @cubic-dev-ai/cli install -g
```
After installation, type `cubic` to open the CLI and start a review.
![cubic CLI home screen showing review preset options]()
## Authentication
The first time you run `cubic`, it will automatically open your browser to sign in with your cubic.dev account. Once authenticated, you're all set — no extra steps needed.
If you run into any authentication issues, press `Ctrl+L` to log out and re-authenticate.
## Bring your coding subscription
The CLI includes a default model, but you can also connect your **ChatGPT Plus/Pro** or **Claude Code** account to run reviews with additional models. These integrations are optional.
### Use your ChatGPT subscription
Connect your ChatGPT account to run reviews against Codex models with your existing plan:
```bash theme={null}
cubic auth connect codex
```
Sign-in happens in your browser. Once connected, choose the Codex model that fits the task.
### Use your Claude Code account
Connect your Claude Code account to run reviews with Claude:
```bash theme={null}
cubic auth connect claude-code
```
Choose the Claude model that fits the review: `opus` when thoroughness matters most, `sonnet` for everyday reviews, `haiku` when you need speed.
#### Why this is permitted under Anthropic's policy
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.
### Switch providers any time
Press `Ctrl+P` to switch provider or `m` to switch model. If you have more than one provider connected, cubic picks the best available model by default. You can change either at any time — no re-authentication needed.
To disconnect a provider, run `cubic auth logout` and pick the one you want to remove. Disconnecting Claude Code only detaches it from cubic; your Claude Code login stays intact.
## When to use local review
Use one of these two workflows:
* **Default: GitHub review only**: Push your branch, let cubic review the PR on GitHub, then fix the comments. This is the simplest setup and the best default for most teams.
* **Advanced: local review plus GitHub review**: Run local review before you push so you can iterate on your code before opening a PR, then rely on GitHub review as the final pass.
## Use it with your coding agent
Most teams use the cubic CLI together with a coding agent:
* Ask your coding agent to `"review my code"` while you are working.
* Run `cubic review` when you want an explicit local pass in the terminal.
* Re-run the local review after fixes, then push and rely on the GitHub PR review as the final pass.
If you have not connected cubic to your editor yet, start with
[Connect cubic to your IDE](/ide/agent-setup).
## Add this to `AGENTS.md`, `CLAUDE.md`, or `.cursorrules`
Use this snippet if you want your coding agent to follow the default GitHub-first workflow:
```markdown theme={null}
## cubic workflow
After pushing, wait for cubic's GitHub review.
Ask the agent to "check cubic comments" or "fix cubic issues".
Push the fixes and repeat until the pull request is clean.
```
Add this extra block if you want the advanced local-review loop:
```markdown theme={null}
Before committing, run `cubic review` or ask the agent to "review my code".
Fix the validated issues and run the local review again.
Repeat until the local review is clean or only disputed issues remain.
Do not expect the cubic CLI and GitHub PR review to return identical results.
The CLI is faster and less thorough.
```
## Common Workflows
The CLI adapts to different stages of your development process.
![cubic CLI review results showing prioritized issues]()
### 1. Review Uncommitted Changes (Default)
Review code you are currently working on, before you commit.
```bash theme={null}
cubic review
```
### 2. Review a Pull Request (Branch Review)
Compare your current branch against a base branch (e.g., `main`) to catch issues before opening a PR.
```bash theme={null}
# Auto-detect base branch
cubic review --base
# Explicit base branch
cubic review --base main
```
### 3. Review a Specific Commit
Analyze changes introduced by a specific commit hash or reference.
```bash theme={null}
cubic review --commit HEAD~1
```
### 4. Custom Instructions
Focus the review on specific concerns like security or performance.
```bash theme={null}
cubic review --prompt "check for XSS vulnerabilities"
```
## Command Reference
The primary command is `cubic review`.
```bash theme={null}
cubic review [options]
```
### Options
| Option | Alias | Description |
| -------------------------- | ----- | --------------------------------------------------------------------------------- |
| `--json` | `-j` | Output results as JSON (for CI/automation) |
| `--output-format ` | | Select `text`, `json`, or streaming `stream-json` output |
| `--base [branch]` | `-b` | Review against a base branch (PR-style). Auto-detects base if no branch specified |
| `--commit [` | `-c` | Review a specific commit |
| `--prompt ` | `-p` | Custom review instructions |
**Note:** `--base`, `--commit`, and `--prompt` are mutually exclusive.
## Output Formats
### Text Output (Default)
Human-readable output with colored priority labels, designed for interactive use.
```text theme={null}
[P0] src/api/auth.ts:45
SQL injection vulnerability in user lookup
User input is concatenated directly into SQL query without parameterization.
```
### JSON Output
Structured output for tools and automation.
```bash theme={null}
cubic review --json
```
```json theme={null}
{
"issues": [
{
"priority": "P0",
"file": "src/api/auth.ts",
"line": 45,
"title": "SQL injection vulnerability in user lookup",
"description": "User input is concatenated directly into SQL query without parameterization."
}
]
}
```
### Streaming JSON Output
Use streaming JSON when an agent, CI job, or other integration needs review progress before the
review finishes.
```bash theme={null}
cubic review --output-format stream-json
```
The command writes compact NDJSON events to stdout as the review runs, including finding updates,
retries, heartbeats, and one final `review.completed` or `review.failed` event. Use `--json` instead
when you only need one JSON object after the review completes.
## Auto-update
The cubic CLI updates itself automatically. Each time you run a command, it checks in the background for a newer version. If one is available, it upgrades the install in place and then runs that command on the updated binary.
### Disabling auto-installs
Add to your global cubic config (`~/.config/cubic/config.json`):
```json theme={null}
{
"disable_auto_updates": true
}
```
With this set, cubic still tells you when a new version is available but does not install it:
```text theme={null}
New version available: v1.2.2. Run `cubic upgrade` to install.
```
### Skipping the check entirely
Set the environment variable to opt out of both the version check and any install:
```bash theme={null}
export CUBIC_DISABLE_AUTOUPDATE=1
```
This is useful in CI, on machines without outbound internet, or when you want to pin a specific version.
### Upgrading manually
Run `cubic upgrade` to upgrade immediately to the latest release, or `cubic upgrade ` to install a specific version.
## AI attribution tracking
The cubic CLI installs [git-ai](https://usegitai.com) during setup to tag AI-assisted commits with git notes. These notes power the [AI coding analytics](/analytics/ai-coding) dashboard for tool usage and authorship trends.
Attribution tracking is **enabled by default**. git-ai shows a brief AI vs human authorship summary after each commit.
### Opting out at install time
Set `CUBIC_DISABLE_GIT_AI` before running the installer to skip git-ai during setup.
macOS and Linux:
```bash theme={null}
CUBIC_DISABLE_GIT_AI=true curl -fsSL https://cubic.dev/install | bash
```
Windows:
```powershell theme={null}
$env:CUBIC_DISABLE_GIT_AI = "true"
npx @cubic-dev-ai/cli install -g
```
Windows Command Prompt:
```cmd theme={null}
set CUBIC_DISABLE_GIT_AI=true
npx @cubic-dev-ai/cli install -g
```
### Managing tracking after installation
Use `cubic stats` to enable, disable, or check the status of AI attribution tracking at any time:
```bash theme={null}
# Check current status
cubic stats status
# Disable tracking
cubic stats disable
# Re-enable tracking
cubic stats enable
```
`cubic stats disable` removes git-ai hooks and persists your preference so future upgrades will not re-enable it. `cubic stats enable` re-installs git-ai and clears the opt-out flag.
## Limitations
Usage is unlimited while the CLI is in alpha, subject to rate limits to ensure fair access for all users.
Because the CLI is optimized for speed and local iteration, it is less thorough than cubic's cloud PR reviews. If you need the most complete review, open or update a PR and rely on the cloud review as the source of truth.
# MCP server
Source: https://docs.cubic.dev/ide/mcp-server
Give your coding agent direct access to PR review issues, codebase documentation, scan results, scan issue triage, and review learnings.
cubic's MCP server connects your coding agent to cubic's data and workflows: PR review issues, AI-generated codebase documentation, codebase scan results, scan issue triage, and team review patterns.
The MCP server requires a cubic account with access to at least one repository. You must be a
member of the repository's installation to access its data.
## 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.
Existing API-key based MCP configs continue to work during the migration window, but new setup should not add an `Authorization` header or `cbk_` key.
## 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:
1. Open Cursor **Settings**.
2. Go to **Tools and MCP**.
3. In MCP, use **Home MCP Servers** or your project-specific MCP section.
4. Click **New MCP server**.
5. Add this to the config and save:
```json theme={null}
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp"
}
```
6. Click **Connect** and complete OAuth.
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}
cursor-agent mcp enable cubic
cursor-agent mcp login cubic
cursor-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`.
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. In Notion, ask a workspace admin to open **Settings** > **Notion AI** > **AI connectors** and enable **Custom MCP servers**.
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. Choose 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.
```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}
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 needed:
Skip this step if `pi-mcp-adapter` is already installed.
```bash theme={null}
pi install npm:pi-mcp-adapter
```
Run Pi's guided setup:
```bash theme={null}
pi-mcp-adapter init
```
Confirm the MCP 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.
## Available tools
| Tool | Description |
| :----------------------------- | :------------------------------------------------------- |
| `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 issue details including code context |
| `update_issue_status` | Update a scan issue triage status with optional feedback |
| `list_learnings` | List AI review learnings for a repository |
| `get_learning` | Get full details of a specific learning |
| `get_pr_issues` | Get all published issues for a pull request |
## Common prompts
* "Show cubic review issues on 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?"
## 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.
# Skills
Source: https://docs.cubic.dev/ide/skills
Trigger code reviews, fix PR issues, and query codebase context from your coding agent using natural language.
Skills are built-in capabilities that ship with cubic's agent integration. They activate based on what you ask your coding agent — no slash commands needed, just describe what you want in natural language.
## Install skills
First connect the [MCP server](/ide/mcp-server) with OAuth. Then install the skills and slash commands:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --skills-only
```
## Best prompts to start with
These prompts cover the workflows most teams use every day:
| Prompt | Best time to use it | What happens |
| :--------------------------------------------- | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
| `"review my code"` | Before you commit | Runs a local cubic review through your coding agent |
| `"loop until clean"` | When you want the agent to keep iterating | Re-runs local review, fixes issues, and repeats until the local pass is clean or the loop stops |
| `"check cubic comments"` | After cubic reviews a PR on GitHub | Fetches unresolved review comments, fixes worthwhile issues, commits, pushes, and resolves handled threads |
| `"how does auth work?"` | Before changing unfamiliar code | Uses cubic's codebase context to explain the system |
| `"what does this team care about in reviews?"` | When writing code for a new repo | Surfaces team coding patterns and conventions |
## Built-in skills
| Skill | Activates when | What it does |
| :-------------------- | :------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------- |
| **Check PR comments** | Working on a PR branch, saying "check cubic comments", "fix cubic issues", or "check PR comments" | Fetches unresolved cubic review comments, autonomously fixes worthwhile issues, commits and pushes changes, and resolves handled threads. |
| **Run review** | Saying "review my code" or doing a pre-commit check | Runs a local cubic AI code review via the CLI and groups issues by priority. Requires the [cubic CLI](/ide/cli-review). |
| **Codebase context** | Asking "how does X work?" or questions about architecture | Queries the cubic AI Wiki to provide architectural context about your codebase. |
| **Review patterns** | Writing or reviewing code | Pulls team-specific review learnings to apply your team's coding conventions and preferences. |
| **Cubic loop** | Saying "loop until clean" or "keep reviewing" | Iteratively runs cubic reviews, fixes issues, and re-reviews until clean or a max iteration count is reached. |
## Use the prompts by stage
* **Before you push**
Ask your coding agent to `"review my code"` or `"loop until clean"` to catch obvious issues early.
* **On an open pull request**
Ask `"check cubic comments"` after cubic finishes the GitHub review. The agent will fetch all unresolved threads, analyze them, and fix only issues that are real and worth addressing. It will then push the changes and automatically resolve the handled threads.
* **When learning the codebase**
Ask questions like `"how does auth work?"`, `"where is rate limiting handled?"`, or `"what does this team care about in reviews?"`.
For the step-by-step local-review flow and the copy-paste `AGENTS.md` / `CLAUDE.md` guidance, see [Local CLI review](/ide/cli-review).
## Slash commands
If you prefer explicit commands, use these. Claude Code uses `/cubic:...`. Other supported agents typically use `/cubic-...`.
| Command | Description |
| :------------------------------------------------------------------- | :--------------------------------------------------------------------- |
| `/cubic-run-review [flags]` or `/cubic:run-review [flags]` | Run a local cubic AI code review on uncommitted changes or branch diff |
| `/cubic-comments [pr-number]` or `/cubic:comments [pr-number]` | Show cubic's review comments on the current PR (auto-detects branch) |
| `/cubic-wiki [page-name]` or `/cubic:wiki [page-name]` | Browse AI-generated codebase documentation |
| `/cubic-scan [scan-id]` or `/cubic:scan [scan-id]` | View codebase security scan results and issues |
| `/cubic-learnings [learning-id]` or `/cubic:learnings [learning-id]` | Show team code review patterns and preferences |
The `/cubic-run-review` and `/cubic:run-review` commands require the cubic CLI. Use
`npx @cubic-dev-ai/cli install -g` on Windows or `curl -fsSL https://cubic.dev/install | bash` on
macOS and Linux. See [Local CLI review](/ide/cli-review) for setup details.
# 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
# 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
```
### 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.
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
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.