one command, whatever your setup
Every path below ends in the same place: setup wires nine lifecycle hooks into ~/.claude/settings.json (as absolute, PATH-independent commands — only claude-rpc's own entries, third-party hooks are never touched), seeds a default config, starts the daemon, registers login autostart (LaunchAgent on macOS, systemd --user on Linux, a Run-key entry on Windows), and test-fires a synthetic SessionStart so a broken pipe surfaces immediately. All of it is reversible — see uninstall.
npm / npx — macOS · Linux · WSL (Node 18+)
$ npx claude-rpc@latest setupthe @latest matters — bare npx will happily reuse a stale cached copy.
Homebrew — macOS · Linux
$ brew install rar-file/claude-rpc/claude-rpc && claude-rpc setupthe one-liner that figures it out
$ curl -fsSL https://claude-rpc.com/install | shdetects Node 18+ (installs the npm package) or falls back to the prebuilt Apple-Silicon binary, then runs setup for you. read install.sh before piping it.
Windows — no Node required
Download the …-setup.exe from the latest GitHub release and run it. Since v1.1.2 the desktop app runs the full setup itself on first launch (and again after every update) — hooks, daemon, autostart, all of it — and reports the outcome in its Daemon tab. The exe is unsigned (solo project), so SmartScreen's More info → Run anyway is expected. Prefer no GUI? There's also a portable …-portable.exe: run claude-rpc setup from it once.
from inside Claude Code — the plugin
/plugin marketplace add rar-file/claude-rpc /plugin install claude-rpc@claude-rpc
typed inside Claude Code. a thin bootstrapper: on the first session it runs npx claude-rpc@latest setup for you, then stays out of the way. macOS / Linux / WSL — on Windows use the exe above.
VS Code
The Claude RPC Presence extension (rarfile.claude-rpc-presence) puts your live session in the VS Code status bar — it reads the same local state the daemon writes, so install claude-rpc itself first with any path above.
prove the pipe works
One command checks the whole chain and prints a pass/fail checklist with a one-line fix hint per failure:
$ claude-rpc doctorIt covers Node version, install mode, config.json (presence + clientId), that ~/.claude and your transcripts exist, hook registration — including hooks wired the old PATH-dependent way, or against a Node that's since been removed — daemon liveness, the Discord IPC state read from the daemon log, aggregate freshness, usage polling, and how the current directory resolves for privacy.
$ claude-rpc doctor --fixapplies only the targeted repairs doctor found (re-wire hooks/config, restart the daemon, rebuild the aggregate) — it doesn't blindly re-run everything. Discord itself can't be auto-fixed; that one stays advice.
For a look at your data rather than your plumbing:
$ claude-rpc status # TUI — heatmap, hour histogram, leaderboards
what healthy looks like on Discord
- The Discord desktop app must be running — the browser client doesn't expose the local IPC bridge Rich Presence uses.
- In Discord: User Settings → Activity Privacy → enable Share your detected activities with others, or the card renders for no one.
- Open Claude Code in any project — the card appears within a second, the large image swaps between working / thinking / waiting / idle as you work, and the two text lines rotate through your frames. Closing Claude Code clears the card instantly.
two lines is a complete config
Every key has a baked default (src/default-config.js is the canonical list). Your config.json only holds overrides — whatever you put there deep-merges over the shipped defaults, so you never copy the full shape and updates never fight your file.
| os | config.json lives at |
|---|---|
| Linux | $XDG_CONFIG_HOME/claude-rpc/config.json (usually ~/.config/claude-rpc/) |
| macOS | ~/Library/Application Support/claude-rpc/config.json |
| Windows | %APPDATA%\claude-rpc\config.json |
{
"clientId": "1506443909406920948"
}frames: byStatus + rotation
The card is templated per status under presence.byStatus — working, thinking, idle, and friends each get a base frame, plus an optional rotation array that cycles after it. Each frame can declare requires: the daemon skips any frame whose required variables resolve empty, so you can write ambitious frames knowing only the relevant ones render.
{
"presence": {
"byStatus": {
"idle": {
"details": "Idle in {project}",
"state": "{modelPretty} · {todayHours} today",
"rotation": [
{ "details": "This week · {weekHours}",
"state": "{weekPromptsLabel} · {weekTokensFmt} tokens",
"requires": ["weekActiveMs"] }
]
}
}
}
}template variables
Over 200 variables are available in any frame. Twelve favourites:
| variable | renders as |
|---|---|
| {project} | the project on the card (respects your privacy aliases) |
| {model} | the model driving the session ({modelPretty} for the friendly name) |
| {todayHours} | active hours today |
| {allTokensFmt} | lifetime tokens, formatted — "2.4B" |
| {streakLabel} | "12-day streak" |
| {topTool} | your most-called tool |
| {toolMixLabel} | how your tool calls split across the top tools |
| {cacheSavedLabel} | "≈$41 saved by cache" |
| {subagentHours} | hours your subagents have worked for you |
| {peakWeekday} | your busiest weekday |
| {currentFile} | the file Claude is touching right now |
| {gitBranch} | current branch of the working directory |
$ claude-rpc vars # dump all 200+ variables, live, as JSON $ claude-rpc preview # render every frame with your real data
layered valves, all one-way
Privacy sits between your local state and Discord — a one-way valve. Your local stats, dashboards, and aggregates are never affected by any of these.
per directory
$ claude-rpc private # hide the current project from the card $ claude-rpc public # un-hide it $ claude-rpc privacy # show how this directory resolves, and why
or drop a .claude-rpc.json at the project root: {"private": true}, {"visibility": "name-only"}, or {"projectName": "redacted"} to show an alias instead.
by pattern, globally
{ "privacy": { "patterns": ["client-*", "secret-stuff"], "mode": "hidden" } }auto-detected
If the gh CLI is installed and authenticated, GitHub-private repos hide themselves (privacy.githubPrivateMode, default hidden; opt out with privacy.autoDetectGithubPrivate: false). Without gh, doctor warns when a private repo's link could reach the card.
screen-sharing
$ claude-rpc pause 30m # snooze the card (also 2h, 1h30m; bare pause = 1h) $ claude-rpc resume # lift it early
telemetry
$ claude-rpc community off # stop reporting anonymous totals
What gets sent while it's on: two counters, the version, the OS family, and an anonymous UUID — nothing else. The byte-level payload, every outbound request, and the persistence mechanics are documented in SECURITY.md.
put your stats where people can see them
join the leaderboard
$ claude-rpc profile set --handle <you> && claude-rpc profile on $ claude-rpc profile publish # optional: push now instead of the next flush
Verified profiles (a proven GitHub identity) rank first on the leaderboard and get the ✓. Two ways to verify: log in with GitHub at claude-rpc.com/link and claim the code it mints with claude-rpc link <code>, or — no browser — claude-rpc profile verify proves ownership through a public gist. Extra machines link into the same identity: run claude-rpc link on the verified machine, claim the code on the new one.
badges & cards for your README
With a published profile, the community worker serves an always-current card and badges — paste once, they refresh themselves (~every 30 min as the daemon flushes):
[](https://claude-rpc.com/u/<you>) [](https://claude-rpc.com/?ref=badge)
badge metric= is one of tokens · sessions · hours · streak (optional &label= to retitle). claude-rpc readme prints the whole block filled in with your handle, and your profile page at /u/<you> has one-click copy. Full route reference: WORKER-API.md.
squads
$ claude-rpc squad create "the night shift" # private mini-board; friends join with the invite code
Claude Wrapped
Your whole year on Claude — hours, streaks, peak day, top projects, tool mix — as an animated year-in-review you can publish to the web in one command: claude-rpc wrapped --publish puts it at claude-rpc.com/wrapped/<you>, share card included. See what a Wrapped looks like →
the failures people actually hit
First step is always claude-rpc doctor — every failure below is something it checks for, with a fix hint. The catalogue, for when you'd rather match symptoms:
Claude Code shows hook errors: "claude-rpc: command not found"
Cause: hooks wired by a pre-v0.19.1 install depend on PATH — and Claude Code runs hooks through a minimal-PATH shell that, under a version manager like nvm, has neither claude-rpc nor node on it. So every tool use errors. The same happens if nvm later removed the Node version the hooks were wired against.
$ npx claude-rpc@latest setupFix: setup rewrites the hooks as absolute, PATH-independent commands. Restart Claude Code afterwards so it re-reads its hook config. doctor flags this state explicitly (as of v1.1.4) and doctor --fix repairs it.
No card on Discord at all
Cause: nine times out of ten, the Discord desktop app isn't running (the browser client can't do Rich Presence), or Discord's Activity Privacy is off.
$ claude-rpc doctorFix: start Discord desktop, then check User Settings → Activity Privacy → Share your detected activities with others. Doctor's "discord IPC connection" line tells you which side is broken.
Card is frozen or showing stale data
Cause: usually a daemon that lost its Discord connection or is running an old version after an update.
$ claude-rpc restart $ claude-rpc tail # watch what the daemon is actually doing
Windows: installed the app, nothing happened
Cause: installers before v1.1.2 put the settings GUI on disk but never ran the one step that matters — setup lived only in the CLI, so no hooks were wired and no daemon started.
Fix: update (the auto-updater pulls it, or grab the latest setup exe). The app now runs setup itself on first launch and after every update — and there's a visible Run setup button in the Daemon tab (plus a tray menu entry) that's safe to click any time.
macOS: "Claude RPC is damaged and can't be opened"
Cause: dmg builds before v1.1.3 shipped unsigned, and Apple Silicon refuses those outright. Current builds are ad-hoc signed — you get the standard unverified developer prompt instead: System Settings → Privacy & Security → Open Anyway, once.
$ xattr -cr "/Applications/Claude RPC.app" # or clear the quarantine flag directly
Or skip the dmg entirely: brew install rar-file/claude-rpc/claude-rpc has no Gatekeeper friction.
Stats look wrong or missing
Cause: a stale or corrupted aggregate — the lifetime numbers are built by scanning your Claude Code transcripts, and the cache can lag a version bump.
$ claude-rpc rescan # force a full re-parse of ~/.claude/projects
claude-rpc tail shows the daemon log live, and issues on GitHub get read by the person who wrote the code.leave no trace
$ claude-rpc uninstall # removes its hooks + the login-autostart entry $ npm rm -g claude-rpc # then remove the package itself
uninstall removes everything that respawns or registers the tool — its own hooks from ~/.claude/settings.json (third-party hooks untouched) and the autostart entry — and deliberately leaves your data (config, stats in ~/.claude-rpc/) in place. Run claude-rpc stop first if a daemon is up, and claude-rpc mcp uninstall if you wired the MCP server. For a clean wipe, delete ~/.claude-rpc and the per-OS config dir afterwards.