prmarmot
CLAUDE.md10 starsChanged 40 days agoMITView on GitHub
PR Marmot is an open-source GitHub PR-review dashboard: a windowed native desktop app in Rust (GPUI + gpui-component), macOS + Linux, MIT, at github.com/oliver-kriska/prmarmot. Workspace: core/ (prmarmot-core — categorization/Note/transport/board layout/search grammar/change notices, no GPUI dep, golden-tested against the shell prototype), local/ (prmarmot-local — config file + attention state files + auth/session, shared by app and CLI), cli/ (prmarmot-cli — read-only My PRs / Review queue views as table/Markdown/JSON plus a watch NDJSON event stream for terminals and agents), ffi/ (prmarmot-ffi…
- Deletes or force-pushes
- Commits and pushes
In this repository2 other files it gives its agents.
- cut-releaseSkill
- verify-uiSkill
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
v1 is read-only + open-in-browser: No AI, no reviewer assignment, no merging, no Windows (full in/out list: HANDOFF §4).
- Distinctive: line 49
No perpetually animating spinner — GPUI renders on demand, and continuous animation defeats the idle-GPU property the framework was chosen …
- Distinctive: line 50
Don't pull in a runtime you don't use (a thread + channel may suffice over full tokio).
- Very specific: line 51
Always show "last synced Xm ago" + the live rateLimit{} budget.
- Distinctive: line 52
Keep transport, token source, and issue-link detection behind traits/config — no hard-coded issue prefixes.
- Very specific: line 62
Run: ./target/debug/prmarmot --repo owner/name (--review for the incoming queue).
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project state
PR Marmot is an open-source GitHub PR-review dashboard: a windowed native desktop app in Rust (GPUI + gpui-component), macOS + Linux, MIT, at github.com/oliver-kriska/prmarmot. Workspace: core/ (prmarmot-core — categorization/Note/transport/board layout/search grammar/change notices, no GPUI dep, golden-tested against the shell prototype), local/ (prmarmot-local — config file + attention state files + auth/session, shared by app and CLI), cli/ (prmarmot-cli — read-only My PRs / Review queue views as table/Markdown/JSON plus a watch NDJSON event stream for terminals and agents), ffi/ (prmarmot-ffi — UniFFI bindings so PR Marmot for iPad reuses core instead of reimplementing it; see ffi/README.md), and the root prmarmot GPUI binary. Presentation that both front ends must agree on (section order, stacks, notice priority) lives in core; wording/tone ports live in each front end. The project was named prboard through v0.5.3; preserve explicit historical migration references, but all active identity uses PR Marmot / prmarmot.
Where the build stands (2026-11-04, v0.20.0 shipped 2026-10-29; PR Marmot for iPad on the App Store since 2026-10-30, 1.0.1 live since 2026-11-04 under the store name "PR Marmot: Pull Request Board", https://apps.apple.com/us/app/pr-marmot/id6814076030): releases since v0.6.0 are Developer-ID-signed and notarized, published by the tag-only release.yml flow, which also updates the cask in oliver-kriska/homebrew-tap. The app has My PRs | Review queue | All open for one repository or all repositories, pinned repos, filters and user-invoked Load more, stack grouping and branch trees, watch/snooze and "changed since you looked" markers with notifications and a dock badge, copy-a-group sharing, editable Settings, and daily update checks. prmarmot-cli (since v0.7.0) prints the same views, pr, report (standup since a moment) and a watch NDJSON stream with --until exit codes; it ships inside the app bundle, the cask links it, and every install path uses one /Applications/prmarmot.app (v0.7.1). Milestones: v0.8 search chips, pickup age/is:stale, size bands, JSON Schemas under cli/schema/, completions; v0.9 sign-in without gh (device flow / token), the ffi/ crate for the iPad, core-owned section tone; v0.9.1–v0.11 gh optional, fine-grained-token limits worded in core, ignored-config banner; v0.12 All open, GitHub-side label:/author:, one name per section, user-set section order, header counts per open view; v0.13 folded sections, quick filters, Details beside the table; v0.14 "approved but can't merge yet", cancelled checks don't fail CI, refreshes kept inside GitHub's query time limit; v0.15 evidence behind the Note, commits since your review, agent/bot-authored PRs (is:agent), merge-queue position, multi-select, Rust 1.99 pinned; v0.16 whose turn an open thread is on (TURNS_QUERY), bot comments don't answer a review request, the all-repositories Review queue as two serial requests, issue-link problems shared with the iPad; v0.17 branch trees without native stacks, teammate threads wait on their author, failed checks open their runs; v0.18–v0.19 a repository switch restores its last rows and keeps its fetch, failed refresh retried by itself, the board at launch; v0.20 colour sets and the Glacier skin, keyboard snooze with Until tomorrow 09:00, reversible appearance preview, stale board data shown with its age, date-aware snoozes. HANDOFF.md's build log stops long before most of this; the post-gate features were built before a clean memory gate at Oliver's direction, and the v0.8.1 overnight soak (18.3 h) met the RSS thresholds and missed the physical-footprint ones because of a 5 s idle repaint fixed in v0.9.0 — see benchmarks/2026-09-16-memory-gate-v0.8.1.md; G0 passed on 2026-09-20 on a 37.4 h soak of the Homebrew v0.9.1 build — mean physical footprint 106.7 MB, p99 159 MB, slope −0.77 MB/h, 0.01 % of one core (benchmarks/2026-09-20-memory-gate-v0.9.1.md). One threshold was rewritten against the measurement, in the open: "(max − min) ≤ 25 MB" became "p99 < 200 MB", because one drawn frame holds ~23 MB per drawable and the range could only ever report failure; both numbers stay published.
ROADMAP.md is the public roadmap (linked from the pinned waitlist Discussion and the Ideas threads): ladder,
principles, gates, phase status, the evidence-ranked next-features list. The full private operating plan — prices,
competitor tactics, cross-session coordination, Apple/App Review tactics, research pointers — is
.claude/research/PLAN.md (gitignored). When a decision changes, update both; never paste private material into
ROADMAP.md.
Read HANDOFF.md first. It is the executive summary of the research plus the running build log (Step 0.x entries + the post-gate roadmap queue), written so a fresh session can start from it alone. Evidence behind every claim is in .claude/research/*.md (indexed in HANDOFF §6) — local-only since 2026-07-24: .claude/research/ and .claude/scriptorium/ are gitignored and were purged from public git history; never recommit them. Claims are tagged FACT / ASSESSMENT / OPEN QUESTION — keep that discipline; never fabricate a number where an OPEN QUESTION belongs.
Decisions already made — do not re-litigate
- Windowed desktop app, NOT a TUI (Oliver's product decision, 2026-07-24). The ratatui analysis in the UI-framework doc is a record of the alternative, not an option.
- UI: GPUI Fast + gpui-component (Oliver, 2026-11-10, for Eric's scroll jank: a scrolled frame went from ~6.9 to ~2.4 ms of main-thread CPU;
.claude/research/2026-11-10-scroll-smoothness.md).gpui-component = "=0.9.1"andgpui-base = "=0.9.1", both with thegpui-fastfeature, ongpui-fastandgpui-fast-platformpinned to=0.1.14(aliased asgpuiandgpui_platform); bump all four together, never one alone. GPUI Fast keeps a view's last frame until something it read changes: render code that reads the clock, anRc<RefCell>, aCellor a static must notify the view that draws it (the slow tick notifies the table too; the update dialog refreshes the window). When something looks stale, run withGPUI_VIEW_RETENTION=0to rule retention in or out. Bootstrap viagpui_platform::application()and wrap the view in componentRoot(since 0.9 it mounts the dialog, sheet and notification layers itself). The virtualized widget is nowDataTable+TableState+TableDelegate. The 0.5.1 instructions in historical research no longer apply to current code. Do not copy unpinned git-main snippets. - Data: shell out to
gh api graphqlbehind aGithubTransporttrait; one request per refresh, authored search starts at 60, review mode two 60-result aliases (requested plus candidates filtered to zero pending reviewer requests; the candidate search excludes PRs that request you, so none is fetched twice). Exception (Oliver, 2026-10-07): the Review queue across all repositories sends its two searches as two serial requests, and its Load more page too (Oliver, 2026-10-15) — both in one ran at 85–100 % of GitHub's cut-off and failed one run in three, each alone at about half of it (.claude/research/2026-10-06-review-all-repos-at-the-10s-limit.md). Every page by itself (Oliver, 2026-11-10, after All open showed 60 of 119): a window's refresh (fetch_view_with_progress) goes on to the next pages one request after another until no PR is left or a search holds 300 rows (five full pages, ten 30-row ones —BoardPagination::page_cap); a refused later page keeps the rows in and leaves Load more to retry.fetch_view(the CLI,--pages) stays page one. Measured live: EnaiaInc/enaia All open 119 PRs in 33 s, Involving me across all repositories 161 in 49 s (30-row pages). A request GitHub gives up on (its ~10 s cut-off: 502/504, "in time", a timeout or resource-limit GraphQL error —GhError::is_query_timeout) is retried once at 30 rows, a 30-row request that fails is sent once more unchanged (fetch::send_with_ids), and that view keeps 30-row pages, Load more included, until the scope changes or the app quits (BoardPagination::small_pages; Oliver, 2026-09-29 — server time, not points, is the limit;.claude/research/2026-09-29-github-api-efficiency.md). Every front end words a refused request withstatus::query_timeout_text(). One bounded follow-up after every page (Oliver, 2026-10-07, "let's try it and we will see"):TURNS_QUERYasks who spoke last on the open threads of at mostMAX_TURN_IDS(30) rows — your own PRs with unresolved threads, or Review-queue rows you already reviewed — so your reply clears your turn and the author's reply returns it (board::wants_turns/apply_turns,fetch::settle_turns); a refused follow-up is ignored and the board stays as GitHub counted it; measured 2 points per PR and 0.7–1.0 s for 9. All-repositories searches sort byupdated-desc; reviews and review threads read the newest end (last:). Show truncation; never fan out per-PR REST. Repository discovery separately uses paginateduser/repos, bounded at 1,000 entries/10 pages, merged with configured/current repos. - Refresh: default 5 min, hard floor 30 s (the "5 s floor" idea is wrong — math in the data-layer doc).
- Auth: the
ghCLI login by default (Oliver, 2026-09-18), behind aTokenSourcetrait; GitHub Device Flow with PR Marmot's own OAuth App (client ID built into core, no client secret anywhere) or a pasted token when there is noghlogin or when chosen explicitly ([auth] mode).auto= a token set explicitly (PRMARMOT_TOKEN, then a pasted PAT: Use a token /--with-token) → authenticatedghfor the host → a device-flow token → sign-in screen; theghCLI is a privileged OAuth app exempt from org OAuth-app restrictions and PR Marmot's app is not, which is whyghcomes first. Never change a sign-in default without an explicit decision from Oliver. - v1 is read-only + open-in-browser. No AI, no reviewer assignment, no merging, no Windows (full in/out list: HANDOFF §4).
- Distribution: macOS signed + notarized
.app— hard-required (Homebrew enforces Gatekeeper on casks from 2026-09-01; quarantine applies regardless of tap). Pipeline: Zed's cargo-bundle fork →codesign --options runtime→notarytool submit --wait→stapler staple→ hand-authored cask in own tap. cargo-dist cannot produce.app/cask. Linux:.debpreferred (Vulkan/fontconfig/xkbcommon runtime deps).
The memory gate — passed 2026-09-20
G0 is passed (benchmarks/2026-09-20-memory-gate-v0.9.1.md), so it no longer blocks anything and the
README may make a measured memory claim. It is re-run on a shipped build whenever the framework, the refresh
loop or the repaint path changes; the rest of this section is the standing procedure for that. Thresholds now:
mean physical footprint < 150 MB, p99 < 200 MB, slope ≤ 2 MB/h, idle CPU ≈ 0 %, all after hour 1; run
scripts/g0-verdict.sh over the two CSVs for the verdict.
The framework choice is validated by an overnight measurement, not assumed: idle RSS flat and < ~150 MB over 12–24 h, ~0 idle GPU. Tooling: scripts/spike-run.sh <owner/repo> (app + per-minute RSS sampler + caffeinate), or attach to an already-running instance with scripts/measure.sh <pid> + caffeinate -i -w <pid> (preferred — it measures the app as actually launched, e.g. from Spotlight); scripts/measure-summary.sh for the verdict; leaks/sudo powermetrics --samplers gpu_power for depth. While a gate run is live: no keystroke automation against any PR Marmot window (a focus race once quit the measured instance via its q handler) and never reinstall/replace /Applications/prmarmot.app (macOS can SIGKILL a running app whose signed binary is swapped). If a re-run fails, STOP and bring the numbers to Oliver — there is no pre-committed fallback framework, and a threshold is only rewritten by his explicit ruling, published with the number it failed on.
Behavioral spec
- The shell prototype at
~/.claude/skills/pr-board/scripts/pr-board.sh(+ itsSKILL.md) is the spec for the GraphQL query, categorization (action/await/draft), and Note logic. It is transcribed in full in.claude/research/2026-07-24-github-data-layer.md. The Rust port lives incore/src/board.rsand is pinned by golden tests:scripts/prototype-jq/holds the prototype's verbatim jq,scripts/gen-golden.shregeneratescore/tests/golden/, andcore/tests/parity.rsasserts field-for-field equality. If parity fails, fix the port, never the golden. - Name note: "PRFlow" /
~/Projects/pr_flowbelow is Oliver's own unreleased 2025 Rust+GPUI prototype that preceded this project. It is unrelated to the commercial product PR Flow at prflow.app. - Reference codebases on disk:
~/Projects/pr_flow(previous GPUI attempt — read itsSOLUTIONS_EXTRACTED.mdfor the unbounded-cache memory bug that killed it, and mine its gpui-component table/state code),~/Projects/agentrixand~/Projects/vibenalytics(shipped Rust TUIs, for patterns and distribution).
Guardrails (from the PRFlow post-mortem — encode from line one)
- Bound every cache: explicit
MAX_*+ FIFO eviction; no unboundedHashMap. - Clamp every rate-limit wait to
max(60).min(900); never sleep until a far-future reset. - No perpetually animating spinner — GPUI renders on demand, and continuous animation defeats the idle-GPU property the framework was chosen for.
- Don't pull in a runtime you don't use (a thread + channel may suffice over full tokio).
- Always show "last synced Xm ago" + the live
rateLimit{}budget. - Keep transport, token source, and issue-link detection behind traits/config — no hard-coded issue prefixes.
Building and testing
- Toolchain: the exact Rust version
rust-toolchain.tomlpins (1.99.1 since 2026-10-21) — rustup, cargo and every CI workflow install from that file, so this machine and CI compile with the same rustc; move to a newer Rust by changing that one line in its own commit aftermake verify+make check. The GPUI app's dependency manifests require at least 1.92 (minimum toolchain not tested).core/,local/, andcli/declarerust-version = "1.85", and CI'smsrvjob checks them with Rust 1.85 (RUSTUP_TOOLCHAIN=1.85, which is what overrides the toolchain file; locallyRUSTUP_TOOLCHAIN=1.85 cargo check --locked -p prmarmot-core -p prmarmot-local -p prmarmot-cli --all-targets) against the committedCargo.lock(ffi/is deliberately outside that promise — it only ever builds for Apple targets, which is why uniffi and its dependencies live there) — if a dependency bump fails it, pin the older dependency or raise all threerust-versions together (and the job's toolchain), never one alone. macOS needs the Xcode Metal Toolchain (xcodebuild -downloadComponent MetalToolchain) or gpui's shader build fails. cargo test -p prmarmot-core -p prmarmot-local -p prmarmot-cli— the fast suites (no GPUI compile); run after any change tocore/,local/, orcli/. The CLI's version is pinned equal to the app's by a unit test — bumpcli/Cargo.tomltogether with the root version.make checkis the quality gate = CI —cargo fmt --all --check+cargo clippy -p prmarmot-core -p prmarmot-local -p prmarmot-cli -p prmarmot-ffi --all-targets -- -D warnings+cargo testof the same four crates, pluscargo test -p prmarmot-core --no-default-features --features small-regex(the iOS build swaps the regex engine; both must agree). All fast, no Metal. Keep it green; CI (.github/workflows/ci.yml) runs exactly this on push/PR to main, enforces-D warnings, and adds the Rust 1.85msrvcheck.make fixauto-fixes;make lint-allclippies the whole workspace incl. the GPUI binary (needs Metal).make helplists targets.- Git hooks:
make hookssetscore.hooksPath=.githooks.pre-commitrunsmake checkbut only when.rs/Cargo.*are staged (docs-only commits stay instant; bypass with--no-verifyorPRMARMOT_SKIP_HOOKS=1).pre-pushrunsmake verify— the full-workspace gate incl. the GPUI binary (fmt --all --check+clippy --all-targets -D warnings+test --workspace), the only automated check the app binary gets since CI is core-only (needs Metal, slower; bypass withgit push --no-verifyorPRMARMOT_SKIP_HOOKS=1).commit-msgwarns (never blocks) when a subject isn't a Conventional Commit. - Changelog / "what's unreleased":
cliff.tomldrives git-cliff. Conventional-commit prefixes group intoCHANGELOG.md; unconventional commits are kept under "Other" (not dropped)..github/workflows/unreleased.ymlkeeps a draft "Unreleased" GitHub release synced with everything on main not in the latest tag;make unreleasedshows it locally;make changelogregeneratesCHANGELOG.md. Real releases use the fail-closed tag-only flow inpackaging/RELEASING.md; this workflow only manages the draft, so no conflict..github/dependabot.ymlfiles weekly cargo + actions bumps (prefixdeps→ 📦 Dependencies). cargo buildfor the dev binary;cargo build --release(LTO) for anything measured or shipped.- Run:
./target/debug/prmarmot --repo owner/name(--reviewfor the incoming queue). Config: TOML at~/.config/prmarmot/config.toml(repo/repos/refresh/theme/reviewers/issue_link); precedence CLI > env > file > cwd detection (see README). - Local .app:
make install(release build +scripts/bundle-app.sh) installs an ad-hoc-signed/Applications/prmarmot.app— the same path the Homebrew cask andinstall.shuse, so there is only ever one app (it removes an older~/Applicationscopy, and replaces a cask-installed app until the nextbrew upgrade); the fail-closed signed/notarized pipeline ispackaging/RELEASING.md. - Visuals:
src/design.rsowns the palette (apply_palette+apply_geometry+apply_skin, driven by theLookglobal; spec:.claude/research/2026-07-24-visual-design.md); it must be re-applied after everyTheme::change/sync_system_appearance, followed byTheme::sync_base—ThemePref::applydoes this. Status semantics render as themed dots + text, never raw emoji (core note strings keep their emoji; the UI strips them). - Screenshot verification gotcha: GPUI does not repaint occluded windows. Bring the window frontmost (osascript
set frontmost … to true) beforescreencapture, or you'll capture a stale first frame that looks like a hung fetch. .claude/research/2026-07-24-step0-build-findings.mdrecords where reality corrected the research (noDataTablein 0.5.1, MSRV 1.88, Metal Toolchain, ~4 min cold build) — read it before trusting the r2 docs on those points.- Historical release: the former
github.com/oliver-kriska/prboardidentity published a v0.1.0 pre-release (prboard-v0.1.0-macos-arm64.tar.gz, ad-hoc-signed app). Do not rewrite those historical assets. Current releases usegithub.com/oliver-kriska/prmarmot,prmarmot-vX.Y.Z-macos-arm64.tar.gz, and the signed/notarized tag-only workflow. Never install over/Applications/prmarmot.appwhile an instance is running/measured. - Git hygiene: history was rewritten on 2026-07-24 to purge
.claude/research+.claude/scriptorium(they're gitignored now). A plugin hook blocks baregit push --force— use--force-with-lease=<ref>:<expected-remote-sha>with an explicit SHA (after a local history rewrite the tracking ref is rewritten too, so the implicit lease is stale). Notegh release createtags exist only on the remote until fetched; raw.githubusercontent.com caches ~5 min after a push.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

