Frequently Asked Questions
This page covers the most common questions about CodePeel, organized by topic. For detailed documentation on specific features, follow the links to the relevant docs pages.
General
What is CodePeel?
CodePeel is an AI-powered code review tool that analyzes every pull request for bugs, security vulnerabilities, performance issues, and architectural problems. It posts inline comments on GitHub PRs with findings and suggested fixes, works via a VS Code extension for pre-push reviews, and integrates with AI coding agents through an MCP server.
Reviews are triggered automatically when a PR is opened or updated. Multiple analysis layers run in parallel: secret scanning, AI-powered analysis, SAST (static application security testing), and architecture review. Results appear as inline comments on the exact lines where issues were detected.
What languages does CodePeel support?
CodePeel works with all programming languages. The AI analysis engine handles any language that appears in a Git diff, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, Dart, and more. Language detection is automatic based on file extensions in the diff.
The auto-test generation feature has explicit framework detection for TypeScript/JavaScript (Jest/Vitest), Python (pytest/unittest), Go (testing), Rust (cargo test), and Dart/Flutter (flutter_test). Other languages receive AI-generated tests in the detected framework style.
How accurate are the reviews?
CodePeel prioritizes precision over recall. The system would rather miss an issue than flood you with false positives. Multiple quality gates filter out noise: slop detection removes vague findings, architecture opinions are suppressed on small files, and per-file caps prevent comment flooding.
If you want more findings, enable strictMode: true in your configuration. If you want fewer, set auto_review.profile to chill. You can also train the AI over time using learnings to suppress recurring false positives.
How fast are reviews?
All four analysis layers (secret scanning, AI analysis, SAST, architecture review) run in parallel. Secret scanning posts within 1-3 seconds. The full review completes in 15-30 seconds for small PRs and 30-90 seconds for large ones.
Most reviews complete within 30–90 seconds. Very large or complex diffs may take a few minutes.
See Features for details on each layer.
Is my code stored or used for training?
No. CodePeel processes your code only to generate the review. Diffs are sent to the AI analysis engine, processed, and discarded after the review completes. Your code is never stored permanently and is never used for model training.
The only data that persists is the review metadata (findings, health score, timestamps) stored in your dashboard. The actual source code is not retained.
Setup and Installation
How do I install CodePeel?
- Sign up at codepeel.com (free, no credit card required)
- Install the GitHub App at github.com/apps/codepeel
- Select which repositories to enable
- Open a PR -- CodePeel reviews it automatically
For the VS Code extension, search "CodePeel" in the Extensions panel and click Install. For the MCP server, see the MCP documentation.
Do I need an API key from OpenAI or another provider?
No. CodePeel uses its own AI infrastructure. You do not need to bring your own API key. The system routes through multiple AI providers for reliability and falls back automatically if one is unavailable.
Can I use CodePeel on private repositories?
Yes. All plans including Free support both public and private repositories with no limit on the number of repos. The only restriction on the Free tier is the 30 reviews per month quota.
Does CodePeel work with GitHub Enterprise?
Currently, CodePeel supports github.com only. GitHub Enterprise Server support is not available at this time.
Can I install CodePeel on my organization?
Yes. Visit github.com/apps/codepeel and install it for your organization. Organization admins can approve the installation and select which repositories to enable.
What permissions does the GitHub App need?
The GitHub App requires:
- Pull requests: Read and write (to post comments and commit statuses)
- Contents: Read (to fetch file content for fixes and configuration)
- Commit statuses: Read and write (for pre-merge checks)
- Webhooks: To receive PR events
Configuration
Where do I put .codepeel.yml?
In the root of your repository, at the same level as package.json or README.md. The file is fetched via the GitHub API at the commit SHA being reviewed, so it must be committed to the branch.
See the Configuration documentation for the full reference.
Do I need a configuration file?
No. CodePeel works with sensible defaults out of the box. You only need .codepeel.yml if you want to customize behavior (exclude files, add rules, enable automation, etc.). Most settings can also be configured from the dashboard without touching YAML.
Can I have different settings for different branches?
The configuration file is read from the commit being reviewed. If you have different .codepeel.yml content on different branches, each branch uses its own version. This allows stricter rules on main than on feature branches.
However, the base_branches setting controls which target branches trigger reviews, not which source branches are reviewed.
How do I skip review for a specific PR?
Include a keyword from ignore_title_keywords in the PR title. The default keywords are "WIP" and "DO NOT REVIEW" (case-insensitive). You can customize these in your configuration:
auto_review:
ignore_title_keywords:
- WIP
- "DO NOT REVIEW"
- "[draft]"
You can also include "[draft]" (or any custom keyword) in the title to skip review without needing the GitHub draft state.
How do I exclude files from review?
Add glob patterns to ignore_paths in your .codepeel.yml:
ignore_paths:
- "node_modules/**"
- "dist/**"
- "*.lock"
- "generated/**"
- "**/*.min.js"
You can also set ignored paths in the dashboard under Settings. Dashboard paths and YAML paths are merged (combined).
Billing and Usage
Is there a free tier?
Yes. The free tier includes 30 reviews per month on unlimited repositories (public and private). No credit card is required. All core features are included: inline comments, walkthrough summaries, security scanning, VS Code extension, and MCP server.
What costs a review?
Every interaction that triggers AI analysis consumes from your monthly quota. GitHub PR reviews consume 1-5 reviews based on diff size. VS Code extension reviews, MCP tool calls (review_code, fix_code, ask_codepeel), auto-fix, and auto-test each consume 1 review. The check_credits MCP tool is free. See Billing for the complete breakdown.
Do unused reviews roll over?
No. Your monthly quota resets to 0 on the 1st of each month. Unused reviews do not accumulate.
Do team members each need a subscription?
Yes. Each developer subscribes individually. There is no organization-level billing or team plan. Each team member gets their own quota (500 reviews/month on Pro). Reviews are deducted from the PR author's CodePeel account; if the author is not a member of the installation, the installation owner is charged instead. See Team Billing for the full table.
What happens when I run out of reviews?
New PR reviews are not processed. A comment is posted on the PR explaining that the quota is exceeded, with a link to upgrade. Reviews resume automatically when your quota resets on the 1st of the next month, or immediately if you upgrade your plan.
What are the rate limits?
Rate limits prevent burst usage and are independent from your monthly quota. The IDE and MCP endpoints share these per‑endpoint limits: 20 requests/minute for review/fixes/summarize, 15 requests/minute for chat. If you hit the rate limit, a comment is posted with the wait time and the review processes automatically when a slot opens. See Billing for details.
Features
What is the health score?
A 0-100 number representing overall code quality for a single review. It starts at 100 and deducts points for each finding based on severity (critical: -20, high: -10, medium: -4, low: -1), with caps per severity to prevent unfair scoring.
| Score | Risk level |
|---|---|
| 80-100 | Low risk -- safe to merge |
| 60-79 | Moderate risk -- review findings |
| 40-59 | High risk -- significant issues |
| 0-39 | Critical risk -- do not merge |
See Features for the complete formula.
What are pre-merge checks?
Quality gates that run after every review and post a GitHub commit status. You can block merges when security issues are found, bug count exceeds a threshold, or critical findings are detected. Configure them in the Pre-merge Checks dashboard page.
What is the difference between expert_rules and custom rules?
expert_rules are AI-interpreted suggestions injected into the prompt -- the AI uses judgment to decide when they apply. rules are deterministic regex pattern matchers that flag exact violations every time the pattern appears. Expert rules are available on all plans; custom rules require Pro or Max. See Configuration for the full comparison.
How do learnings work?
Learnings teach CodePeel your codebase conventions. When you add a learning (via PR comment, VS Code extension, or dashboard), it is stored per-repository and injected into the AI prompt on future reviews. Confirmed learnings are enforced as team preferences. Ignore learnings suppress false positives.
Add a learning via PR comment:
@codepeel learn: Always use Zod schemas for API validation
@codepeel ignore: Don't flag TODO comments
See Learnings for the full documentation.
Does auto-fix work automatically?
Auto-fix is opt-in and disabled by default. When enabled (auto_fix.enabled: true), it creates a separate PR with all fixable findings applied after each review. It requires a Pro or Max plan. See Auto-Fix for details.
Does auto-test work automatically?
Auto-test is also opt-in and disabled by default. When enabled (auto_test.enabled: true), it generates unit tests for your PR changes and opens a separate PR. It detects your language and testing framework automatically. Requires Pro or Max. See Auto-Test for details.
VS Code Extension
Does the extension work with Cursor, Windsurf, or other VS Code forks?
Yes. The extension is compatible with any VS Code fork that supports the Extension API version 1.85 or later. The "Fix with AI" feature specifically detects Cursor's composer and chat commands for native integration.
Does the extension require a GitHub App installation?
No. The VS Code extension works independently with any Git repository, regardless of hosting provider (GitHub, GitLab, Bitbucket, Azure DevOps, or self-hosted). The GitHub App is only required for automatic PR reviews on GitHub.
Do IDE reviews use the same quota as PR reviews?
Yes. All review sources draw from the same monthly pool. A VS Code extension review consumes 1 review, identical to an MCP review_code call.
How do I authenticate the extension?
Click "Sign In" in the CodePeel sidebar. Your browser opens to the authentication page. After signing in, the extension receives a token via a local HTTP callback. No manual code copying is required. See VS Code Extension for details.
MCP Server
What AI agents work with the MCP server?
Any MCP-compatible client: Kiro, Claude Code, Cursor, Cline, Roo Code, Augment, Windsurf, Codex, Goose, Zed, and others. See MCP Server for setup instructions for each.
Do I need a separate API key for the MCP server?
You need a CodePeel API token (starts with cpk_), which you create in Settings > API Tokens. This is different from your login credentials. API tokens do not expire unless you set an explicit expiration or revoke them manually.
Can I use the MCP server in CI/CD?
Yes. You can run the MCP server in any environment with Node.js 18+ and a CODEPEEL_TOKEN environment variable:
git diff origin/main...HEAD | CODEPEEL_TOKEN=$TOKEN npx -y github:codepeel/mcp-server review
Security
Can I disable security scanning?
No. Security scanning is always enabled on every review. You cannot disable the secret scanning, SAST, or AI security analysis layers.
securityOnly: true skips the architecture review pass entirely (the other layers — AI analysis, SAST, secret scanning — still run). Use this when you only want security-relevant findings reported, e.g. on legacy code where architecture suggestions would be noise.
Does CodePeel detect secrets in Git history?
No. CodePeel only scans the diff of the current PR (added lines). It does not scan repository history. Use dedicated tools like GitHub's secret scanning for historical detection.
How do I add custom secret patterns?
Add regex patterns to your .codepeel.yml:
security:
custom_patterns:
- "MYAPP_KEY_[A-Za-z0-9]{16,}"
- "myco_[a-f0-9]{32}"
These run during instant secret scanning and produce findings within seconds. See Security for details.
Troubleshooting
Reviews are not triggering
If CodePeel is not reviewing your PRs:
- Verify the GitHub App is installed for the repository (check Settings > Integrations on GitHub)
- Check that the PR targets a branch in
base_branches(default: main, master, develop) - Ensure the PR title does not contain an
ignore_title_keywordsmatch (default: "WIP", "DO NOT REVIEW") - Verify your review balance is not exhausted (check the billing page)
- Check the webhook delivery log in your GitHub repository settings
Inline comments are on the wrong line
CodePeel resolves line numbers from the diff hunk headers. In rare cases, line numbers may be slightly off for large files or files with many changes. The problemCode snippet matching usually corrects this, but edge cases exist with heavily modified files.
Review is taking too long
Large PRs (over 2000 lines of diff) may take up to 90 seconds. If reviews consistently time out:
- Break large PRs into smaller ones
- Use
ignore_pathsto exclude generated files, lock files, and build output - Consider using staged changes mode in the VS Code extension for incremental reviews
Too many false positives
If you are seeing too many irrelevant findings:
- Set
auto_review.profiletochillfor minimal findings - Enable
ignoreFormatting: trueto suppress style issues - Add ignore rules for recurring patterns:
@codepeel ignore: Don't flag X - Use learnings to train the AI on your conventions
- Add specific files to
ignore_pathsif they consistently produce noise
A review failed with an error
Check the CodePeel dashboard for error details. Common causes:
- Credit balance depleted -- upgrade or wait for monthly reset
- Rate limit hit -- wait for the per-minute limit to reset
- Diff too large -- the 50,000 character limit was exceeded for AI analysis. The 35,000-character limit is for SAST and auto-test only, not AI analysis.
- GitHub API error -- temporary GitHub outage, retry by pushing a new commit
- Payment failed -- update your payment method at the billing page
"Token expired" errors in the MCP server
Use a cpk_ API token from Settings → API Tokens, not a session cookie from browser sign-in. Session cookies expire after about an hour. API tokens do not expire unless you set an explicit expiration date.
Pre-merge check not blocking merges
For pre-merge checks to block merges, you need both:
- A check with
errorseverity enabled in the CodePeel dashboard - Branch protection rules on GitHub requiring the
codepeel/premergestatus
Without both configured, check failures are informational only.
Comparison with Other Tools
How does CodePeel compare to GitHub Copilot code review?
CodePeel provides deeper analysis with four independent layers (secret scanning, AI analysis, SAST, architecture review), custom rules enforcement, pre-merge checks, auto-fix PRs, auto-test generation, and a learning system. It works as a standalone tool that does not require GitHub Copilot.
How does CodePeel compare to SonarQube?
SonarQube is a self-hosted static analysis tool focused on code quality metrics. CodePeel is a cloud-hosted AI-powered reviewer that provides contextual analysis, natural language explanations, and suggested fixes. CodePeel requires no infrastructure setup and works immediately after installing the GitHub App.
How does CodePeel compare to CodeRabbit?
Both are AI-powered PR review tools. CodePeel differentiates with multiple AI providers for reliability, MCP server integration for AI agents, VS Code extension for pre-push reviews, and custom regex rules enforcement. Both offer inline comments, walkthrough summaries, and learning systems.
Data and Privacy
Where is my data stored?
Review metadata (findings, health scores, timestamps) is stored encrypted. Payment data is managed by Polar. No source code is stored permanently.
What data does CodePeel access?
CodePeel accesses:
- PR diffs (to analyze code changes)
- File contents (to apply fixes and read
.codepeel.yml) - Repository metadata (name, owner, branch info)
- PR metadata (title, author, target branch)
All access is scoped to the permissions granted by the GitHub App installation.
Can I delete my data?
Yes. You can delete your account from the Settings page. This removes all stored data including review history, learnings, API tokens, and subscription information. Repository-level data (learnings, review records) is also deleted.
Is CodePeel SOC 2 compliant?
CodePeel is not currently SOC 2 certified. CodePeel runs on SOC 2 compliant cloud infrastructure. For enterprise compliance requirements, contact support.
Related Documentation
- Getting Started -- Initial setup guide
- Features -- Complete feature reference
- Configuration --
.codepeel.ymlreference - Billing -- Plans, quotas, and pricing
Plans and Features Matrix
For a complete breakdown of features by plan tier, see the Feature Comparison table in Billing.
Common Workflows
Self-reviewing AI code with MCP
Have your AI agent call review_code on its own output before presenting it to you. The agent writes code, reviews it, fixes any issues, and delivers clean results. Works with any MCP-compatible agent. See MCP Server for detailed examples.
Pre-commit review with VS Code
Stage your files, select "Staged changes" mode in the CodePeel sidebar, and click "Review Changes" to catch issues before committing. See VS Code Extension for details.
Automated quality gates
Enable pre-merge checks with error severity, configure branch protection to require codepeel/premerge, and enable auto-fix for automated remediation. See Pre-merge Checks for setup instructions.
Getting Help
Where can I report bugs?
File issues at github.com/hexivine/codepeel/issues.
How do I contact support?
Use the public contact form at codepeel.com/contact, or open a support ticket from inside the dashboard at /app/support. Email support directly for urgent issues. Select your issue category (bug report, review issue, billing, feature request, or general).
Where can I see the changelog?
The VS Code extension changelog is available in the extension's CHANGELOG.md. Product updates are announced through the dashboard and email notifications for subscribed users.