Claude Code Configuration

A reusable CLAUDE.md configuration that teaches Claude Code to collaborate with CodeRabbit, Cursor BugBot, Greptile, CodeAnt, and Graphite AI Reviews for automated PR planning, code review, and merge workflows — all driven from your terminal. Includes a full PM skill family for project orchestration across threads.

Table of Contents

• What You Get
• Getting Started
• Slash Commands
• Rule Files
• Hook Scripts
• Scripts Library
• Config Files
• GitHub Actions
• Architecture
• Documentation map
• Per-Project Override
• FAQ
• Troubleshooting
• Customizing
• Contributing
• License

---

What You Get

After setup, Claude Code will automatically:

• Plan before coding — Triggers @coderabbitai plan on new issues, builds its own plan in parallel, then merges both into one implementation spec before writing any code.
• Review locally, then on GitHub — Runs CodeRabbit CLI reviews before pushing (instant feedback, no PR noise). After PR creation, the reviewer chain is CodeRabbit primary, BugBot (Cursor) second tier, Greptile last resort, then self-review only if every reviewer is unavailable; CodeAnt and Graphite AI Reviews provide supplemental AI review signals.
• Verify and merge — Checks every acceptance criteria checkbox against the code, confirms CI is green, then squash-merges. The running worktree and branch are left intact and reaped out-of-band by /pm-clean.
• Orchestrate multi-agent work — Decomposes large tasks into phases (fix, review, merge) with health monitoring, handoff files, and heartbeat enforcement.
• Manage your project — 36 slash commands for backlog prioritization, OKR-aware ranking, daily standups, PR-fleet monitoring, and cross-thread orchestration.

Review ownership is sticky once a fallback tier takes over:

---

Getting Started

Prerequisites

Optional: Greptile — AI code reviewer used as a fallback when CodeRabbit and BugBot are unavailable. Install the GitHub App and configure via the Greptile dashboard.

Account identity: during setup, Claude must explicitly ask which email/account to use for git identity and for each CLI tool it authenticates (GitHub CLI, CodeRabbit, CodeAnt today — the checklist is extensible) — never assume one. See SETUP.md — Account identity for the checklist and where each credential is stored.

Install

Using an LLM to set this up? See SETUP.md — it has the same bash ./setup.sh command with LLM-friendly context.

Step 1: Clone

git clone https://github.com/auerbachb/claude-code-config.git
cd claude-code-config

Pick a permanent location — symlinks will point here.

Step 2: Run the installer

bash ./setup.sh

This single command handles everything:

1. Creates ~/.claude/skills/ directory
2. Merges settings from global-settings.json into ~/.claude/settings.json (preserves existing keys), including the Graphite plugin marketplace and enabled plugins when those keys are missing locally
3. Optionally runs gt repo init in this checkout when Graphite CLI (gt) is installed, creating .git/.graphite_repo_config so the Graphite plugin can auto-detect this repo (skipped quietly if gt is missing; setup fails if gt is present but gt repo init fails)
4. Sets up the skills worktree and symlinks (CLAUDE.md, rules, all skills)
5. Registers all hooks with correct paths
6. Installs the git pre-commit hook that blocks root-main commits
7. Verifies the installation and prints a pass/fail summary

The script is idempotent — safe to re-run at any time.

After upgrading or first enabling plugins, run /reload-plugins once inside Claude Code so the Graphite skills and MCP load.

Graphite CLI + Claude Code plugins (optional)

global-settings.json seeds extraKnownMarketplaces (the claude-code-graphite catalog) and enabledPlugins for graphite and graphite-mcp. That matches Anthropic’s team-marketplace pattern: Claude Code can discover those marketplaces/plugins and prompt you to install them after you trust the folder—explicit consent is required, and you may still need /plugin marketplace add manually if you skip the prompt or in setups where prompting is unreliable. Once installed to your scope, enabledPlugins from merged settings can enable the extensions without re-running marketplace commands every time.

Per-repo marker (not committed): The Graphite plugin detects repos via .git/.graphite_repo_config. Run gt repo init in each clone where you want stacked-PR context, or:

bash /path/to/claude-code-config/.claude/scripts/graphite-repo-init.sh /path/to/other-repo

Opt-out: Remove or set enabledPlugins entries to false in ~/.claude/settings.json, or disable the plugins under /plugin → Installed. Omitting Graphite CLI does not break this config — hooks and skills behave as before.

Step 3: Verify

ls -la ~/.claude/CLAUDE.md     # -> ~/.claude/skills-worktree/CLAUDE.md
ls -la ~/.claude/rules         # -> ~/.claude/skills-worktree/.claude/rules
ls -la ~/.claude/skills/       # each skill -> ~/.claude/skills-worktree/.claude/skills/

Set up CodeRabbit for a repo (per-repo)

1. Install CodeRabbit on the repo (via GitHub App settings)
2. Optionally add a .coderabbit.yaml to the repo root for custom review rules
3. The config auto-detects whether CodeRabbit is installed — without it, those sections are skipped

---

Slash Commands

All 36 commands are invoked as /command in a Claude Code session. They are defined as skill files in .claude/skills/ and symlinked globally.

Run /pm first to bootstrap the PM config, then use the other PM skills as needed. Workflow commands (/merge, /wrap, /go-on, etc.) work independently.

---

Rule Files

Rule files in .claude/rules/ auto-load alongside CLAUDE.md and define the detailed workflows. Each file’s own header block states its scope.

The canonical rule index — grouped by area (Issues & planning, Review & merge, Orchestration, Safety & hygiene) — lives in CLAUDE.md §Rule Files and is kept in sync by rule-lint.sh.

---

Hook Scripts

Hook scripts in .claude/hooks/ automate Claude Code session lifecycle events. All hooks are idempotent and fail-safe.

Hooks auto-register on every session start — no manual setup needed after the initial install.

For the full per-hook manifest (script name, event, purpose) and auto-registration mechanics see .claude/hooks/README.md. For the hook event sequence see ARCHITECTURE.md §Hook Lifecycle and ARCHITECTURE.md §Hook Auto-Registration.

---

Scripts Library

Shared helpers in .claude/scripts/ are used by skills, hooks, and review subagents for repeatable GitHub, git, and PM workflow operations.

See .claude/scripts/README.md for the script catalog — a category index linking one doc per category under .claude/scripts/docs/, each carrying a one-sentence purpose per script. For full contracts, arguments, and exit codes run the script with --help or read the script header.

---

Config Files

---

GitHub Actions

---

Architecture

CLAUDE.md, rules, and all skills are served through a skills worktree (~/.claude/skills-worktree/) — a git worktree pinned to main that decouples config availability from the root repo’s branch state. These symlinked assets stay available regardless of what branch the root repo is on.

The session-start-sync.sh hook keeps the worktree in sync with origin/main at the start of each session. New hooks added to global-settings.json are auto-registered without re-running setup.

For the full architecture reference — symlink topology, hook lifecycle, session lifecycle, multi-agent orchestration, review loop flowcharts, and design decisions — see ARCHITECTURE.md.

Mermaid diagram stubs (skills worktree, review pipeline, hook sequence) live under .claude/reference/diagrams/ and are filled in alongside doc updates.

---

Documentation map

Long-form material is split so rules + CLAUDE.md stay token-efficient (see the word-budget section in CLAUDE.md). Use this table to find the right doc.

Audits and research (reference, not rules): ai-review-tool-audit-2026-04.md, repo-audit-2026-05.md, graphite-stacked-prs-research-2026-05.md.

---

Per-Project Override

The global config applies to all projects. To customize per repo, copy files into the project:

cp CLAUDE.md /path/to/your/project/CLAUDE.md
mkdir -p /path/to/your/project/.claude/rules
cp -R .claude/rules/. /path/to/your/project/.claude/rules/

Claude Code loads project-level CLAUDE.md first, then falls back to ~/.claude/CLAUDE.md. The same precedence applies to .claude/rules/*.md.

Do not use project-level .claude/settings.json files for permissions. They interfere with the global wildcard and cause more re-prompting, not less. See Troubleshooting.

---

FAQ

Why does the config require worktrees? Without worktrees, all Claude Code sessions share a single working directory. If two agents work on the same repo, they overwrite each other’s edits. Worktrees give each agent its own isolated directory and branch. See ARCHITECTURE.md §Skills Worktree for the full rationale.

What’s the difference between local and GitHub reviews? Local reviews run the CodeRabbit CLI in your terminal — instant, no PR noise, no quota cost. GitHub reviews happen after PR creation. CodeRabbit is the primary merge-gate reviewer, BugBot and Greptile are fallbacks, and CodeAnt plus Graphite AI Reviews add supplemental PR review signals.

Does this work with CodeRabbit’s free tier? Yes. Rate limits in the config are tuned for Pro. Free tier limits are lower — you may want to increase polling timeouts.

What happens when CodeRabbit is slow or down? Local review times out after 2 minutes. GitHub review polling follows the sticky chain: CodeRabbit first, BugBot after CodeRabbit rate-limit/timeout, Greptile after BugBot timeout, then self-review only if all reviewers are unavailable. A self-review reduces risk but does not satisfy the merge gate.

Can I use this without CodeRabbit / BugBot / Greptile? Yes. The config auto-detects reviewer availability. If CodeRabbit is unavailable, Claude uses the next available reviewer tier: BugBot first, then Greptile if needed. Greptile remains optional. The PR workflow, branch naming, acceptance criteria, and squash-merge flow work regardless.

What is pm-config.md? A per-repo config bootstrapped by /pm. Stores team roster, OKRs, and infrastructure detection. Only needed for PM skills — the review workflow works without it.

---

Troubleshooting

Claude Code keeps asking for permission even with bypass enabled

Three independent causes — fix all that apply.

Cause 1: A project-level .claude/settings.json exists in the repo.

Project-level settings files override (not merge with) global settings. Even with "allow": ["*"] in both, the project file’s presence interferes.

Fix: Delete project-level settings files and rely on ~/.claude/settings.json:

find . -name "settings.json" -path "*/.claude/*" -not -path "*/.git/*" -delete

Related: anthropics/claude-code#17017, #13340, #27139.

Cause 2: Trust dialog flags reset on new worktrees.

Every worktree creates a new project entry in ~/.claude.json with trust flags set to false.

Fix: The trust-flag-repair.sh hook auto-repairs flags after every response. For manual repair:

python3 -c "
import json, os
path = os.path.expanduser('~/.claude.json')
with open(path) as f: data = json.load(f)
flags = ['hasTrustDialogAccepted', 'hasClaudeMdExternalIncludesApproved', 'hasClaudeMdExternalIncludesWarningShown']
total = 0
for proj in data.get('projects', {}).values():
    if not isinstance(proj, dict): continue
    for flag in flags:
        if not proj.get(flag): proj[flag] = True; total += 1
if total:
    with open(path, 'w') as f: json.dump(data, f, indent=2)
    print(f'Fixed {total} flag(s).')
else: print('All flags already set.')
"

Cause 3: Worktree-symlink topology (this repo only).

This repo’s global symlinks point back into itself, so worktrees see them as “external includes.” The trust-flag-repair.sh hook mitigates this after the first response. See .claude/rules/trust-dialog-fix.md for full details.

Upstream issues: #34437, #23109, #28506, #9113.

---

Customizing

The config is plain Markdown. Edit to match your workflow:

• Change branch naming — Modify the issue-N-short-description pattern in CLAUDE.md
• Adjust polling intervals — The 60-second interval and reviewer timeouts are in cr-github-review.md, bugbot.md, and greptile.md
• Adjust Greptile budget — Change the budget field in session-state.json (default: 40/day)
• Restrict autonomy — Add restrictions in CLAUDE.md for certain paths
• Customize PM config — Edit .claude/pm-config.md for team roster, OKRs, workflow rules

Contributing

Found an edge case or improvement? PRs welcome. This config evolved from real-world usage across multiple repos.

License

MIT