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)
• Enable auto-fix or auto-test PRs
• Switch to security-only mode
• Add custom secret patterns
• Skip reviews on WIP pull requests

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:

security:
  custom_patterns:
    - "MYAPP_KEY_[A-Za-z0-9]{16}"
    - "Bearer [A-Za-z0-9-._~+/]+=*"

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

---

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 — All supported options

# ─── File Exclusions ───────────────────────────────────────────
ignore_paths:
  - "node_modules/**"
  - "*.lock"
  - "dist/**"
  - "vendor/**"

# ─── AI Instructions ──────────────────────────────────────────
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"

# ─── Review Behavior ──────────────────────────────────────────
strictMode: false          # Flag more issues, including nitpicks
securityOnly: false        # Only report security vulnerabilities
ignoreFormatting: true     # Skip style/naming/formatting issues

# ─── Walkthrough ──────────────────────────────────────────────
walkthrough:
  auto_sequence_diagram: true   # Generate mermaid logic flow diagrams

# ─── Auto Review ──────────────────────────────────────────────
auto_review:
  ignore_title_keywords:        # Skip review if PR title contains these
    - WIP
    - "DO NOT REVIEW"
  profile: balanced             # chill | balanced | assertive
  tone_instructions: ""         # Custom tone (e.g., "Be concise and direct")

# ─── Security ─────────────────────────────────────────────────
security:
  custom_patterns:              # Regex patterns for custom secret detection
    - "MY_API_KEY_.*"
    - "Bearer [A-Za-z0-9-._~+/]+=*"

# ─── Automation ───────────────────────────────────────────────
auto_description:
  enabled: true                 # Generate PR description summary
  postToGithub: false           # Post description as a PR comment

auto_test:
  enabled: false                # Generate test PRs for changes

auto_fix:
  enabled: false                # Generate fix PRs for findings

---

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.

---

Dashboard vs .codepeel.yml