GitHub - vmc-7645/claude-fleet: Raycast extension: integrate Claude Code — spawn/resume/review agents from the launcher

See your Claude Code agents, PRs, and worktrees in Raycast — and hand any of them to an agent in one keystroke. Plus an ambient menu-bar read on who needs you.

Note

Built and in daily use as a local Raycast dev extension. Full design in SPEC.md. Liveness needs no hooks — the extension reads Claude Code's own session registry (~/.claude/sessions) directly, so active agents show up out of the box. The bundled helpers add the richer touches (Focus Tab, per-turn state, Spawn, Undo).

The `→ Claude` primitive

Every dev surface — a PR, an issue, a running agent, a past session, a worktree — carries a one-keystroke hand it to an agent action. That's the whole idea: stop context-switching to a terminal to start work; start it from wherever you already are.

Commands

Fourteen commands, grouped by what you reach for.

🤖 Agents & fleet

Command	Mode	What it does
Agents	list	Active (live) + Recent (history) console. Per agent: Focus Tab (jumps to the exact Ghostty tab), Resume, Fork, Nudge / Quick Reply (send a canned follow-up into its tab), Close Tab, Undo last turn, Stop, open in editor/folder. Detail pane (⌘I) shows the pending question + mode/state/diff. Scope dropdown (All / Active / Recent / per-repo).
Next Waiting Agent	hotkey	Focus the agent that's been waiting on you longest — hit it again to work through the backlog. Opt-in: off by default; enable it and assign a hotkey.
Fleet	menu bar	Needs-you count badge + roster; click an agent to focus its tab. Refreshes every minute.

🔀 PRs, issues & worktrees

Command	Mode	What it does
My PRs	list	Your cross-repo open PRs with CI status (✅ / ❌ / ⏳). Per PR: Review in Claude, Check Out & Work, Resume PR agent (`--from-pr`).
PRs to Review	list	PRs where someone requested your review (cross-repo, with CI + author) → Review in Claude (`/review`), cloning the repo on demand.
My Issues	list	Cross-repo open issues → start an agent seeded with the issue.
Review PR	form	Type a PR number + pick a repo → `claude /review`.
Worktrees	list	Worktrees across repos; open / resume / remove; merged branches flagged 🍂.

🚀 Spawn & start

Command	Mode	What it does
Spawn Agent	form	Repo + task (+ optional branch) → agent in a fresh worktree, seeded with the task.
New Session	form	Fresh Claude session in a repo (no worktree).

⚙️ Manage Claude Code

Command	Mode	What it does
MCP Servers	list	Configured servers + live auth status; re-authenticate via `/mcp`.
Skills	list	Manage your custom slash-command skills — edit, enable/disable, create.
Usage	list	Estimated tokens & cost per session (today vs earlier), at API rates.
Claude Code Config	list	Edit settings / CLAUDE.md, inspect hooks / plugins, set model, run `doctor`, show version.

Repo pickers (Review PR · New Session · Spawn) are recency-sorted: your local repos first, then everything you can access on GitHub — remote picks are cloned on demand.

Screens

_{The Claude Fleet commands in Raycast.}

Setup

Prerequisites: macOS · Raycast · Claude Code · gh · git · jq · a terminal (Ghostty recommended)

# 1 — clone
git clone https://github.com/vmc-7645/claude-fleet.git && cd claude-fleet

# 2 — install the shell helpers + hooks (idempotent; wires ~/.claude/settings.json, backs it up first)
helpers/install.sh

# 3 — sign in to GitHub (for My PRs / PRs to Review / My Issues)
gh auth login

# 4 — load the extension into Raycast (persists after you stop the dev server)
cd extension && npm ci && npm run dev

Then two one-time steps:

Restart Claude Code so the new hooks load.
Grant Raycast Accessibility — System Settings → Privacy & Security → Accessibility → enable Raycast. Needed for the tab-focus / keystroke actions; gh reads work without it.

That's it — open Raycast and search Claude Fleet.

Preferences (Raycast → Extensions → Claude Fleet → ⚙️)

Terminal — where agents open: Ghostty (default), iTerm2, or Apple Terminal. Focus Tab / Nudge / Close Tab need Ghostty (per-tab accessibility); every other action (Resume, Fork, Review, Spawn, New Session…) works on any of them.
Agent primary action — Focus Tab vs Resume in New Tab (what Enter does on a live agent).
Quick replies — comma-separated canned follow-ups for the Quick Reply action.
Editor command — code / cursor / … for Open in Editor (must be on PATH).
Repos directory — override discovery root. Blank → ~/.config/claude-fleet/repos.env → ~/Repos.
Open agents as (Ghostty) — a new tab in the project's window (default) or a new window.
Tab open delay (Ghostty) — seconds to settle before the command is pasted in (default 0.3).

Under the hood

The extension is a thin, declarative UI over a few data sources it reads directly — no daemon, no polling service, nothing to keep running.

Where each fact comes from

Source	Gives
`~/.claude/sessions/*.json`	Active agents — Claude's own live registry (sessionId · cwd · pid · busy/idle). Authoritative liveness, no hooks needed.
`~/.claude/projects/*.jsonl`	Recent sessions — title (`aiTitle`), pending question (last assistant message), turn count, token usage. Parsed metadata is cached by file mtime.
`~/.claude/fleet/*.json`	Optional enrichment from the `fleet-register` hook — finer state (waiting / done), task label, diff, mode.
`gh`	Cross-repo PRs & issues, CI rollup, remote repo list.

The local commands + hooks the extension drives are vendored in helpers/ (claude-worktree, claude-undo, claude-restore, and the tab-status / fleet-register / checkpoint hooks) — see helpers/README. The extension degrades gracefully without them: Focus Tab falls back to raising the terminal; Spawn / Undo report the missing command.

Focus Tab — how it works

The tab-status hook titles each Ghostty tab <emoji> <repo>:<branch> — <task>. Ghostty exposes tabs as a native AXTabGroup of AXRadioButtons (titles = those strings), so the extension matches an agent to its tab by repo:branch and AXPresses it — jumping you straight there (even across Spaces for a fullscreen window). No match → it raises the terminal.

Requirements

macOS · a terminal — Ghostty (default, and required for Focus Tab / Nudge / Close Tab), iTerm2, or Apple Terminal · Claude Code · gh (My PRs / PRs to Review / My Issues) · git · jq (the helpers/ hooks).

Publishing to the Raycast store

It runs great as a local dev extension (npm run dev); this is what's left if you ever want it in the Raycast store:

✅ categories, keywords, CHANGELOG.md, icon, and required manifest fields are in place.
⬜ Screenshots — add 3–6 to extension/metadata/ (Raycast's Export Screenshots, 2000×1250).
⬜ Store submission — cd extension && npm run publish opens a PR against raycast/extensions for review.
⚠️ Caveat: full functionality depends on the shell helpers (helpers/install.sh) and Ghostty + Accessibility. The extension degrades gracefully without them, but store reviewers will see reduced behavior unless that setup is documented in the store description.

License

MIT. The Claude marks in extension/assets/ are Anthropic's trademarks — see assets/NOTICE. Not affiliated with Anthropic.

The → Claude primitive