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 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, so 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. Your data (config, stats in ~/.claude-rpc/) is deliberately left 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.