Configuration

Customize how CodePeel reviews your code directly from the CodePeel Web Dashboard. You can control review aggressiveness, ignore generated files, add custom instructions and team expert rules, and toggle automation features like auto-fix.

Configuration is entirely optional — CodePeel works with sensible, balanced defaults out of the box.

Configuration Hierarchy & Priority

CodePeel follows a clean two-tier configuration hierarchy:

VS Code Extension & MCP: Reviews performed through the VS Code extension or MCP server automatically inherit your repository-specific configuration or global account settings directly from the cloud backend.

Configuring via the Web Dashboard

1. Repository-Specific Configuration

Each connected repository can have its own tailored configuration:

1. In the CodePeel sidebar, click Repositories (/app/repositories)
2. Select your repository
3. Click the Repository Config button in the header
4. Edit your settings using either the Visual Form tab or the YAML Editor tab
5. Click Save Configuration

Your changes take effect immediately on all subsequent reviews — no git commits or pull requests required. If you ever want to remove a repository's custom override, click Revert to Global Defaults in the modal footer.

Visual Form Tab

The Form tab provides straightforward controls for everyday settings:

• Review Profile: Choose between chill, balanced (default), or assertive
• Strict Mode: Toggle stricter analysis criteria to catch subtle nitpicks and style suggestions
• Security-Only Mode: Limit reviews strictly to vulnerabilities, secrets, and security flaws
• Ignore Formatting: Suppress purely aesthetic, naming, or whitespace findings (enabled by default)
• Auto-Description: Automatically generate PR descriptions, with an option to post them to GitHub
• Auto-Fix (Pro/Max): Automatically generate fix pull requests for addressable findings
• Custom Instructions: Describe your framework, architecture patterns, and conventions (appended to every AI review prompt)
• Ignored Paths: Minimatch glob patterns (one per line) for files to exclude from reviews (e.g. tests/**, dist/**, *.lock)
• Expert Rules: High-priority team standards (one per line) interpreted contextually by the AI

YAML Editor Tab

The YAML tab provides a full code editor for power users:

• Edit the entire configuration as YAML with syntax highlighting
• Changes in the YAML tab automatically synchronize with the Form tab in real-time
• Built-in syntax validator detects errors before saving
• Direct access to advanced keys like rules (custom compliance regex) and security.custom_patterns

2. Global Account Settings

Located at /app/settings in the web dashboard sidebar. Global settings establish default review rules and automation toggles across all connected repositories in your account.

When a repository has its own repository-specific configuration saved, that repository's settings take precedence over your global account defaults.

Configuration Reference

You can customize your repository settings using the Visual Form or by providing YAML in the Repository Config editor:

# Repository Configuration — Full YAML reference

ignore_paths:
  - "node_modules/**"
  - "*.lock"
  - "dist/**"
  - "vendor/**"

custom_instructions: |
  This is a TypeScript monorepo using pnpm workspaces.
  We prefer functional patterns over class-based OOP.

expert_rules:
  - "Never use console.log in production code"
  - "All async functions must have error handling"
  - "Database queries must use parameterized statements"

rules:
  - id: no-console-log
    pattern: "console\\.log\\("
    message: "Remove console.log before merging"
    severity: medium
    paths: ["src/**"]
    exclude_paths: ["**/*.test.*"]
    category: quality

strictMode: false
securityOnly: false
ignoreFormatting: true

walkthrough:
  enabled: true
  auto_sequence_diagram: true
  include_affected_files: true
  risk_assessment: true
  max_length: 5000

auto_review:
  enabled: true
  auto_incremental_review: true
  base_branches: ["main", "master", "develop"]
  ignore_title_keywords: ["WIP", "DO NOT REVIEW"]
  profile: balanced
  tone_instructions: ""

chat:
  auto_reply: true

security:
  custom_patterns:
    - "MY_API_KEY_[A-Za-z0-9]{16,}"
    - "sk_(live|test)_[A-Za-z0-9]{24}"

auto_description:
  enabled: true
  postToGithub: false

auto_fix:
  enabled: false

Top-Level Keys

ignore_paths

An array of glob patterns specifying files to exclude from review. Uses minimatch syntax with the dot: true option, meaning dotfiles are matched. Patterns are tested against the file path relative to the repository root.

ignore_paths:
  - "node_modules/**"
  - "dist/**"
  - "*.lock"
  - "generated/**"
  - "*.min.js"
  - "vendor/**"
  - "**/*.snap"

Ignored paths configured for a repository exclude matching files across all reviews, including GitHub pull requests, the VS Code extension, and the MCP server.

custom_instructions

Free-text instructions appended to the AI prompt for every review. Use this to describe your project, technology stack, or review preferences. The AI reads these instructions and adjusts its analysis accordingly.

custom_instructions: |
  This is a TypeScript monorepo using pnpm workspaces.
  We prefer functional patterns over class-based OOP.
  The project uses Prisma for database access.
  All API routes must validate input with Zod schemas.

Keep instructions concise and specific. Vague instructions like "be thorough" have little effect. Specific instructions like "All database queries must use the repository pattern, not direct Prisma calls in route handlers" produce targeted findings.

strictMode

When set to true, the AI applies stricter criteria and flags more issues, including nitpicks and minor style suggestions that would normally be suppressed. Default is false.

strictMode: true

securityOnly

When set to true, only security vulnerabilities are reported. Bug, performance, and architecture findings are suppressed. The architecture review layer is skipped entirely, reducing review time. Default is false.

securityOnly: true

ignoreFormatting

When set to true (the default), style, naming, and formatting issues are suppressed. Set to false if you want the AI to flag formatting inconsistencies.

ignoreFormatting: false

Expert Rules

Expert rules are injected directly into the AI prompt as team preferences. They are the most powerful way to enforce conventions that require judgment -- the AI interprets them contextually rather than matching patterns literally.

expert_rules:
  - "Use Zod for all runtime type validation"
  - "React components must use named exports, not default exports"
  - "API routes must validate request body with a schema"
  - "Never use any type — use unknown and narrow"
  - "All database access must go through the repository layer"
  - "Error messages must not expose internal implementation details"

Each rule is a plain string. The AI reads all rules before analyzing the diff and flags violations it detects. Because the AI uses judgment, expert rules can express nuanced preferences that regex patterns cannot capture.

Tips for effective rules

• Be specific. "Use parameterized queries" is better than "Be careful with databases."
• Keep rules short. One clear instruction per line.
• Do not exceed approximately 10 rules. Too many dilutes the AI's attention and increases the chance of false positives.
• Focus on conventions that are hard to enforce with linters. If ESLint can catch it, use ESLint instead.

Expert rules are validated on save. Each entry must be a string. Non-string entries are skipped with a warning. expert_rules entries are capped at 30 per repo for IDE reviews and each rule is truncated at 500 characters. Expert rules can be managed directly in the Web Dashboard Repository Config modal (under either the Form or YAML tab). Custom regex matchers (the rules field, capped at 50 per repo) can be configured via the YAML tab in the Repository Config modal.

Custom Compliance Rules

Unlike expert_rules (which are AI-interpreted suggestions), rules are pattern-based matchers that flag exact violations. They run during a dedicated enforcement pass and produce deterministic results -- if the pattern exists in added lines, it is flagged. Every time. Custom rules require a Pro or Max plan. On the free tier, custom rules are silently skipped.

How rules work

Rules are evaluated against every added line in the diff (lines starting with +). The pattern field is a regular expression tested against each line individually. When a match is found, the rule's message is posted as an inline comment on that line.

Regex safety: Unlike security.custom_patterns (which are validated for ReDoS), the rules field has no ReDoS protection. The pattern is compiled and run as-is. Avoid nested quantifiers like (a+)+ and overlapping alternations like (a|b+)+ — they can cause catastrophic backtracking and hang your review. Keep patterns simple and test at regex101.com before committing.

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

Rule fields

Limits

• Maximum 50 rules per repository
• Pattern length capped at 200 characters
• Message length capped at 500 characters
• Path arrays capped at 20 entries each
• Patterns are validated for regex safety; invalid patterns are skipped with a warning
• Messages are sanitized to keep your rules on-topic

Writing regex patterns

The pattern field uses standard JavaScript regular expressions with the gi flags (global, case-insensitive). If you have never written regex before, here is a quick reference:

Key symbols:

• \\. -- literal dot (without \\, dot means "any character")
• \\s* -- zero or more spaces/tabs
• \\b -- word boundary
• .* -- any characters (zero or more)
• [A-Za-z0-9] -- any letter or number
• {8,} -- 8 or more of the previous thing
• (a|b) -- "a" or "b"

Test your patterns at regex101.com before adding them.

Example rules

rules:
  # Flag console.log in production code
  - id: no-console-log
    pattern: "console\\.log\\("
    message: "Remove console.log before merging — use a proper logger"
    severity: medium
    paths: ["src/**"]
    exclude_paths: ["**/*.test.*", "**/*.spec.*"]

  # Flag hardcoded secrets
  - id: no-hardcoded-secrets
    pattern: "(password|secret|apiKey|api_key)\\s*[:=]\\s*['\"][^'\"]{8,}"
    message: "Possible hardcoded secret — use environment variables instead"
    severity: critical

  # Flag HTTP URLs (should use HTTPS)
  - id: no-http
    pattern: "http://(?!localhost|127\\.0\\.0\\.1)"
    message: "Use HTTPS instead of HTTP for external URLs"
    severity: high
    exclude_paths: ["**/*.test.*", "**/*.md"]

  # Flag direct database calls outside repository layer
  - id: no-direct-db
    pattern: "db\\.(query|execute|raw)\\("
    message: "Use the repository layer — no direct DB calls in controllers"
    severity: high
    paths: ["src/controllers/**", "src/routes/**", "src/api/**"]

  # Enforce named exports in React components
  - id: named-exports-only
    pattern: "export default (function|class|const)"
    message: "Use named exports — default exports make refactoring harder"
    severity: low
    paths: ["src/components/**"]

Expert rules vs custom rules

Walkthrough Settings

The walkthrough is a summary comment posted on the Conversation tab of your pull request. It provides a high-level overview of the review including file breakdown, finding counts, health score, and optionally a sequence diagram.

walkthrough:
  enabled: true
  auto_sequence_diagram: true
  include_affected_files: true
  risk_assessment: true
  max_length: 5000

Setting enabled: false suppresses the walkthrough comment entirely. Individual inline findings are still posted. See Features for details on what the walkthrough contains.

Auto Review Settings

Controls when and how automatic PR reviews are triggered.

auto_review:
  enabled: true
  auto_incremental_review: true
  base_branches: ["main", "master", "develop"]
  ignore_title_keywords: ["WIP", "DO NOT REVIEW"]
  profile: balanced
  tone_instructions: ""

Review profiles

Skipping WIP pull requests

If the PR title contains any of the ignore_title_keywords (case-insensitive match), the review is skipped entirely. No comment is posted and no reviews are consumed.

auto_review:
  ignore_title_keywords:
    - WIP
    - "DO NOT REVIEW"
    - "[draft]"
    - "wip:"

Base branch filtering

Only PRs targeting branches listed in base_branches are reviewed. This prevents reviews on feature-to-feature branch merges or release branches you do not want reviewed.

Security Settings

Configure custom secret patterns that are checked during the instant secret scanning pass. These patterns run before AI analysis and produce results within seconds.

security:
  custom_patterns:
    - "MYAPP_KEY_[A-Za-z0-9]{16,}"
    - "Bearer [A-Za-z0-9\\-._~+/]+=*"
    - "AKIA[A-Z0-9]{16}"
    - "sk_(live|test)_[A-Za-z0-9]{24,}"

Patterns are regular expressions tested against every added line in the diff. They are validated for ReDoS safety (max 200 characters, no nested quantifiers). Use narrowly scoped patterns and test them against representative code. Read the security review guide for how to investigate resulting findings.

Chat Settings

Controls the behavior of the @codepeel mention in PR comments.

chat:
  auto_reply: true

When auto_reply is true, CodePeel responds to commands like @codepeel explain, @codepeel learn:, @codepeel ignore:, and free-form questions. Set to false to disable all chat interactions. See the Chat Commands documentation for the full list of available commands.

Auto Description Settings

Controls automatic PR description generation.

auto_description:
  enabled: true
  postToGithub: false

When postToGithub is true, the generated description is posted as a comment on the PR. When false, it is only visible in the CodePeel dashboard.

Auto Fix

This feature generates a separate pull request with addressable fixes applied. Requires a Pro or Max plan.

auto_fix:
  enabled: true

When enabled, auto-fix runs after the main review completes. The generated PR targets the same branch as the original PR and includes only the fixes, making them easy to review and merge.

Common Recipes

Security-focused review

Only report security issues. Skips bugs, performance, and architecture findings:

securityOnly: true

Quiet mode (fewer findings)

Reduce noise for teams that prefer minimal feedback:

auto_review:
  profile: chill
ignoreFormatting: true

Strict mode (more findings)

Catch everything including nitpicks:

strictMode: true
ignoreFormatting: false
auto_review:
  profile: assertive

Skip generated files

Exclude auto-generated code, build output, and dependencies:

ignore_paths:
  - "node_modules/**"
  - "dist/**"
  - "*.lock"
  - "generated/**"
  - "*.min.js"
  - "vendor/**"
  - "**/*.g.dart"
  - "coverage/**"

Monorepo with multiple packages

Use custom instructions to describe your project structure:

custom_instructions: |
  This is a pnpm monorepo with packages in packages/.
  Each package has its own tsconfig.json.
  Shared types are in packages/shared/src/types.
  API routes are in packages/api/src/routes.

ignore_paths:
  - "packages/*/dist/**"
  - "packages/*/node_modules/**"

Disable walkthrough but keep inline comments

walkthrough:
  enabled: false

Only review PRs to main

auto_review:
  base_branches: ["main"]

Configuration Options Comparison

Troubleshooting

Changes in Web Dashboard not appearing on PR

1. Configuration changes saved in the Web Dashboard apply to new reviews. If a PR was reviewed prior to updating settings, push a new commit to trigger a re-review with updated settings.
2. Verify you clicked Save Configuration and saw the green confirmation indicator in the modal.

YAML syntax errors

If your YAML has syntax errors, CodePeel falls back to default settings and posts a warning. Common mistakes:

• Missing quotes around strings with special characters or glob patterns
• Incorrect indentation (YAML uses spaces, not tabs)
• Using yes/no instead of true/false for booleans
• In the Web Dashboard, the YAML tab validates your syntax in real-time before saving.

Rules not firing

If your custom rules are not producing findings:

1. Verify you are on a Pro or Max plan (custom rules are silently skipped on Free)
2. Check that the pattern is valid regex (test at regex101.com)
3. Verify the paths globs match the files you expect
4. Remember that rules only match added lines (lines starting with + in the diff)
5. Check if the match is being suppressed by the context-aware transaction check

Expert rules being ignored

Expert rules must be a list of strings. In the Web Dashboard Form tab, simply enter one rule per line. In YAML:

# Correct
expert_rules:
  - "Never use any type"
  - "Always handle errors"

Frequently Asked Questions

Does configuration affect VS Code extension and MCP reviews?

Yes. When you run a review from the VS Code extension or MCP server, it automatically inherits your repository-specific configuration or global account settings from the cloud backend.

Can I revert a repository back to global defaults?

Yes. Open the Repository Config modal for that repository and click Revert to Global Defaults in the footer. This removes the custom override so the repository inherits from /app/settings.

Are custom rules checked on IDE reviews?

Yes. Custom rules (the rules field) are enforced on IDE reviews from the VS Code extension and MCP server, as well as GitHub PR reviews.

What happens if my regex causes catastrophic backtracking?

Patterns are validated before execution. If a pattern is detected as potentially causing ReDoS (catastrophic backtracking), it is rejected with a warning. Keep patterns simple and avoid nested quantifiers like (a+)+.

Can I disable reviews for specific PRs without changing the config?

Yes. Add any of the ignore_title_keywords to your PR title (default: "WIP" or "DO NOT REVIEW"). You can also convert the PR to draft — CodePeel does not review draft PRs by default.

How do I see what config CodePeel is using for a review?

You can view review details and findings directly in your dashboard. The walkthrough comment on GitHub also notes any active review profile or custom rule counts.

Related Documentation

• Features -- Analysis engine and finding categories
• Security -- Custom secret patterns and security scanning details