research

The Repo Page: what converts a visitor into a star in the first 5 seconds

Jul 14, 2026

Lens: the GitHub repo page as a conversion funnel. A stranger lands from HN / X / a "show me your setup" thread, and decides in ~5 seconds whether to (a) keep reading, (b) star, or (c) bounce. This doc reverse-engineers the READMEs + repo metadata of real high-star dev tools, extracts the shared skeleton, and ends with a concrete repo-page spec for Claude Mission Control.

Method: read the actual READMEs (raw markdown, not summaries) and gh api metadata of 18 repos. Local clones at ~/Developer/reference-repos/; remote via gh api repos/<r>/readme -H "Accept: application/vnd.github.raw". Every claim below is tied to a named repo. [UNVERIFIED] marks anything not directly read.


0. TL;DR — the three laws + the three highest-ROI moves

The 5-second law. A visitor's first screen (before any scroll) must answer three questions, in this order: (1) What is this? (one line) → (2) Does it actually work / what does it look like? (a demo) → (3) How do I get it? (one copy-paste command). Every repo that converts well nails all three above the fold. Every repo that "succeeds anyway" without them (ripgrep with no image, cline with no demo) is coasting on a reputation a new repo does not have.

The demo-is-the-hero law. The single highest-weight element on the page is a motion demo of the product doing its actual job, placed above the fold. jesseduffield/lazygit (80k★) and charmbracelet/gum (24k★) lead with an animated GIF of the tool in use; winfunc/opcode (22k★, the Claude Code GUI) leads with a screenshot + embedded video. The repos that bury or omit it (junegunn/fzf hides its demo behind a YouTube link ~line 500; Aider-AI/aider buries install behind 9 feature blocks; cline/cline ships no visual at all) succeed despite the README, on word-of-mouth.

The reputation-buffer law. 80k-star repos can open with sponsor ads (lazygit), merch ads (fzf), or a demoted plain-text title (ripgrep) and still win — they have a reputation buffer absorbing the friction. A launch-day repo has zero buffer, so it must be stricter about the first screen than the famous repos are.

Highest-ROI moves for Claude Mission Control specifically (current README is text-only, zero images, and leads with swift build):

  1. Add a hero GIF above the fold — a 10–15s autoplay loop of the Attention Strip flipping a session to BLOCKED and re-sorting it to the top. This is the "which of my 8 agents needs me now" money moment; nothing else in the category shows it.
  2. Replace the swift build quickstart with a visitor install — a downloadable .app release (and later a brew cask, like CodexBar). swift build is the contributor path; the visitor wants to run it, not compile it.
  3. Set the repo metadata — a scannable GitHub description, 10–15 topics, a 1280×640 social-preview image, and a LICENSE file (the repo currently has none, so no license badge is even possible).

1. The dataset (18 repos mined)

Repo GitHub description (verbatim) Hero element What I drew from it
oven-sh/bun 93.6k "Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one" Centered PNG logo + clean H1 12 topics; "all-in-one" legible tagline; joke speed:fast badge → founder tweet
junegunn/fzf 81.5k ":cherry_blossom: A command-line fuzzy finder" Static banner image (no H1 text) Anti-pattern: merch ads above fold; real demo = YouTube link ~line 500
jesseduffield/lazygit 80.1k "simple terminal UI for git commands" Animated GIF demo (after a sponsor block) Best "tired of X" hook; per-feature GIFs (×13); anti-pattern: 3 sponsor blocks are the literal first pixels
BurntSushi/ripgrep 65.9k "ripgrep recursively searches directories for a regex pattern while respecting your gitignore" Plain text (no image on first screen) Proof-by-benchmark-table (real timings vs ag/grep); crisp descriptive description
cline/cline 64.4k "Autonomous coding agent as an SDK, IDE extension, or CLI assistant." 80px app icon only Anti-pattern: no demo/screenshot/GIF anywhere; no badges; no topics
tldr-pages/tldr 63.1k "Collaborative cheatsheets for console commands 📚." Wordmark banner (H1 has no text) Best problem framing: shows competitor's bad man tar output verbatim, then before/after screenshot; 20 topics
Aider-AI/aider 47.2k "aider is AI pair programming in your terminal" SVG logo + SVG "screencast" Testimonial wall (~35 named quotes); usage-scale badges ("Installs 6.8M", "Singularity 88%")
google/zx 45.6k "A tool for writing better scripts" Inline SVG logo + H1, then runnable code Code-as-demo (show, don't tell); fastest to install (~line 23); no badges at all
oraios/serena 26.2k "A powerful MCP toolkit for coding … the IDE for your agent" SVG logo (light/dark) + analogy H3 Embedded video demo; novel social proof = the AI agents themselves review it; 12 topics
charmbracelet/gum 24.0k "A tool for glamorous shell scripts 🎀" Logo → 3 badges → tagline → GIF demo Per-command GIFs (×18), all published via VHS
humanlayer/12-factor-agents 24.0k "What are the principles we can use to build LLM-powered software…" Big linked screenshot + founder narrative Positioning-by-analogy ("12-Factor Apps"); founder-authority narrative; conf-talk badge
winfunc/opcode (was getAsterisk/claudia) 22.2k "A powerful GUI app and Toolkit for Claude Code…" Icon → H1 → bold tagline → screenshot + video Closest analog (desktop GUI for Claude Code); "⭐ Star the repo" CTA; trademark disclaimer NOTE; "command center for Claude Code" analogy
charmbracelet/vhs 20.3k "Your CLI home video recorder 📼" Logo → 3 badges → tagline → GIF demo The demo-tooling recommendation itself; dogfoods its own GIF; "GIFs as code" (reproducible)
steipete/CodexBar 17.1k "Show usage stats for OpenAI Codex and Claude Code, without having to login." social.png banner + product screenshot Native-mac-app pattern; brew cask; privacy-first section; "Why" bullets; topics: ai/claude-code/codex/swift
ryoppippi/ccusage 17.0k "npx ccusage" SVG logo + badge cluster + screenshot description = the run command; star-history chart; sponsor logos; one-line blockquote pitch
anthropics/claude-code 136.7k "Claude Code is an agentic coding tool that lives in your terminal…" The anchor product's description shape (a full capability sentence); no topics set
disler/single-file-agents 0.4k "What if we could pack single purpose, powerful AI Agents into a single python file?" Premise blockquotes + thumbnails description = a provocative question; creator-authority (YouTube)
mattpocock/skills 160.1k "Skills for Real Engineers. Straight from my .claude directory." Themed banner (light/dark) "Quickstart (30-second setup)" named literally; "not vibe coding" positioning; 60k-newsletter social proof; failure-mode framing

Demo-tooling repos also pulled: asciinema/asciinema (17.5k, "Terminal session recorder, streamer and player"), faressoft/terminalizer (16.1k, "Record your terminal and generate animated gif images"), wulkano/Kap (19.3k, "open-source screen recorder built with web technology"), sindresorhus/Gifski (8.5k, "Convert videos to high-quality GIFs on your Mac").


2. The 5-second hierarchy — what must be above the fold, in priority order

The "fold" on GitHub ≈ the first screenful before the reader scrolls (roughly the first 20–30 rendered lines / one laptop viewport). Rank order of what should occupy it:

  1. Identity — logo + name, recognizable in <1s. SVG logo with light/dark variants is the pro move (oraios/serena uses #gh-light-mode-only / #gh-dark-mode-only; ccusage, mattpocock/skills, and aider all ship theme-aware hero art). A wordmark-as-H1 works too (tldr, fzf) but forgoes a real title.
  2. The one-line "what it is" — a single sentence a stranger understands with no context. Best examples: lazygit "A simple terminal UI for git commands", bun "Bun is an all-in-one toolkit for JavaScript and TypeScript apps", serena "The IDE for Your Coding Agent". Jargon-free, category-anchored.
  3. The demothe highest-weight pixel on the page. Motion beats stills. See §3–§4.
  4. Trust badges — a compact row: release/version, platform, license, build/CI. CodexBar's row (release, macOS 14+, Homebrew, AUR, MIT, site) is the clean native-app template. Keep it to one line; do not put a tiny star badge here while stars are low (it reads as "nobody uses this").
  5. The quickstart — one copy-paste command. ccusage's npx ccusage@latest and CodexBar's brew install --cask codexbar are the model. mattpocock literally titles it "Quickstart (30-second setup)".

Everything else — full feature lists, architecture, contributing, FAQ — lives below the fold. The repos that invert this (feature-wall or sponsor-wall before the demo/install) are the anti-patterns of §8.


3. Hero archetypes — pick the one that matches the product

There are three README hero archetypes in the dataset. They are not interchangeable; the product type dictates the hero.

Archetype A — Tool → animated demo of it working. For CLIs and TUIs where "watch it run" is the pitch. Lead with a GIF (lazygit assets/demo/commit_and_push-compressed.gif; gum + vhs GIFs hosted on vhs.charm.sh) or with runnable code as the demo (zx puts a #!/usr/bin/env zx script block immediately after the H1, before any prose). Ripgrep is the outlier that substitutes a benchmark table for a visual and still wins — proof-by-numbers instead of proof-by-motion.

Archetype B — Native app / GUI → screenshot + embedded video. For desktop apps where the product is a visual surface. Lead with a product screenshot, then an embedded video tour. winfunc/opcode (Tauri GUI for Claude Code): app icon → H1 → bold tagline → bold second line → nav badges → screenshotembedded video → "⭐ Star the repo" → trademark disclaimer → "command center for Claude Code" overview. steipete/CodexBar (menu-bar app): social.png banner → one-paragraph what-it-is → product screenshot → "Why" bullets. oraios/serena (MCP server): logo → analogy tagline → embedded video ("Quick Demo") → "What Our End Users Say".

Archetype C — Content / manifesto → positioning + authority. For guides, principle-sets, and curated collections where there's no runtime to demo. Lead with positioning-by-analogy and author authority. humanlayer/12-factor-agents: title riffs on "12 Factor Apps", then a personal "Hi, I'm Dex… I've tried every agent framework out there" narrative, then a visual-nav image grid. mattpocock/skills: "not vibe coding" positioning + "60,000 devs on my newsletter" authority.

Claude Mission Control is Archetype B (a native macOS app / visual surface) — with a twist: it also has a legitimate Archetype-A "watch the fleet react" motion moment (the Attention Strip re-sorting), which is its most differentiated 5-second hook. So: screenshot + embedded video (B) for the tour, but a motion GIF of the attention re-sort (A) as the actual hero. Its nearest competitor for the hero pattern is opcode — study opcode's hero, then out-motion it.


4. The demo asset — GIF vs video vs screenshot, length, and tooling

4.1 Format trade-offs (all three observed in the wild)

Format GitHub behavior Best for Cost Seen in
Animated GIF Autoplays inline, loops, silent, no controls The 5–15s "money moment" above the fold Large file; capped color/quality lazygit, gum, vhs
Video (.mp4/.mov via github user-attachments) Renders an inline player; click to play, has audio, higher quality, can be long A 30–60s narrated feature tour, below the hero Needs a click; no autoplay/loop opcode, serena
Static screenshot (PNG) Always renders instantly "What it looks like" + the social-preview base No motion → doesn't prove liveness ccusage, CodexBar, ripgrep

The winning combo (synthesized from opcode + lazygit + CodexBar): a short autoplay GIF of the core action above the fold + a longer embedded video tour just below + a static screenshot reused as the 1280×640 social preview. Don't make the visitor click to see anything — the GIF carries the 5-second decision; the video is for the already-interested.

4.2 Length / loop discipline

  • GIF: 5–15s, one clear action, seamless loop, cropped tight to the UI, high-DPI. lazygit's hero GIF is a single commit-and-push; each of its 13 feature GIFs isolates exactly one feature. Do not try to show the whole app in the hero GIF — show the one move that makes someone go "oh, I need that."
  • Video: 30–90s, narrated or captioned, one pass through the value arc. serena's "Quick Demo" is a short embed with a longer YouTube link offered separately — a good two-tier pattern (short embed for the impatient, long-form link for the converted).

4.3 Tooling — and the terminal-vs-app split that matters for CMC

For terminal/CLI demos (not CMC, but this is the canonical tooling and worth knowing):

  • charmbracelet/vhs — "Write terminal GIFs as code." Demos are a .tape script (Output demo.gif / Type "..." / Sleep / Enter), so they're reproducible and CI-regenerable. The modern default for CLI demos; the whole Charm family dogfoods it (gum's 18 GIFs are vhs output).
  • asciinema — records a terminal session to a .cast file + web player; great for long sessions, embeds as a player rather than a GIF.
  • faressoft/terminalizer — record → animated GIF, config-driven.

For a native macOS app (this is CMC — its hero is a screen recording of a SwiftUI window, not a terminal cast, so vhs/asciinema do not apply):

  • CleanShot X — commercial mac capture; records region/window → GIF/MP4, clean cursor, one-click. (Available on this machine via the cleanshot MCP.)
  • wulkano/Kap — open-source mac screen recorder → GIF/MP4; good free option.
  • QuickTime / macOS ⌘⇧5 — built-in screen record → MP4, then encode.
  • sindresorhus/Gifski — video → high-quality GIF (far better than ffmpeg's default palette). The standard "record MP4, then Gifski it to a tight loop" pipeline.
  • CMC also already emits deterministic --render-<name> PNGs (light+dark) via ImageRenderer — perfect static assets and social-preview bases, but they are stills; the motion hero still needs a live screen recording.

5. Repo metadata — the parts that aren't the README

The README is ~70% of the repo page, but three metadata fields do disproportionate work and are the most-skipped:

The description one-liner (shows under the repo name, in search, in every embed). Patterns that work, ranked by legibility:

  • Crisp category sentence — lazygit "simple terminal UI for git commands", ripgrep's full descriptive line, bun's "all-in-one" line. Best default.
  • Value + differentiator — CodexBar "Show usage stats for OpenAI Codex and Claude Code, without having to login." The differentiator ("no login") is baked into 6 words.
  • Value + analogy — serena "…the IDE for your agent."
  • The run command itself — ccusage "npx ccusage" (tells you how to use it and what it is in two words).
  • A provocative question — 12-factor-agents, single-file-agents. High-risk/high-personality; only works for content/manifesto repos.

topics (the discovery layer — this is your only organic inbound before word-of-mouth). serena (12), tldr (20), bun (12), ripgrep (10), fzf (10) all invest here. Note that several huge repos (ccusage, cline, single-file-agents, mattpocock/skills, anthropics/claude-code) have zero topics — they can afford to skip discovery because they are the word-of-mouth. A launch-day repo cannot. CodexBar's 4 well-chosen topics (ai, claude-code, codex, swift) are the efficient minimum for a Claude-adjacent mac tool.

The social preview image (og:image, 1280×640, set in Settings → Social preview). This is what renders when the repo link is pasted into X / Slack / Discord / HN — i.e., the actual first impression for most launch traffic, before anyone sees the README. CodexBar's docs/social.png bakes the tagline into the image ("every AI coding limit in your menu bar. 57 providers.") so the link-unfurl itself pitches the product. Most repos never set this and get a generic gray GitHub card. [UNVERIFIED: the exact set of repos above that have vs. haven't set og:image — the API doesn't expose it cleanly; CodexBar's is confirmed by its social.png hero reuse.]


6. Naming + tagline patterns

  • Name = the metaphor, tagline = the literal. opcode ("command center for Claude Code"), serena ("The IDE for Your Coding Agent"), Mission Control — the name carries a spatial/role metaphor and the tagline cashes it out plainly. Lean into the metaphor the name already sets up.
  • Category-anchor in the first 5 words. "terminal UI for git" (lazygit), "command-line fuzzy finder" (fzf), "all-in-one toolkit" (bun). The reader must be able to file you into a known drawer instantly.
  • The differentiator can live in the tagline. CodexBar "…without having to login." One clause that says why-this-not-that.
  • Pain-first taglines work when the pain is universal and visceral. lazygit: "if you're a mere mortal like me and you're tired of hearing how powerful git is when in your daily life it's a powerful pain in your ass…" — the single best "tired of X?" hook in the set.
  • Second bold line to elaborate (opcode pattern): line 1 = what it is, line 2 = the three things it does. Gives skimmers two altitudes.

7. Social proof — match the signal to your stage

Social proof is stage-dependent. Showing a "★ 12" badge on launch day hurts. Ladder:

  • Pre-traction (0–500★): the demo is the proof. Add testimonials/quotes as they arrive (aider's ~35-quote "Kind Words From Users" wall is the gold standard; serena's clever move is quotes from the AI agents themselves). Benchmarks if you have them (ripgrep). An "as seen in" conf-talk badge if applicable (12-factor-agents). Do not show a small star count.
  • Traction (500–5k★): add download counts (aider "Installs 6.8M"), a star-history chart (ccusage embeds star-history.com), an "awesome-list mentioned" / Trendshift badge (ccusage).
  • Established (5k★+): live stars badge, sponsor logos (ccusage, lazygit), "used by" logos.

One universal, stage-independent move: an explicit star CTA. opcode's > [!TIP] ⭐ Star the repo and follow @… for early access converts fence-sitters. Underused; cheap; add it.


8. Anti-patterns, ranked by damage to first-5-second conversion

  1. Ads / sponsors / merch above the demo. lazygit's first pixels are three paid-sponsor blocks before the project is even named; fzf sells T-shirts above the fold. They survive on fame; a new repo doing this reads as spam. (Sponsors belong at the bottom — ccusage, CodexBar put them there.)
  2. No demo at all. cline (64k★) ships zero screenshots/GIFs/video — you cannot tell what it looks like. For a visual product this is fatal at launch.
  3. Demo buried. fzf's real demo is a YouTube link ~line 500; aider's install is behind 9 feature blocks. If the reader has to scroll to see it work, most won't.
  4. Wall of text / feature-list before the demo or install. aider (9 feature blocks → install), lazygit (~262 lines → brew install).
  5. Contributor path masquerading as the quickstart. Leading with git clone && build / swift build instead of a download or package install. The visitor wants to run it; the builder is a different audience, lower down. ← the current CMC README does exactly this.
  6. No trust signals (no badges, no license) for a skimmer deciding if it's real and maintained. zx has 45k★ but zero badges — again, fame-buffered.
  7. Unset metadata — no description, no topics, no social preview → generic gray unfurl + no discovery.
  8. Jargon tagline — a first line only an insider parses. (None of the winners do this; it's the failure mode of internal tools going public.)

9. THE README TEMPLATE (ordered, first-5-second optimized)

Section-by-section, with the repo each element is drawn from. Above-the-fold block = items 1–6; ship those first.

┌─ ABOVE THE FOLD (the 5-second decision) ─────────────────────────┐
│ 1. Centered LOGO  — SVG, light/dark variants                      │  ← serena, ccusage, aider
│ 2. H1 — the product name                                          │  ← bun, opcode
│ 3. TAGLINE — one bold line "what it is" + a 2nd bold line          │  ← opcode
│    elaborating the 3 things it does (jargon-free, category-anchored)│  ← lazygit, bun
│ 4. BADGE ROW — release · platform · license · build (one line;     │  ← CodexBar
│    NO small-star badge while stars are low)                        │
│ 5. ★ HERO DEMO — autoplay GIF of the core action, above the fold ★ │  ← lazygit, gum, vhs
│ 6. ONE-SENTENCE what-it-is + the DIFFERENTIATOR sentence           │  ← ripgrep, CodexBar
└───────────────────────────────────────────────────────────────────┘
 7. Trademark/affiliation NOTE ("not affiliated with Anthropic")     ← opcode
 8. QUICKSTART (<30s) — the VISITOR install (download / brew cask),   ← ccusage, CodexBar,
    one copy-paste command, titled "Quickstart (30-second setup)"       mattpocock
 9. EMBEDDED VIDEO tour (30–90s, click-to-play) + optional long link  ← opcode, serena
10. WHY / THE PROBLEM — the visceral "tired of X?" pain hook          ← lazygit, tldr
11. FEATURES — grouped by pillar, EACH with its own small GIF/shot;   ← lazygit (per-feature
    emoji subsection headers                                            GIFs), opcode (emoji)
12. THE DIFFERENTIATOR — vs alternatives, with a screenshot          ← CodexBar "Why", ripgrep
13. PRIVACY / SECURITY posture (critical if it reads user data)       ← CodexBar privacy-first
14. SOCIAL PROOF — testimonials now; star-history/downloads later     ← aider, serena, ccusage
15. ARCHITECTURE (brief) — for the curious/contributor               ← CodexBar, humanlayer
16. BUILD FROM SOURCE / DEVELOPMENT — swift build etc. (moved DOWN)   ← CodexBar, ccusage
17. ★ STAR CTA — "⭐ Star the repo…"                                   ← opcode
18. RELATED PROJECTS · CREDITS · LICENSE                              ← CodexBar, fzf

10. THE CONVERSION RUBRIC (score any repo page /100)

Four weighted blocks. Score honestly against the first screen, then the rest.

A. Above the fold — the 5-second test (0–40) — the block that actually moves stars.

  • Logo/name identifiable in <1s (5)
  • One-line "what it is" a stranger understands, above the fold (8)
  • A demo (GIF/video/screenshot) visible without scrolling (12) ← highest single weight
  • Demo shows the product's real money moment in motion, not a logo/mockup (8)
  • No ads/sponsors/merch/feature-wall before the demo (7)

B. Trust (0–20)

  • Trust badge row: release · license · platform · build (5)
  • Social proof appropriate to stage (testimonials/benchmarks now; stars/downloads later) (5)
  • Platform / requirements obvious (e.g. macOS 15+) (3)
  • Privacy/security posture stated if it reads user data (4)
  • Trademark/affiliation disclaimer if riding a brand (Claude/Anthropic) (3)

C. Activation (0–20)

  • Copy-paste install one-liner reachable in <30s / within ~2 screens (8)
  • The install is the visitor path (download/brew), not the contributor build (6)
  • Clear "what next" after install (first-run guidance) (3)
  • GitHub description set and scannable (3)

D. Depth & discovery (0–20)

  • Feature list with per-feature visuals (5)
  • The differentiator vs alternatives is stated (5)
  • topics set (10–15) for discovery (5)
  • Social-preview image (1280×640 og:image) set (5)

Bands: 85–100 = converts on the first screen. 60–84 = converts the patient. <60 = coasting on reputation (fine for fzf, fatal for a launch). Current CMC README self-scores ≈ 35–40 — strong copy, but it loses the entire block A demo weight (no image) and the block C visitor-install weight (leads with swift build).


11. REPO-PAGE SPEC — Claude Mission Control

Grounding: CMC is a native macOS SwiftUI app (Archetype B) that reads the files Claude Code already writes and gives a one-person AI fleet a cockpit — SEE / AUDIT / LAUNCH / ORCHESTRATE. Its sharpest, most ownable 5-second hook is the Attention Strip ("which of my 8 agents needs me right now") and its differentiator is the cross-machine fleet over Tailscale ("none sees a fleet across machines"). Nearest hero-pattern competitor: winfunc/opcode. (Source language: docs/VISION.md, README.md.)

11.1 GitHub description (the metadata one-liner)

Pick one (all ≤ ~120 chars, category-anchored + differentiator, in the lazygit/CodexBar mold):

  • A (recommended): Mission control for your Claude Code fleet on macOS — see which agent needs you, audit the waste, launch the next one right.
  • B (differentiator-forward): The macOS command center that watches every Claude Code agent across all your machines — attention routing, waste audit, launch button.
  • C (crisp category): A native macOS dashboard for Claude Code power users running many agents at once.

11.2 Tagline (README hero, two altitudes — opcode pattern)

  • Line 1 (what it is): "Mission control for a one-person Claude Code fleet."
  • Line 2 (the three jobs): "See which of your agents needs you now, audit the whole workflow for waste, and launch the next session pre-loaded — across every machine you run on."
  • Pain-first alternative (lazygit mold), for the "Why" section: "Stop alt-tabbing between eight terminals wondering which agent is stuck." (Lifted from VISION's own "friend sentence" — it's already the best line in the repo.)
  • Analogy line to reinforce the name: the app is the door light — "the brand is the telemetry."

11.3 The hero demo to make (the single highest-ROI asset)

Primary — the hero GIF (Archetype A motion, 10–15s, autoplay loop, above the fold):

  • Content: the Attention Strip in motion. Open on 6–8 live sessions RUNNING (green). One session's tool_use dangles → it flips to BLOCKED (red) → the strip re-sorts it to the top → the dock badge + menu-bar glyph light up ("needs you"). This is the exact moment no competitor shows and it reads in 3 seconds.
  • How: record the live app with CleanShot X (or Kap) → trim to the single re-sort beat → Gifski to a tight, seamless loop, cropped to the strip + menu bar. Retina scale, dark mode (the app's default look).
  • Placement: immediately after the badge row, before any prose. This is item 5 in the template.

Secondary — the embedded video tour (Archetype B, 45–75s, click-to-play, below the hero):

  • One pass through the flywheel: SEE (Fleet Board "the Floor" with the event-heartbeat) → AUDIT (the "$20 hey" cache-miss finding attributed to a cause) → Dreaming Ledger (a finding → an approvable candidate fix → clipboard) → LAUNCH (Session Builder composes a recipe with model pins) → the cross-machine chip showing devcube. Upload as a github user-attachments .mp4.

Static assets (already producible today):

  • Use .build/debug/ClaudeMissionControl --render-fleet and --render-attention (light+dark PNGs via ImageRenderer) as the per-feature screenshots in the Features section and as fallbacks.
  • Logo / identity: ship "the door light" (session dot + 1pt tier ring) as an SVG with light/dark variants for the README hero (serena/ccusage pattern) and reuse the app icon.
  • Social preview (1280×640): compose a --render-fleet shot + the tagline text baked in (CodexBar social.png pattern); set it in Settings → Social preview so the launch-day X/HN unfurl pitches itself.

11.4 Metadata to set

  • topics (12–14): claude-code, claude, anthropic, macos, swift, swiftui, menu-bar, dashboard, observability, ai-agents, agent-orchestration, developer-tools, cost-tracking, tailscale. (Mirrors serena/CodexBar's Claude-adjacent topic set + the mac-native ones.)
  • LICENSE: the repo currently has no LICENSE file — add one (MIT, matching CodexBar/ccusage/serena) so the license badge is even possible and so people can legally use it.
  • Release: publish a GitHub Release with a zipped .app (bash Scripts/make-app.sh output) so the quickstart can be a download; a brew install --cask later (CodexBar's path).

11.5 The exact README outline for CMC

1.  Centered "door light" LOGO (SVG, light/dark)
2.  # Claude Code Mission Control
3.  **Mission control for a one-person Claude Code fleet.**
    **See which of your agents needs you now, audit the workflow for waste, launch the next session pre-loaded — across every machine you run on.**
4.  Badges: [Release] [macOS 15+] [Swift 6] [License: MIT] [Build]   (no star badge yet)
5.  ★ HERO GIF — the Attention Strip flipping a session to BLOCKED and re-sorting ★
6.  One-liner: "It reads the files Claude Code already writes — zero import, nothing
    leaves the machine, never writes ~/.claude." + DIFFERENTIATOR: "The only dashboard
    that sees your fleet across every machine, over Tailscale."
7.  > [!NOTE] Not affiliated with, endorsed by, or sponsored by Anthropic.
8.  ## Quickstart (30-second setup)  → Download the latest .app (Release link)  [visitor path]
9.  Embedded VIDEO tour (SEE → AUDIT → Dreaming Ledger → LAUNCH → cross-machine)
10. ## Why  — "Stop alt-tabbing between eight terminals wondering which agent is stuck."
11. ## What it does  — the four pillars, EACH with its --render-* screenshot / a short GIF:
      ### 👁  SEE — Attention Strip · Fleet Board "the Floor" · cloud-browser live view
      ### 🔎  AUDIT — cache-miss dollars · dead-skill ledger · doctrine audit · model-mismatch
      ### 🚀  LAUNCH — Session Builder (model-pinned recipes) · skill hierarchy
      ### 🔁  The Dreaming Ledger — findings → approvable fixes (the flywheel/moat)
12. ## Cross-machine fleet over Tailscale  — the differentiator, with a screenshot
13. ## Privacy  — reads a known set of local files; nothing leaves the machine; never
      writes ~/.claude; remote is read-only over Tailscale   (CodexBar privacy-first mold)
14. ## Under the hood (brief)  — 2 targets, Swift 6 strict concurrency, ~14k LOC, 265 tests
15. ## Build from source  — swift build / swift run / swift test  (moved DOWN here)
16. > [!TIP] ⭐ Star the repo if a fleet cockpit is something you'd use.
17. ## Related · Credits · License

The two edits that move the most stars, if only two are made: (1) put the Attention-Strip hero GIF at position 5; (2) swap the position-8 quickstart from swift build to a downloadable .app. Everything else is polish on top of those two.


12. Citations (repos read for this doc)

Local clones (~/Developer/reference-repos/): ccusage, CodexBar, serena, humanlayer(12-factor-agents), single-file-agents, mattpocock-skills. Remote via gh api .../readme: junegunn/fzf, BurntSushi/ripgrep, jesseduffield/lazygit, google/zx, oven-sh/bun, Aider-AI/aider, cline/cline, tldr-pages/tldr, charmbracelet/vhs, charmbracelet/gum, winfunc/opcode, anthropics/claude-code. Demo-tooling: charmbracelet/vhs, asciinema/asciinema, faressoft/terminalizer, wulkano/Kap, sindresorhus/Gifski.

Key asset URLs cited: lazygit assets/demo/commit_and_push-compressed.gif; vhs stuff.charm.sh/vhs/examples/neofetch_3.gif; gum GIFs on vhs.charm.sh; CodexBar docs/social.png; ccusage docs/public/screenshot.png + star-history.com embed; serena resources/serena-logo.svg (#gh-light-mode-only/#gh-dark-mode-only); opcode github user-attachments screenshot + video.

Star counts current as of 2026-07-08 (gh api). Product language for CMC drawn from docs/VISION.md and the current README.md.