pr-cockpit: Instructions file for Codex

PR Cockpit contributor and agent guide

This repository is worked on by humans and coding agents alike. Leave it easier to operate than you found it.

Layout

• server/: the Bun server. GitHub ingestion, SQLite cache, mutation queue, HTTP API.
• ui/: the Svelte 5 front end (runes: $state, $derived, $props, $effect).
• shell/: the Electron shell. It only provides the macOS window, global hotkeys, and prcockpit:// links.
• relay/: the Cloudflare Worker that receives GitHub webhook events and hands them to a cockpit.
• scripts/: install, launch, update, and the pr-cockpit CLI.

Working here

• Always work directly on main and pull origin/main before starting work.
• Commit continuously in small, coherent increments and push every commit immediately to origin/main.
• Never create pull requests or feature branches for work in this project. This project-specific workflow overrides generic instructions to open a pull request.
• bun install at the repository root, in ui/, and in shell/.
• cd ui && bun run dev for a hot-reloading UI. It proxies /api to 127.0.0.1:4820, so it needs a server on that port. Run scratch previews with the installed UI Vite under Node; root bunx downloads unlocked dependencies, and Bun lacks the proxy’s socket.destroySoon.
• bun test server/<file>.test.ts for a targeted test. Prefer targeted runs over the whole suite while iterating.
• Screenshot harnesses render at 1600x1200; keep their default viewport and PNG dimension checks aligned.
• PR detail headers and tabs use the standard width; Conversation centers its 816px primary column and adjacent sidebar beneath them, and Files alone expands to full width.
• Agents is a conversation workspace, not a status dashboard: prioritize session discovery and transcript reading; keep history and logs secondary, because repeated badges and competing controls obscure the work.
• Whiteboard scroll zooms at the cursor; Space-drag pans. Seed layouts fit the canvas proportions. Only Arrange refreshes inbox-generated group membership, reflows, and removes empty sections, undoably; custom sections stay personal. Otherwise preserve positions. Show tool keys beside their labels.
• Verify landing-page search queries against live GitHub results; captured PR titles can disappear from the search index while the fixture remains valid.
• Match existing style. Keep the homepage dark and speed-first, with brief subtext and FAQ answers; link to details. Comments explain hidden constraints.
• Pull-request actions follow GitHub semantics: merge green, update neutral, and destructive actions red.
• Pins are bookmarks, not merge consent. Approved for safe merge is explicit PR-wide permission exposed as approvedForSafeMerge in CLI JSON; re-read it before merging, never grant it yourself, and retain all safety checks. Approval survives pushes but ends on revoke, close, or feature disable; replicas use the source's approval state.
• Cross-group inbox drops change the grouping's source: conventional-commit type or scope via the title mutation queue, or personal manual assignment. Keep draft markers, breaking markers, and the rest of the title intact. Computed status sections are never writable by dragging.
• Workflow jobs use commit-check semantics: green check for success, red cross for failure, orange spinner while active, and gray minus when skipped. Logs preserve ANSI colors and open at the bottom. Commit status icons and failing-check rows open Cockpit’s Actions tab at the exact commit and job; its selector covers the full mirror range, not GraphQL’s last 100 commits.
• Operational telemetry belongs on a dedicated Usage page in Settings, not among general controls; it keeps three days of hourly context and forecasts the active GitHub quota window.
• File status lives in the colored leading icon; moved files use a distinct move glyph, never a text badge beside the name. 1: - Agents mutate existing PRs through pr-cockpit; use its --body-file commands for exact multiline text, never gh or direct GitHub APIs.
• Agent reads share a per-PR 60-second GitHub revalidation window, including fresh/listen reads and --new-since queries. A newer webhook permits one immediate revalidation; concurrent reads share in-flight work. Cached responses retain their actual snapshot timestamp and freshness. With REST recording enabled, agent JSON's quota.hotPrs ranks personal core calls over the last 60 minutes by PR and dominant source; quota.identities[].hotPrs separates installation usage. Markdown and exhausted-quota errors identify the hottest PR for the affected credential.
• Keep examples, fixtures, benchmarks, and docs free of private company, product, repository, host, and infrastructure names; do not perform unrelated hosting or infrastructure work here. 2: COCKPIT_PROXY="build-server" # optional Cockpit replica source over SSH 3: # COCKPIT_PROXY="build-server" # replicate another Cockpit over SSH
• For manual app recordings, launch /Users/theo/dev/pr-cockpit; this pr-cockpit-v3 checkout is the legacy landing worktree.