Configuration

Customize how CodePeel reviews your code with a .codepeel.yml file in your repository root.

---

Do I Need a Config File?

No. CodePeel works out of the box with sensible defaults. You only need .codepeel.yml if you want to:

• Exclude files from review (generated code, lock files, vendor)
• Enforce team-specific rules (expert_rules)
• Add custom compliance rules with regex patterns (rules)
• Enable auto-fix or auto-test PRs
• Switch to security-only mode
• Add custom secret patterns
• Control which branches trigger reviews
• Skip reviews on WIP pull requests
• Disable walkthrough comments or sequence diagrams

If you're happy with the defaults, skip this page entirely. You can also configure most settings from the Dashboard Settings without touching YAML.

Ways to create .codepeel.yml

You don't have to write it manually. Three options:

Option 1: PR command — mention @codepeel init in any PR comment. CodePeel creates a PR 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: Webapp — go to Repositories, 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: CLI — run in your repo root:

npx @codepeel/mcp-server init-config

Requires CODEPEEL_TOKEN set in your environment. If you've already configured the MCP server, the token is already set.

---

Common Recipes

Security-focused review

Only report security issues — skip bugs, performance, and best practice findings:

securityOnly: true

This also skips the architecture review layer entirely.

Quiet mode (fewer findings)

Reduce noise for teams that prefer minimal feedback:

auto_review:
  profile: chill
ignoreFormatting: true

Skip generated files

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

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

Enforce team conventions

Add rules that the AI checks on every review:

expert_rules:
  - "Never use console.log in production code"
  - "All async functions must have error handling"
  - "Use Zod for runtime type validation"
  - "React components must use named exports"

Skip WIP pull requests

Prevent reviews on work-in-progress PRs:

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

If the PR title contains any of these keywords (case-insensitive), the review is skipped entirely.

Enable auto-fix and auto-test PRs

auto_fix:
  enabled: true
auto_test:
  enabled: true

See Auto-Fix docs and Auto-Test docs for details.

Add custom secret patterns

Detect your organization's custom secret formats. These patterns are regex — here's what each part means:

security:
  custom_patterns:
    # Match your internal API keys (format: MYAPP_KEY_ followed by 16+ characters)
    - "MYAPP_KEY_[A-Za-z0-9]{16,}"

    # Match Bearer tokens in code (shouldn't be hardcoded)
    - "Bearer [A-Za-z0-9\\-._~+/]+=*"

    # Match AWS-style access keys (starts with AKIA, followed by 16 uppercase chars)
    - "AKIA[A-Z0-9]{16}"

    # Match Stripe keys (starts with sk_live_ or sk_test_)
    - "sk_(live|test)_[A-Za-z0-9]{24,}"

How to write your own: Look at your real secrets and find the consistent prefix or format. For example, if your internal tokens always start with myco_ followed by 32 hex characters, the pattern is: "myco_[a-f0-9]{32}"

These are checked during instant secret scanning — flagged within seconds, before AI analysis even starts.

---

Config Priority

Settings merge in this order (later overrides earlier):

How merging works:

• ignore_paths — merged (dashboard paths + repo paths are combined)
• strictMode, securityOnly, ignoreFormatting — repo config overrides dashboard
• profile — repo config overrides dashboard
• expert_rules, custom_instructions — only from .codepeel.yml (not in dashboard)

---

Full Reference

# .codepeel.yml

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

---

Config Key Reference

Top-level keys

rules[] fields

walkthrough keys

auto_review keys

chat keys

security keys

auto_description keys

auto_test keys

auto_fix keys

---

Review Profiles

Set via auto_review.profile or in the dashboard under Settings → Review Preferences:

---

ignore_paths Patterns

Uses minimatch glob patterns:

Dashboard ignored paths and .codepeel.yml ignored paths are merged — you don't need to repeat dashboard paths in the YAML.

---

Expert Rules

Expert rules are injected directly into the AI prompt as "TEAM PREFERENCES". They're the most powerful way to enforce team conventions:

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"

Tips for effective rules:

• Be specific — "Use parameterized queries" is better than "Be careful with databases"
• Keep rules short — one clear instruction per line
• Don't exceed ~10 rules — too many dilutes the AI's attention

For ad-hoc rules that don't need version control, use @codepeel learn: in a PR comment instead.

---

Custom Compliance Rules

Unlike expert_rules (which are AI-interpreted suggestions), rules are pattern-based matchers that flag exact violations. They run during the SAST pass and produce deterministic results — if the pattern exists in the code, it's flagged. Every time.

How patterns work

The pattern field uses regex (regular expressions) — a way to describe text patterns. If you've never written regex before, don't worry. Here's how to read and write them:

Key symbols:

• \\. — a literal dot (without \\, dot means "any character")
• \\s* — zero or more spaces/tabs
• \\b — word boundary (matches the edge of a word)
• .* — 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"

Tip: Test your patterns at regex101.com before adding them. Paste your code in the test string, write your pattern, and see what highlights.

Ready-to-use rule examples

Copy these directly into your .codepeel.yml:

rules:
  # ─── Code Quality ────────────────────────────────────────────

  # Flag console.log left 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 TODO/FIXME comments that should be resolved
  - id: no-todo
    pattern: "//\\s*(TODO|FIXME|HACK|XXX)"
    message: "Resolve this TODO before merging, or create an issue for it"
    severity: low

  # Flag 'any' type in TypeScript (encourages proper typing)
  - id: no-any-type
    pattern: ":\\s*any\\b"
    message: "Avoid 'any' — use 'unknown' and narrow the type"
    severity: low
    paths: ["**/*.ts", "**/*.tsx"]

  # ─── Security ────────────────────────────────────────────────

  # Flag hardcoded passwords or secrets in assignments
  - 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"]

  # ─── Architecture ────────────────────────────────────────────

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

  # Flag importing from internal modules (enforce public API boundaries)
  - id: no-deep-imports
    pattern: "from ['\"]\\.\\./(.*)/internal"
    message: "Don't import from /internal — use the module's public API"
    severity: medium

  # ─── Team Conventions ────────────────────────────────────────

  # 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/**"]

  # Flag large files (likely needs splitting)
  - id: no-god-files
    pattern: "^.{0,}$"  # This won't work as a line-count check — see note below
    message: "This file is getting large — consider splitting it"
    severity: low

Note: Pattern rules match against file contents, not metadata like line count. For file-size rules, use expert_rules instead (the AI can judge file complexity).

Rule fields explained

Writing good rule messages

Bad: "Don't do this" Good: "Remove console.log before merging — use the Logger service from @/lib/logger instead"

A good message tells the developer:

1. What's wrong
2. Why it matters
3. What to do instead

How rules differ from expert_rules

Custom rules require Pro or Max plan.

---

Dashboard vs .codepeel.yml