Features

CodePeel is an AI code review engine that analyzes every pull request for bugs, security vulnerabilities, performance issues, and architectural problems. Reviews are triggered automatically from GitHub PRs, manually from the VS Code extension, or programmatically via the MCP server. Every review produces inline comments on the exact lines that need attention, a walkthrough summary, a health score, and optional automation like auto-fix PRs and test generation.

---

Inline Comments on Your PR

When CodePeel reviews a pull request, it posts findings as GitHub inline comments directly on the lines that need attention. Each comment appears in the "Files changed" tab of your PR, positioned on the exact line where the issue was detected. Comments are posted incrementally as each analysis layer completes, so you start seeing results within seconds of the review starting.

Every inline comment follows a structured format designed for quick scanning and immediate action. The comment begins with a severity badge that tells you at a glance how serious the issue is, followed by a title with a relevant emoji to indicate the category. The body uses bullet-point sections to separate what the problem is, what impact it has, and what you should do about it.

When CodePeel can generate a concrete code fix, the comment includes a GitHub suggestion block. This renders as a green "Commit suggestion" button that lets you apply the fix with a single click, no copy-pasting required. Fixes must look like actual code (not prose instructions) and be 10 lines or fewer to qualify for a suggestion block. Comments also include a collapsible "Prompt for AI Agents" section containing a structured prompt you can feed to Copilot, Cursor, or Claude to apply the fix in your IDE.

Severity Badges

Comments with a "Quick win" badge (⚡) indicate issues where the fix is three lines or fewer, making them trivial to resolve.

Trivial (🔵) findings are stored in your CodePeel dashboard only. They are not posted as PR comments to keep noise low.

---

Walkthrough Summary

Every PR gets a walkthrough comment posted on the Conversation tab of your pull request. This is a collapsible section that provides a high-level overview of the entire review, giving reviewers context before they dive into individual findings.

The walkthrough includes a plain-English summary of what the PR does, a breakdown of findings by category (bugs, security, performance, best practices), a review effort score, and a health score. It also lists all files reviewed grouped by module, with a per-module finding count so you can see which areas of the codebase need the most attention.

The walkthrough is structured as follows:

• Commits — which commit SHA is being reviewed against which base
• Files reviewed — collapsible list of all files grouped by module
• Changes table — module-level breakdown showing file count and finding count per module
• Finding counts — table with counts for bugs, security, performance, and best practices
• Review effort — a 1-5 scale (⬤◯◯◯◯ to ⬤⬤⬤⬤⬤) indicating how complex the PR is to review
• Health score — aggregate quality score (0-100) with emoji indicator
• Inline comments count — total number of comments posted on the PR

Sequence Diagrams

For complex PRs, CodePeel generates a mermaid sequence diagram showing the logic flow of the changes. This diagram is appended to the walkthrough and renders natively in GitHub's markdown viewer. Only valid mermaid diagram types are accepted: sequenceDiagram, flowchart, graph, classDiagram, stateDiagram, erDiagram, gantt, pie, journey, gitgraph.

Sequence diagrams are enabled by default. To disable them, set in .codepeel.yml:

walkthrough:
  auto_sequence_diagram: false

Contextual Tips

When a review has two or more findings of the same category, CodePeel appends a contextual tip relevant to the dominant finding type. For example, if most findings are security-related, you might see:

💡 Tip: Consider adding automated secret scanning and dependency auditing to your CI pipeline.

---

Health Score

A 0-100 number representing overall code quality for a single review. The health score appears in the walkthrough comment on your PR and on the PR detail page in the dashboard. It gives you an instant signal about whether a PR is safe to merge or needs more work.

The score starts at 100 and deducts points for each finding based on severity. Caps prevent a burst of minor issues from tanking your score unfairly. For example, even if a PR has 20 minor findings, the maximum deduction from minor issues is capped at 15 points.

How it's calculated

The formula is:

healthScore = max(0, 100 - penalty)
penalty = min(50, criticals × 20) + min(30, highs × 10) + min(15, mediums × 4) + min(5, lows × 1)

What the score means

Use Pre-merge Checks to automatically block merges when the health score drops below your threshold or when specific conditions are met.

---

Analysis Layers

CodePeel runs four independent analysis passes in parallel on every PR. Each layer specializes in a different class of issues, and all four run simultaneously regardless of PR size. This parallel architecture means you get comprehensive coverage without waiting for sequential passes to complete.

Secret Scanning Layer

The secret scanning layer runs first and posts results within seconds, before any other analysis completes. It uses a two-pronged approach:

Regex-based scanning detects known secret patterns including AWS Access Keys, OpenAI/Stripe keys, GitHub tokens, Firebase API keys, JWTs, database connection strings, RSA private keys, and more. It also scans for injection vulnerabilities (SQL injection, timing attacks, PCI DSS violations), performance anti-patterns (N+1 queries, unbounded caches), and memory safety issues (unbounded list growth, caches without eviction).

TruffleHog integration provides an additional layer of entropy-based secret detection that catches secrets the regex patterns might miss. When TruffleHog is available in the environment, it runs alongside the regex scanner and results are deduplicated.

You can add custom secret patterns in your .codepeel.yml:

security:
  custom_patterns:
    - "MY_SECRET_[A-Z]{10}"
    - "INTERNAL_TOKEN_[a-f0-9]{32}"

AI Analysis Layer

The AI analysis layer is the core of CodePeel's review engine. It uses multiple AI providers for reliability, falling back if one is unavailable. The AI receives the full diff along with your configuration (custom instructions, expert rules, review profile) and produces structured findings with problem code, fix code, and explanations.

The AI is guided by strict severity criteria to avoid noise. Critical findings are reserved for security vulnerabilities, data loss, and crashes. The AI will not flag architecture opinions on files under 100 lines, generic "consider refactoring" suggestions without concrete fixes, or style preferences.

For large PRs, the diff is analyzed in sections and findings are aggregated and deduplicated across sections.

SAST Layer

The SAST (Static Application Security Testing) layer runs an AI-based pattern analysis focused specifically on CWE-classified security vulnerabilities. It operates independently from the AI analysis layer, providing a second opinion on security issues. Findings from SAST are deduplicated against AI findings using proximity matching (same file, within 3 lines).

Architecture Review Layer

The architecture review layer evaluates design patterns, modularity, complexity, and structural risks. It is automatically skipped when securityOnly: true is set in your configuration. Architecture findings use additional filtering to suppress noise:

• Architecture opinions on files under 120 lines are suppressed (enforced by an additional filter, separate from the 100-line threshold above)
• Findings are capped at 4 per file to prevent comment flooding
• Vague recommendations without concrete fixes are filtered out
• Findings within 3 lines of an already-posted SAST finding are deduplicated

---

Incremental Reviews

When you push new commits to an existing PR, CodePeel automatically re-reviews only the new changes. It will not repeat findings you have already seen, and it respects findings you have dismissed.

What happens on a new push

1. CodePeel detects the synchronize event (new commit pushed to the PR)
2. Fetches all existing CodePeel comments on the PR
3. Loads any findings you previously dismissed with @codepeel resolve
4. Only posts new findings on lines not previously commented
5. Updates the walkthrough summary with new totals

This is always enabled and requires no configuration. The incremental behavior uses file:line as the deduplication key, so if you push a fix for a previously flagged line, CodePeel will not re-flag it.

Dismissing Findings

If CodePeel flags something you disagree with, reply to the inline comment with:

@codepeel resolve

The finding is permanently dismissed for that PR. Even after new pushes, it will not be flagged again. You can also use @codepeel dismiss or @codepeel ignore this as alternatives.

See the full Chat Commands documentation for all available commands.

---

Finding Categories

CodePeel classifies every finding into one of four categories. Each category maps to a specific type of code issue and is displayed with a distinct icon in the walkthrough summary.

Review Types

In addition to categories, each finding is classified by review type which indicates the nature of the recommendation:

---

Quality Gates and Noise Reduction

CodePeel applies multiple layers of filtering to ensure you only see actionable, high-value findings. The goal is zero false positives and zero noise.

Slop Detection

Findings are automatically filtered if they contain vague, generic language without concrete fixes. A finding is classified as "slop" and removed if:

• The explanation is under 20 characters
• It contains two or more generic phrases like "consider refactoring", "could be improved", "add proper error handling"
• The problem code is a comment, less than 10 characters, or identical to the fix code
• The fix code contains placeholder markers like [insert, [your, or ...
• The title says "magic number" but the number is a legitimate constant (HTTP status codes, common timeouts, port numbers)

Architecture Noise Suppression

Architecture opinions are suppressed on files under 120 lines. Patterns like "single responsibility violation", "tight coupling", "should be split", and "dependency injection" are only flagged on files with substantial complexity where the feedback is actionable.

Per-File Caps

Findings are capped at 4 per file, prioritized by severity. This prevents comment flooding on files with many minor issues. Critical and high-severity findings always take priority over medium and low.

Confidence Scoring

For borderline findings, CodePeel may re-evaluate the finding to confirm it's worth surfacing. Low-confidence findings are suppressed. This catches hallucinations and false positives that pass the initial filters.

---

Deduplication

If multiple analysis layers flag the same issue on the same line, you only see one comment. CodePeel deduplicates across all engines using multiple strategies:

• Exact dedup: Same file:line key across AI, SAST, architecture, and secret scanning layers
• Proximity dedup: Findings within 3 lines of each other on the same file are consolidated (the higher-severity one wins)
• Content dedup: Identical comment text on the same file and line is collapsed
• Cross-engine dedup: SAST findings that overlap with architecture findings are suppressed

For secret scanning specifically, if more than 3 identical findings exist (same pattern type), only the first 2 are posted with a note listing the other locations.

---

Suggestion Blocks (One-Click Fixes)

When CodePeel identifies a fixable issue, the inline comment includes a GitHub suggestion block. Click "Commit suggestion" to apply the fix directly from the PR interface.

When suggestions appear

A suggestion block is included only when all of these conditions are met:

• CodePeel can generate a concrete, working code fix
• The fix looks like actual code (contains semicolons, braces, parentheses, imports, or assignments)
• The fix is 10 lines or fewer
• The fix is not prose instructions (does not start with "extract", "introduce", "consider", etc.)

What suggestions look like

const query = 'SELECT * FROM users WHERE email = ?';
const result = await db.query(query, [email]);

Want all fixes applied automatically as a separate PR? Enable Auto-Fix PRs (Pro and Max plans only).

---

Custom Rules

Custom regex rules let you enforce team-specific conventions that the AI might not catch on its own. Rules are defined in your .codepeel.yml and run as a dedicated enforcement pass, separate from the AI analysis.

Custom rules require a Pro or Max plan. On the free tier, rules defined in .codepeel.yml are silently skipped.

Defining rules

rules:
  - id: no-console-log
    pattern: "console\\.log\\("
    message: "Remove console.log statements before merging to production."
    severity: medium
    paths:
      - "src/**/*.ts"
    exclude_paths:
      - "src/**/*.test.ts"
    category: best-practice

  - id: no-raw-sql
    pattern: "\\$\\{.*\\}.*(?:SELECT|INSERT|UPDATE|DELETE)"
    message: "Use parameterized queries instead of string interpolation in SQL."
    severity: critical
    paths:
      - "**/*.ts"

Rule fields

Rules are capped at 50 per repository to prevent prompt bloat.

Regex safety: security.custom_patterns patterns are validated for ReDoS and rejected if they could cause catastrophic backtracking. Custom rules (rules field) are NOT validated for ReDoS — be careful with nested quantifiers in your patterns. The parser silently passes any string.

Context-aware matching

Custom rules include context-aware logic to reduce false positives. For example, if your rule flags direct database writes, CodePeel will automatically suppress the finding when the matched line is inside a transaction or batch block.

---

Pre-merge Checks

Pre-merge checks let you define quality gates that must pass before a PR can be merged. When a check fails, CodePeel posts a failure commit status to GitHub, which can block the merge if you have branch protection rules enabled.

Checks are configured in the dashboard and evaluated automatically after every review completes.

Available check types

How it works

1. CodePeel completes the review and calculates metrics
2. All enabled checks for your account are evaluated against the review metrics
3. Each check records a pass/fail event with details
4. If any check with error severity fails, a failure commit status is posted
5. Checks with warning severity are recorded but do not block the merge
6. Results are saved with the review for dashboard display

The commit status appears as codepeel/premerge in GitHub's checks tab. Link it to a branch protection rule to enforce merge blocking.

See the full Pre-merge Checks documentation for setup instructions.

---