Getting started with CodeCrab

• • A desktop app that reviews GitHub pull requests with AI.
• • It runs on your own tools: the GitHub CLI (gh) and Claude Code (claude), using your accounts.
• • It is read-only toward GitHub. It never posts comments, approves, or pushes. You copy what you want and paste it yourself.
• • It reads your local clone to understand the code and never edits it.

macOS

1. Download the .dmg for your Mac: Apple Silicon (M1 and newer) or Intel.
2. Open it and drag CodeCrab into Applications.
3. Open CodeCrab from Applications. The app is signed and notarized by Apple.

Windows

1. Download the .msi or .exe. If your browser says it is not commonly downloaded, choose Keep.
2. When you see Windows protected your PC, click More info, then Run anyway.
3. Finish the installer and open CodeCrab from the Start menu.

Updates

When a new version is ready, an Update to vX chip appears in the top bar. Click it, then Update now. The app restarts on the new version. Later hides it for 24 hours.

The top bar has three badges: gh, claude and jira.

Click an orange badge to open its setup card. Each command has a Copy button. When finished, click Re-check Status.

3.1 GitHub CLI — required

CodeCrab uses gh to list PRs, read diffs and read comments.

# Install GitHub CLIbrew install gh

# Install GitHub CLIwinget install --id GitHub.cli --source winget

No Homebrew or winget? Download the installer from cli.github.com.

# Sign in, then verify the sessiongh auth login
gh auth status

3.2 Claude Code — required

CodeCrab runs reviews through your local Claude Code, so it must be installed and signed in on this computer.

# Install Claude Codecurl -fsSL https://claude.ai/install.sh | bash

# Install Claude Codeirm https://claude.ai/install.ps1 | iex

Already use Node.js? You can install it with:

npm install -g @anthropic-ai/claude-code

Run Claude and complete the login in your browser:

claude

3.3 Jira — optional

Add Jira only if your team links tickets in PRs. It adds an Open KEY button and lets reviews use the ticket as the specification.

# Install Atlassian CLIbrew tap atlassian/homebrew-acli
brew install acli

On Windows, follow Atlassian’s Windows guide.

# Sign in and verify Jiraacli jira auth login --web
acli jira auth status

Each repo needs its GitHub URL and a local clone on this computer.

# Only if you do not have a local clone yetgit clone <repo-url>

Open Settings (gear icon) → Repositories.

Fast way: let CodeCrab find them

1. Click Find repositories. CodeCrab checks common folders and only reads them.
2. Review the list. Recommended repos have PRs waiting for you; On GitHub means verified; Not verified appears when gh is not ready.
3. Select the repos you want and click Add selected.

Manual way

1. Paste the GitHub URL, such as https://github.com/acme/web-app or acme/web-app.
2. Click Browse… to choose the local clone, or use Auto-find.
3. Click Add repository. Use the pencil icon later to fix its local path.

Skills are the instructions the AI follows. CodeCrab creates them for each repository from your actual code.

Open Settings → Skills by repository and select the repo under Active repository.

5.1 Review Profile — automatic

• • Generated once the repo has a local path. It scans the codebase, CI and conventions and may take a few minutes.
• • View Profile shows its rules. Evidence shows where each rule came from.
• • Use Regenerate after major changes. CodeCrab warns when a profile is 30+ days old.

5.2 Master Review Agent — always on

The main reviewer runs on every review. Click View Skill File to read it. Nothing needs configuring.

5.3 CodeCrab review skills

Extra review passes are generated independently after the Review Profile is ready.

Enable skills with their checkbox. View skill explains its scope and source. Regenerate rebuilds one skill without touching the others.

5.4 Reuse your own skills

Existing Claude Code skills in .claude/skills or ~/.claude/skills appear under Your own review skills. Select one to run it on every review.

1. Click Template prompt to create your local skill.
2. Copy the prompt and paste it into Claude Code inside your repo.
3. Let Claude create .claude/skills/review-peer-pr/SKILL.md.
4. Reopen the tab and select the new skill.

5.5 Additional notes

Add context every review should know, such as “we’re migrating off Redux” or “ignore the legacy folder,” then click Save & sync.

Language

Model

Appearance

Under Settings → Appearance, choose Small, Default, Large or Extra large text. Shortcuts: Cmd/Ctrl +, Cmd/Ctrl - and Cmd/Ctrl 0. Use the top-bar theme icon for light or dark mode.

Set the top switch to PR code review and choose the repository.

7.1 Find the PR

• • Assigned to Me: PRs where you are an assignee or requested reviewer. Start here.
• • Team PRs: every other open PR in the repo.
• • My PRs: PRs you opened.

Use search, status filters and Authors to narrow the list.

7.2 Run the review

1. Open a PR and click Start Review.
2. Watch progress in Live Console.
3. When it finishes, open PR Review Result.

7.3 Read the result

The verdict is Ready to Approve or Request Changes. Findings appear directly on relevant diff lines; general findings appear above the diff.

Every finding includes the Problem, Why it matters, Suggested Fix and a paste-ready Suggested PR Comment.

7.4 Act on a finding

• • Copy PR Comment copies the ready-to-paste comment.
• • Open on GitHub opens the exact line in the Files tab.
• • Investigate Finding opens a read-only deep dive with call traces, affected files and fix steps.
• • Use Re-run Review when new commits arrive.

Use this workflow to handle feedback reviewers left on your PRs.

1. Open My PRs and select your PR. CodeCrab syncs the diff and GitHub comments.
2. Inline comments appear on their lines. General comments are listed separately.
3. Choose Investigate comment for a read-only explanation and fix plan, or View on GitHub to reply.

Review local changes before pushing and catch problems before a teammate does. This workflow uses local git and never touches GitHub.

1. Switch the top toggle to Pre-push review.
2. Open the branch card to inspect your local diff, base branch and commits ahead.
3. Choose whether to include staged and unstaged changes.
4. Click Start Review.
5. Read findings and the Ready to Push or Request Changes verdict.
6. If code changes, use Re-run Review from the Outdated banner.

Select the skills used here under Settings → Pre-push. These can differ from your PR review skills.

First review checklist

Frequently asked questions