Configuration

Customize how CodePeel reviews your code with a .codepeel.yml file in your repository root. This file controls which files are reviewed, what rules are enforced, how aggressive the analysis is, and which automation features are enabled. Configuration is optional -- CodePeel works with sensible defaults out of the box.

---

Do I Need a Config File?

CodePeel works without any configuration. The default behavior provides a balanced review profile, ignores formatting issues, and runs all analysis layers (secret scanning, AI analysis, SAST, and architecture review). You only need a .codepeel.yml if you want to customize this behavior.

Common reasons to add a configuration file:

• Exclude files from review (generated code, lock files, vendor directories)
• Enforce team-specific conventions with expert_rules
• Add deterministic compliance rules with regex patterns
• Enable auto-fix or auto-test PR generation
• Switch to security-only mode for sensitive repositories
• Add custom secret patterns for your organization
• Control which branches trigger reviews
• Skip reviews on work-in-progress pull requests
• Disable or customize walkthrough comments

If you are satisfied with the defaults, you can also configure most settings from the Dashboard Settings without touching YAML. Dashboard settings apply to all your repositories, while .codepeel.yml applies only to the repository where it lives.

Ways to create .codepeel.yml

You do not have to write the file manually. Three options are available:

Option 1: PR command. Mention @codepeel init in any PR comment. CodePeel creates a pull request with the config file based on your dashboard settings. If .codepeel.yml already exists, use @codepeel reset config to overwrite it with fresh defaults.

Option 2: Dashboard. Go to Repositories in the sidebar, click the menu on a repo, and select Generate Config. The YAML is copied to your clipboard. Paste it as .codepeel.yml in your repo root and commit.

Option 3: MCP. Run in your repo root:

npx -y github:codepeel/mcp-server init-config

This command fetches your dashboard settings and learned rules, then generates a .codepeel.yml file in the current directory. It requires CODEPEEL_TOKEN set in your environment. See the MCP Server documentation for details.

---

How It Works

When a pull request is opened or a review is triggered, CodePeel loads configuration from multiple sources and merges them into a single effective config. The merge follows a strict priority order where more specific sources override less specific ones.

Loading sequence

1. Built-in defaults are applied first (balanced profile, formatting ignored, all layers enabled)
2. Dashboard settings from your user account are loaded when you sign in (ignored paths, strict mode, review profile, custom instructions)
3. .codepeel.yml is fetched from the repository root via the GitHub API (using the commit SHA being reviewed)
4. Local config (IDE only) -- when reviewing from the VS Code extension or MCP server, a workspace-local .codepeel.yml is read and merged on top of the dashboard config. For expert_rules, this is capped at 30 entries and applied after dashboard rules. For ignore_paths, the local paths are appended to the dashboard paths — they are not replaced. Other fields from the local YAML override their dashboard counterparts when set.

Merge behavior

Different fields follow different merge strategies:

Validation

CodePeel validates your configuration file on every review. If issues are found, warnings are posted as part of the review comment:

• YAML syntax errors -- the file cannot be parsed; defaults are used
• Unknown keys -- typos or unsupported fields are flagged with a link to this documentation
• Type mismatches -- for example, strictMode: "yes" instead of strictMode: true
• Invalid regex patterns -- rules with broken regex are skipped with a warning
• Invalid profile values -- must be chill, balanced, or assertive

Warnings appear at the top of the walkthrough comment so you can fix them in the same PR.

Always-ignored files

Regardless of your configuration, CodePeel always ignores changes to .codepeel.yml and .codepeel.yaml themselves. This prevents the config file from triggering findings about itself.

---

Config Priority

Settings merge in this order (later overrides earlier):

---

Full Reference

# .codepeel.yml — Full configuration 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_test:
  enabled: 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"

For PR reviews, dashboard ignored paths and .codepeel.yml ignored paths are merged -- you do not need to repeat dashboard paths in the YAML file. For IDE/webapp reviews (VS Code, MCP), the repo YAML overrides the dashboard paths entirely. If you rely on dashboard-level ignore paths, repeat them in .codepeel.yml to keep behavior consistent across surfaces.

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 load. 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. The rules field (custom regex matchers) is a separate field, capped at 50 per repository. Both are version-controlled in .codepeel.yml and are not exposed in the dashboard.

---

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, rules defined in .codepeel.yml 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). See the Security documentation for pattern writing guidance, safety rules, and examples.

---

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 resolve, 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 and Auto Test

These features generate separate pull requests with fixes or tests applied. Both require a Pro or Max plan.

auto_fix:
  enabled: true

auto_test:
  enabled: true

When enabled, these features run after the main review completes. The generated PRs target the same branch as the original PR and include only the fixes or tests, 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"]

---

Dashboard vs .codepeel.yml

---

Troubleshooting

Config file not being picked up

If your .codepeel.yml is not being applied:

1. Verify the file is in the repository root (not in a subdirectory)
2. Verify the file is named exactly .codepeel.yml (not .codepeel.yaml, though both are supported)
3. Verify the file is committed to the branch being reviewed (CodePeel fetches it via the GitHub API at the commit SHA)
4. Check the walkthrough comment for config warnings -- they appear at the top if issues were detected

YAML syntax errors

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

• Missing quotes around strings with special characters
• Incorrect indentation (YAML uses spaces, not tabs)
• Using yes/no instead of true/false for booleans

Validate your YAML at yamllint.com before committing.

Rules not firing

If your custom rules are not producing findings:

1. Verify you are on a Pro or Max plan (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 an array of strings. Common mistakes:

# Wrong — single string instead of array
expert_rules: "Never use any type"

# Wrong — objects instead of strings
expert_rules:
  - rule: "Never use any type"
    severity: high

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

Unknown key warnings

If you see "Unknown keys in .codepeel.yml" warnings, you have a typo or are using an unsupported field. The valid top-level keys are:

ignore_paths, custom_instructions, expert_rules, rules, strictMode, securityOnly, ignoreFormatting, walkthrough, auto_review, chat, security, auto_description, auto_test, auto_fix

Common typos: ignorePaths (should be ignore_paths), strict_mode (should be strictMode), security_only (should be securityOnly).

---

Frequently Asked Questions

Does the config file affect VS Code extension reviews?

Yes. When you run a review from the VS Code extension, it reads .codepeel.yml from your workspace root and sends it along with the review request. Your custom instructions, expert rules, ignore paths, and all other settings are applied to IDE reviews just as they are to GitHub PR reviews.

Can I have different configs for different branches?

The config 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 is useful for having stricter rules on main than on feature branches.

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, not just GitHub PR reviews. The same regex matching and context-aware suppression logic applies.

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 use draft PRs -- CodePeel does not review draft PRs by default.

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

The walkthrough comment includes config warnings if any issues were detected. For a full view of the effective configuration, check the review detail page in your dashboard which shows the merged config that was applied.

---

Related Documentation

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