@codepeel Chat

CodePeel provides an interactive conversational interface within GitHub pull requests. Mention @codepeel in any PR comment to ask questions about the code under review, teach CodePeel your team's conventions, correct false positives, and manage review findings — all without leaving the PR workflow.

What Makes This Different

Traditional code review bots require rigid command syntax. CodePeel uses natural language understanding to detect your intent from message content, not command prefixes.

Interact with CodePeel like a human reviewer:

• "we handle auth at the gateway level" → teaching a preference
• "why did you flag this?" → asking a question
• "good catch, fixing now" → acknowledgment

There is no rigid command syntax. CodePeel detects intent and, when it identifies a preference/learning, may append a hidden marker to its response. CodePeel strips the marker before posting, classifies the type, and saves the rule to your repository's learnings. Messages without a learning intent are answered without saving a rule.

IDE chat vs PR chat: The IDE/extension chat does not persist learnings automatically. Learning detection only happens in the PR conversation flow, where the saved rule is scoped to the owner/repo of the PR.

---

Getting Started

Mention @codepeel in any comment on a PR where CodePeel is installed:

@codepeel is there a potential race condition in the new handler?

CodePeel processes your message, loads context (full PR diff, file/line if replying to inline comment, saved preferences), and responds within 5–15 seconds.

Two interaction locations:

• PR conversation tab — general questions about overall changes
• Files changed tab — reply to specific inline review comments for targeted questions (provides file/line context)

---

Asking Questions

Most common interaction: asking about code, a finding, or the review. Any message not expressing a preference/correction is treated as a question.

About Specific Findings

@codepeel explain why this is flagged as a security issue
@codepeel is this actually exploitable if we use CloudFront in front of the API?
@codepeel what's the real-world impact of this race condition?

CodePeel responds with detailed explanation grounded in actual PR diff code — not generic answers.

About Architecture and Approach

@codepeel suggest a better approach for error handling here
@codepeel is this N+1 query a real concern at our scale?
@codepeel would it be better to use a transaction here instead of optimistic locking?

About the Review Itself

@codepeel why didn't you flag the missing null check on line 45?
@codepeel what's the difference between this finding and the one on line 23?

Response Quality

Concise (1–3 paragraphs), grounded in actual diff. References specific code, patterns, context. No generic advice.

Follow-up: Ask in a new comment. Each comment processed independently — no multi-turn conversation state within a thread.

---

Teaching Preferences

CodePeel learns from your feedback. When you correct a finding, state a convention, or tell it to stop flagging something, it automatically detects teaching intent and saves the preference for future reviews.

How It Works

No special syntax needed. Explain naturally:

@codepeel we handle rate limiting at the API gateway level, don't flag it on individual services
@codepeel this is a test key replaced at build time via environment injection — it's intentional
@codepeel actually nested try-catch is our pattern here for error isolation between parsing and validation
@codepeel the src/generated/ directory is auto-generated by our protobuf compiler — never flag issues there
@codepeel we use console.log intentionally in the debug/ directory for development diagnostics

When teaching intent detected:

1. Extracts core preference
2. Classifies learning type (preference, correction, suppression)
3. Saves to repository knowledge base
4. Confirms in reply with collapsible details

Learning Types

✅ Preference — positive convention to enforce:

• "We always use Zod for input validation in this project"
• "In this repo we use Uri.parse with queryParameters map instead of string interpolation"
• "Our convention is to use named exports, not default exports"

✏️ Correction — specific finding was wrong:

• "That finding is incorrect — the backend validates file types at the gateway"
• "This isn't a vulnerability because we use a whitelist of allowed paths"
• "The path traversal finding is wrong — our backend enforces directory boundaries"

🚫 Suppression — stop flagging a pattern:

• "Stop flagging console.log in debug utilities"
• "Don't flag hardcoded keys in test fixtures — they're mock values"
• "Ignore TODO comments, we track those in our issue tracker"

Confirmation Format

Got it — I'll stop flagging rate limiting on services behind the API gateway.

📝 Learning saved (🚫 Suppression)
> Do not flag rate limiting on individual services — handled at API gateway level.
> I'll apply this to future reviews in owner/repo.

When Learnings Are NOT Saved

• "Good catch, fixing now" → acknowledgment only (no learning saved)
• "Thanks, we'll address this in a follow-up" → acknowledgment
• "Makes sense" → acknowledgment
• "Can you explain more?" → question

CodePeel decides whether to save a learning based on the conversation context. It is not 100% deterministic — if a teaching message did not get saved, try rephrasing more explicitly (e.g. "we use X, not Y — please remember this") or use the learn: shortcut.

How Learnings Affect Future Reviews

Saved preferences applied to every subsequent review of the same repository:

• Teach "don't flag console.log in debug/" → future reviews won't flag console.log in that directory
• Teach "we use Zod for validation" → future reviews may flag code not using Zod where validation needed
• Correct a false positive → similar patterns won't be flagged in future PRs

Effect is cumulative — each learning makes future reviews more accurate for your codebase.

---

Shortcut Commands

Natural language is primary, but explicit shortcuts bypass AI for instant execution (1–2 seconds vs 5–15 seconds).

learn: and ignore: — Direct Rule Saving

@codepeel learn: Always use Uri.parse with queryParameters map instead of string interpolation for URLs
@codepeel learn: We use effect-ts for error handling, not try/catch
@codepeel learn: All API responses must include a requestId field for tracing

@codepeel ignore: console.log in debug utils is intentional
@codepeel ignore: Don't flag TODO comments as issues — we track them in Linear
@codepeel ignore: The hardcoded API URL in tests is a mock server address

Saves the rule immediately without invoking AI. The learn: shortcut stores the rule as a positive preference; the ignore: shortcut stores it as a suppression. Both are applied to all future reviews of the repository.

resolve and dismiss — Finding Management

When replying to a CodePeel inline review comment in Files changed tab:

@codepeel resolve

Also accepted: @codepeel dismiss. (@codepeel ignore this is treated as natural language, not a hardcoded shortcut, and may produce a learning rather than a strict resolve.)

What happens:

• Finding marked resolved in CodePeel database
• Won't be flagged again on subsequent pushes to this PR
• Resolved state stored per file path, line number, PR

Constraints:

• Only works on CodePeel review comments in Files changed tab (needs file/line metadata)
• Not in regular PR conversation comments
• New PR with same code may reappear (unless you also saved a learning)

When to use resolve vs teaching:

• resolve = finding valid but already fixed, or one-time exception
• Teach preference = pattern you never want flagged again

init and setup — Configuration Generation

@codepeel init

Generates .codepeel.yml from dashboard settings, creates PR with the file. Review and merge to activate per-repo config.

To regenerate from scratch (overwrite existing):

@codepeel reset config

Useful after changing dashboard settings.

See Configuration for all options.

---

Context and Intelligence

What the AI Receives

What the AI Does NOT Receive

• Full file contents — only diff (changed lines)
• Conversation history — each message processed independently
• Other PR comments — other reviewers' comments not included
• CI/CD results — test failures, build status not included
• .codepeel.yml configuration — used during automated reviews, not chat
• Code outside the diff — unchanged files/lines not visible

Tips for Better Responses

• Reply to inline comments — gives AI file/line context
• Include specifics — file names, function names, variable names
• Quote relevant code if discussing something outside the diff
• Ask one question per message — multiple questions may get partial answers

---

Preference Management

How Preferences Are Stored

All preferences saved via @codepeel chat (natural language or learn:/ignore:) stored in CodePeel database, associated with:

• Repository (e.g., owner/repo)
• User who saved it
• Type (preference, correction, suppression)
• Rule text
• Timestamp

Scope and Isolation

Preferences scoped per repository. Rule in owner/repo-a has no effect on owner/repo-b.

For cross-repository conventions:

1. Save same rule in each repository individually
2. Use .codepeel.yml with same expert_rules in each repo (version-controlled, portable)

Viewing and Managing Preferences

Navigate to Learnings in dashboard to:

• View all saved preferences grouped by repository
• See classification type for each rule
• See creation timestamp and author
• Delete individual rules
• Edit rule text

Capacity and Injection

• Reviews: All saved preferences are applied to every review for the repository. There is no cap on review injection.
• Chat: Only the most recent 5 preferences for the user are loaded into chat context. Older rules are still stored and still applied in reviews, just not in chat context.

If you find that older chat-relevant rules are not being honored, move them to expert_rules in .codepeel.yml (no injection limit, version-controlled, visible to the team).

---

Chat Learnings vs Configuration File

Recommended Strategy:

Use chat learnings for:

• Correcting false positives during review
• Quick one-off preferences discovered during development
• Personal conventions not applying to whole team
• Temporary suppressions ("ignore this until we refactor in Q3")

Use .codepeel.yml expert_rules for:

• Team-wide coding standards all reviewers should enforce
• Onboarding documentation ("this is how we do things here")
• Conventions surviving team member changes
• Rules needing PR review and approval

Both applied during the same review — they work together.

---

Real-World Examples

Example 1: Correcting a False Positive

CodePeel flags hardcoded API key in test fixtures:

🔴 Critical — Hardcoded credential detected in tests/fixtures/api.ts:7

Reply:

@codepeel those are mock API keys for our test environment, they don't work against any real service

Response:

Understood — since these are mock credentials used exclusively in test fixtures
and don't authenticate against any real service, they don't represent a security risk.

📝 Learning saved (🚫 Suppression)
> Hardcoded API keys in test fixtures are mock values — do not flag as credentials.

Future reviews won't flag similar patterns in test fixture files.

Example 2: Teaching a Convention

@codepeel in this project we use the Result type from neverthrow for error handling instead of try/catch — it's our team standard

Response:

Got it — I'll look for Result/neverthrow patterns instead of try/catch when
reviewing error handling in this repository.

📝 Learning saved (✅ Preference)
> This project uses the Result type from neverthrow for error handling, not try/catch.

Example 3: Asking About a Finding

@codepeel is this actually an N+1 issue? We're using DataLoader which batches these automatically

Response:

You're right — if DataLoader is configured for this resolver, the individual
`findById` calls within the loop will be automatically batched into a single
query. The N+1 pattern is only problematic without a batching layer.

However, I'd verify that the DataLoader instance is properly scoped to the
request lifecycle. If it's shared across requests, you could see stale cache hits.

📝 Learning saved (✏️ Correction)
> N+1 query patterns are acceptable when DataLoader batching is configured.

Example 4: Quick Rule via Shortcut

@codepeel learn: All database migrations must include a rollback function

Instant response (1–2 seconds):

📝 Preference saved for owner/repo:

> All database migrations must include a rollback function

I'll apply this to all future reviews.

---

Limitations

Context Window

AI receives full PR diff. For very large PRs (100+ files), context may be truncated.

Workaround: Reply directly to inline comment on the file you're discussing — ensures AI knows which file.

No Conversation Memory

Each @codepeel message processed independently. AI doesn't remember previous messages in thread. Include relevant context in new message if referencing previous exchange.

Resolve Scope

resolve/dismiss only works on CodePeel's own inline review comments (Files changed tab). Cannot use on:

• Regular PR conversation comments
• Comments from other bots/reviewers
• Comments on commits outside the PR

Learning Scope

Preferences per-repository. No global rules across all repositories. For cross-repo conventions, configure .codepeel.yml in each repo or use shared config template.

Rate and Quota

Each conversational message (questions, natural language) counts toward monthly review quota. Shortcut commands (learn:, ignore:, resolve, init) do not count — they don't invoke AI.

---

Integration with Auto-Fix

When CodePeel's automated review generates an Auto-Fix PR, chat integrates with the workflow.

Discussing Auto-Fix Results

After CodePeel posts Auto-Fix PR link:

@codepeel why did the auto-fix change the error handling pattern in auth.ts?
@codepeel the auto-fix looks correct but I'd prefer a different approach — can you explain the tradeoffs?

Teaching Fix Preferences

If auto-fix uses a pattern your team doesn't prefer:

@codepeel for SQL injection fixes, we prefer using our internal query builder (db.safe()) instead of raw parameterized queries

Influences both future review findings and auto-fix generation.

Requesting Specific Fixes

@codepeel how should I fix the race condition you found in the payment handler?
@codepeel what's the minimal change to fix the XSS vulnerability without breaking the markdown rendering?

---

Working with Teams

Shared Learning

When any team member teaches CodePeel a preference, it applies to all future reviews for that repository — regardless of who opens the PR:

• Senior developer teaches conventions once, all team members benefit
• New members get same review quality as veterans
• Institutional knowledge accumulates over time

Onboarding New Repositories

First install → no preferences → first few reviews may produce false positives. This is expected.

Recommended workflow:

1. First PR: Let CodePeel review normally. It will flag intentional patterns.
2. Correct false positives: Reply naturally to incorrect findings. Each correction teaches CodePeel.
3. State conventions: Proactively teach 3–5 key team conventions.
4. Second PR: Review quality improves significantly. Repeat corrections.
5. Steady state: After 3–5 PRs, CodePeel learns patterns, minimal false positives.

Alternative: Accelerate with .codepeel.yml expert_rules encoding team standards upfront.

Handling Disagreements

If two members teach conflicting preferences, most recent wins (only the last 5 are loaded in chat). Resolve by:

1. Delete conflicting rules in Dashboard → Learnings
2. Save single clear rule representing team consensus
3. Or move to .codepeel.yml for PR approval process

---

Advanced Patterns

Teaching Contextual Rules

Some rules only apply in specific contexts:

@codepeel in our API routes (src/routes/**), always flag missing input validation. But in internal services (src/services/**), input is already validated by the route layer — don't flag it there.

@codepeel console.log is fine in files under src/scripts/ and src/debug/ but should be flagged everywhere else

AI stores as-is and applies contextually during future reviews.

Bulk Teaching via learn:

@codepeel learn: We use pnpm, not npm or yarn
@codepeel learn: All API responses must include a correlationId header
@codepeel learn: Database queries must use the connection pool from src/db/pool.ts, never create direct connections
@codepeel learn: Error messages shown to users must not contain stack traces or internal details

Each saves instantly without AI call — efficient for establishing multiple rules.

Using Chat During Review Discussions

CodePeel works alongside human reviewers:

1. Human reviewer asks question about code
2. PR author unsure about security implications
3. Author asks @codepeel for analysis
4. CodePeel provides grounded answer based on actual diff
5. Team makes informed decision

Turns CodePeel into a reference tool during review discussions.

---

Troubleshooting

CodePeel Doesn't Respond

If no response within 30 seconds:

1. Check GitHub App installation — Settings → Installed GitHub Apps → CodePeel
2. Check permissions — CodePeel needs read access to PRs, write access to comments
3. Check quota — If exhausted, CodePeel responds with quota message. Silence = permissions/installation issue
4. Check PR state — Only responds on open PRs. Closed/merged PRs won't trigger.

Learning Not Saved

1. Check response — Look for "📝 Learning saved" collapsible section. Not there = AI didn't detect teaching intent.
2. Be more explicit — "don't flag X" or "we always use Y" are strong signals.
3. Use shortcut — @codepeel learn: [your rule] saves directly.

Incorrect Learning Saved

1. Go to Dashboard → Learnings
2. Find incorrect rule
3. Delete it — takes effect immediately

Response Quality Issues

1. Reply to inline comments — gives AI file/line context
2. Include specifics — file names, function names, line numbers
3. Quote relevant code — if discussing something not in diff
4. Ask one thing at a time — multiple questions may get partial answers

---

Security and Privacy

What Data is Processed

• Your message text sent to CodePeel servers
• PR diff fetched from GitHub via installed GitHub App
• Message and diff sent to AI model for processing
• AI response posted back as GitHub comment

Data Retention

• Messages: Not stored after processing. No chat history maintained.
• Learnings: Stored in database until deleted. Contain only preference text, not original conversation.
• Diffs: Not stored. Fetched on-demand, discarded after processing.

Access Control

Anyone who can comment on the PR can trigger @codepeel. CodePeel does not currently check GitHub collaborator permission level before responding, so read-only viewers and forks can technically interact. If you need stricter access control, restrict the GitHub App installation to specific teams at the org level.

---

FAQ

Can I use @codepeel in issues, not just PRs? Currently only responds to PR comments. Issue comments not supported (requires PR diff for context).

Does @codepeel work on draft PRs? Yes. Responds on both draft and ready-for-review PRs.

Can I undo a learning? Yes. Dashboard → Learnings → find rule → delete. Deletion immediate — next review won't include it.

How many learnings per repository? No limit on saved learnings. Reviews apply all rules. Chat only sees the most recent 5 for context. For more active rules, use .codepeel.yml expert_rules (no surface cap).

Does @codepeel respond in other languages? Responds in same language you use. Write in Spanish → responds in Spanish. Saved learnings should be in English for best results.

Can multiple people teach conflicting rules? Yes, most recent wins (last 5 loaded in chat). For team conventions, use .codepeel.yml with PR approval process.

Is there a way to see all available commands? There is no @codepeel help command. All available shortcuts are documented above: learn:, ignore:, resolve, dismiss, init, and reset config. This page (Chat) is the canonical reference.