{"id":50092474,"url":"https://github.com/rar-file/claude-rpc","last_synced_at":"2026-07-02T02:03:50.924Z","repository":{"id":359232344,"uuid":"1245108765","full_name":"rar-file/claude-rpc","owner":"rar-file","description":"Discord Rich Presence (RPC) for Claude Code — live model, project, tokens, and lifetime stats in your Discord profile. Driven by Claude Code hooks.","archived":false,"fork":false,"pushed_at":"2026-07-02T01:15:03.000Z","size":3174,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T01:17:31.802Z","etag":null,"topics":["anthropic","claude","claude-code","claude-code-hooks","cli","developer-tools","discord","discord-rpc","hooks","nodejs","productivity","rich-presence"],"latest_commit_sha":null,"homepage":"https://claude-rpc.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rar-file.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T23:21:35.000Z","updated_at":"2026-07-02T01:15:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rar-file/claude-rpc","commit_stats":null,"previous_names":["rar-file/claude-rpc"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/rar-file/claude-rpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rar-file%2Fclaude-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rar-file%2Fclaude-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rar-file%2Fclaude-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rar-file%2Fclaude-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rar-file","download_url":"https://codeload.github.com/rar-file/claude-rpc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rar-file%2Fclaude-rpc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35029798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","claude-code-hooks","cli","developer-tools","discord","discord-rpc","hooks","nodejs","productivity","rich-presence"],"created_at":"2026-05-23T01:06:04.579Z","updated_at":"2026-07-02T02:03:50.917Z","avatar_url":"https://github.com/rar-file.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/header.svg\" width=\"820\" alt=\"claude-rpc — Discord Rich Presence for Claude Code: live model, project, tokens, and lifetime stats, driven by the hooks Claude Code already fires. Install with: npx claude-rpc setup\" /\u003e\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n\u003cimg src=\"https://cdn.qualit.ly/clawd-working-building.gif\" width=\"104\" alt=\"working\" /\u003e\n\u003cimg src=\"https://cdn.qualit.ly/clawd-working-typing.gif\" width=\"104\" alt=\"thinking\" /\u003e\n\u003cimg src=\"https://cdn.qualit.ly/clawd-notification.gif\" width=\"104\" alt=\"waiting on you\" /\u003e\n\u003cimg src=\"https://cdn.qualit.ly/clawd-sleeping.gif\" width=\"104\" alt=\"idle\" /\u003e\n\n\u003csub\u003ethe card's live states — \u003cb\u003eworking\u003c/b\u003e · \u003cb\u003ethinking\u003c/b\u003e · \u003cb\u003ewaiting\u003c/b\u003e · \u003cb\u003eidle\u003c/b\u003e\u003c/sub\u003e\n\n\u003cbr/\u003e\n\n**Discord Rich Presence for [Claude Code](https://claude.com/claude-code)** — your live model, project, tokens, and lifetime stats, driven by the hooks Claude Code already fires.\n\n**[claude-rpc.com →](https://claude-rpc.com)** — see it in one page.\n\n[![community · sessions](https://claude-rpc-totals.claude-rpc.workers.dev/sessions.svg)](#community-totals) \u0026nbsp; [![community · tokens](https://claude-rpc-totals.claude-rpc.workers.dev/tokens.svg)](#community-totals)\n\n\u003csub\u003elive — on by default for fresh installs, opt out any time. see [community totals](#community-totals)\u003c/sub\u003e\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Node 18+](https://img.shields.io/badge/node-%3E%3D18-43853d.svg?logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-hooks-d97757.svg)](https://claude.com/claude-code)\n[![Discord RPC](https://img.shields.io/badge/Discord-RPC-5865F2.svg?logo=discord\u0026logoColor=white)](https://discord.com/developers/docs/topics/rpc)\n[![Release](https://img.shields.io/npm/v/claude-rpc?color=4c1\u0026label=release\u0026logo=npm\u0026logoColor=white)](https://github.com/rar-file/claude-rpc/releases/latest)\n[![npm downloads](https://img.shields.io/npm/dm/claude-rpc?color=cb3837\u0026logo=npm\u0026logoColor=white\u0026label=downloads)](https://www.npmjs.com/package/claude-rpc)\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/demo.gif\" width=\"560\" alt=\"Discord Rich Presence card showing Claude Code working in claude-rpc on Opus 4.7\" /\u003e\n\u003c/div\u003e\n\nA small Node daemon that takes the lifecycle events Claude Code already fires and pipes them into the Discord rich-presence card on your profile. Your friends see what you're building; your future self gets lifetime stats. Built solo, on weekends.\n\n## install\n\n**macOS / Linux / any Node 18+** — one command:\n\n```sh\nnpx claude-rpc@latest setup\n```\n\n(The `@latest` matters — bare `npx claude-rpc` will happily reuse a stale cached copy.)\n\nThat installs `claude-rpc` globally, wires the hooks into Claude Code, and starts the daemon — no separate `start` step. Open Claude Code in any project and the card appears within a second. Something looks wrong? `claude-rpc doctor` (or `claude-rpc doctor --fix` to auto-repair).\n\n**Prefer a one-liner that figures it out for you?**\n\n```sh\ncurl -fsSL https://claude-rpc.com/install | sh\n```\n\nDetects Node (installs the npm package) or falls back to the prebuilt Apple-Silicon binary, then runs `setup` for you.\n\n**Homebrew** (macOS / Linux):\n\n```sh\nbrew install rar-file/claude-rpc/claude-rpc \u0026\u0026 claude-rpc setup\n```\n\n**Windows (no Node required)** — [grab the portable exe from the latest release](https://github.com/rar-file/claude-rpc/releases/latest), then:\n\n```sh\nclaude-rpc setup\n```\n\nThat's the whole pitch.\n\n\u003e `setup` registers a Windows startup entry and wires hooks into Claude Code's `settings.json`, and the daemon reports anonymous totals by default. All of it is reversible (`claude-rpc uninstall`, `community off`) and fully documented in [`SECURITY.md`](SECURITY.md) — read it first if you want to know exactly what runs.\n\nThe Discord *desktop* app must be running. The browser client doesn't expose the local IPC bridge that Rich Presence uses.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eother platforms / from source\u003c/b\u003e\u003c/summary\u003e\n\n```sh\ngit clone https://github.com/rar-file/claude-rpc.git\ncd claude-rpc\nnpm install\nnode ./src/cli.js setup     # wires hooks + starts the daemon\n```\n\nOr `npm install -g claude-rpc \u0026\u0026 claude-rpc setup` for the global bin. `setup` starts the daemon for you; manage it afterward with `claude-rpc start | stop | status`. Every mode survives `npm update` without losing your `clientId` — user config lives under the per-OS config dir, not inside `node_modules`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003euse your own Discord app\u003c/b\u003e\u003c/summary\u003e\n\nA working public Discord application is bundled into the default config — you don't need to register your own to get started. If you want a different app name on the card, create one in the [Discord Developer Portal](https://discord.com/developers/applications), copy the Application ID, and drop it into your config:\n\n```sh\n# Linux\necho '{ \"clientId\": \"YOUR_ID\" }' \u003e ~/.config/claude-rpc/config.json\n# macOS\necho '{ \"clientId\": \"YOUR_ID\" }' \u003e ~/Library/Application\\ Support/claude-rpc/config.json\n# Windows (PowerShell)\n'{ \"clientId\": \"YOUR_ID\" }' | Set-Content $env:APPDATA\\claude-rpc\\config.json\n```\n\n`claude-rpc upgrade-config` if you're carrying forward a v0.3-era file.\n\u003c/details\u003e\n\n## what claude-rpc does\n\n### on discord\n\nA card that updates as you work. The large image swaps between five states (working / thinking / idle / stale / notification — those gifs at the top of this README). The two lines of text rotate through frames you template — current file, today's hours, lifetime totals, top hotspot, code churn, cost — and the daemon skips frames whose required template variables are empty. The `SessionEnd` hook clears the card instantly when you close Claude Code; no \"is it still running?\" timeout.\n\nA *View on GitHub →* button appears automatically when your cwd is a git repo with a github origin. The daemon checks `.git/config` directly — no shell-out, no surprise GH API call.\n\nA rotation frame can show your **subscription usage** — `Usage · 34% weekly` — the exact numbers Claude Code's own `/usage` screen shows. The daemon asks Anthropic's usage endpoint with the OAuth token Claude Code already stores locally; the token goes only to its issuer, the percentages go only where you template them, and `usage.enabled: false` turns the whole thing off ([`SECURITY.md` §3d](SECURITY.md)). `claude-rpc usage` prints the same data as heat-graded bars in your terminal.\n\n### on your machine\n\nThree local surfaces, all reading the same `~/.claude-rpc/aggregate.json`:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\u003cb\u003eweb dashboard\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003eclaude-rpc serve\u003c/code\u003e · port 47474\u003c/sub\u003e\u003cbr/\u003e\u003cbr/\u003e\u003cimg src=\"docs/dashboard.png\" alt=\"Web dashboard with range selector, activity chart, heatmap, cost panel, languages stack, and leaderboards\" /\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\u003cb\u003esettings gui\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003enpm run dashboard\u003c/code\u003e · Electron\u003c/sub\u003e\u003cbr/\u003e\u003cbr/\u003e\u003cimg src=\"docs/electron.png\" alt=\"Electron config editor with Presence / Discord / Assets / Timing / Daemon / Stats tabs\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n```text\nclaude-rpc status                 (TUI — heatmap, hour histogram, leaderboards)\nclaude-rpc today                  (today's stats, focused)\nclaude-rpc week                   (weekday breakdown)\nclaude-rpc preview                (every rotation frame rendered with real data)\nclaude-rpc insights               (3–5 auto-generated lines: trend, peak, hotspot)\nclaude-rpc recap --md             (standup-ready: yesterday's projects, ships, churn)\n```\n\nThe web dashboard pushes updates via SSE; the TUI refreshes on a 3-second tick.\n\n### beyond your machine\n\nShields-style badges and a poster-style summary card you can paste into a README or a Discord message. The fastest path is one command:\n\n```sh\nclaude-rpc readme                 # prints paste-ready README badge markdown\nclaude-rpc readme --raw | pbcopy  # straight to your clipboard\n```\n\n**Live card + badges, paste once.** With a public profile (`claude-rpc profile set --handle \u003cyou\u003e \u0026\u0026 claude-rpc profile on`), your stats are served as an always-current card (and badges) from the community worker — no `gh`, no gist, nothing to re-run:\n\n```md\n[![Claude Code stats](https://claude-rpc-totals.claude-rpc.workers.dev/card/\u003cyou\u003e.svg)](https://claude-rpc.com/u/\u003cyou\u003e)\n\n[![Claude Code hours](https://claude-rpc-totals.claude-rpc.workers.dev/badge/\u003cyou\u003e.svg?metric=hours)](https://claude-rpc.com/?ref=badge)\n```\n\nThe card shows tokens, sessions, active hours and streak; badge `metric=` is one of `tokens · sessions · hours · streak` (optional `\u0026label=` to retitle). Both refresh themselves as the daemon flushes your profile (~every 30 min). Your profile page at `/u/\u003cyou\u003e` has a one-click \"copy\" for the whole block.\n\nPrefer to render locally? `badge`/`card`/`calendar`/`github-stat` all write SVG, and `--gist` self-hosts a live one:\n\n```sh\nclaude-rpc badge --metric hours  --range 7d   --out claude-hours.svg\nclaude-rpc badge --metric streak              --out claude-streak.svg\nclaude-rpc badge --metric hours  --gist                                     # publish to a gist (live README badge)\nclaude-rpc card  --range year                 --out year-on-claude.svg\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"site/examples/week-on-claude.svg\"  width=\"270\" alt=\"Week-on-claude summary card\" /\u003e\n  \u003cimg src=\"site/examples/month-on-claude.svg\" width=\"270\" alt=\"Month-on-claude summary card\" /\u003e\n  \u003cimg src=\"site/examples/year-on-claude.svg\"  width=\"270\" alt=\"Year-on-claude summary card — hours, prompts, tokens, lines, cost, daily activity strip\" /\u003e\n  \u003cbr/\u003e\n  \u003csub\u003e\u003ccode\u003ecard --range week · month · year\u003c/code\u003e (also \u003ccode\u003eall\u003c/code\u003e) — live at \u003ccode\u003e/api/card.svg\u003c/code\u003e while the daemon's up\u003c/sub\u003e\n\u003c/div\u003e\n\n`badge --gist` writes the SVG to your own GitHub gist (creates one on first run, updates it after — id remembered in `config.json`). The URL printed back is README-ready and updates every time you re-run the command. Uses `gh` if available, else `GH_TOKEN` with `gist` scope.\n\nLive equivalents when the daemon is up:\n\n- `http://127.0.0.1:47474/api/badge.svg?metric=hours\u0026range=7d`\n- `http://127.0.0.1:47474/api/card.svg?range=year`\n\nCost numbers come from `src/pricing.js`, seeded with **approximate** public list prices. Your actual Claude Code subscription bill is unrelated.\n\n### community totals\n\nThe badges at the top of this README are live, served by a small Cloudflare Worker ([`worker/`](worker/)) that holds running totals of sessions and tokens across every install that's reporting. As of v0.7 **fresh installs are on by default** — `setup` mints an anonymous UUID v4 and the daemon starts flushing deltas every 30 minutes. Existing users upgrading from a pre-v0.7 config stay off until they explicitly run `community on` (the consent flow prints the exact payload first).\n\n```sh\nclaude-rpc community              # show state + instanceId (last 8 chars)\nclaude-rpc community off          # opt out; instanceId retained for re-enable continuity\nclaude-rpc community on           # explicit consent flow (upgraders / re-enable)\nclaude-rpc community report       # one-shot manual flush (testing)\n```\n\nEach report sends only: a `sessionsDelta`, a `tokensDelta`, the claude-rpc version, OS family (`linux`/`darwin`/`win32`), and the anonymous UUID v4. No prompts, paths, models, repos, costs, usernames, or hostnames — the Worker's [`validateReport`](worker/src/index.js) is the schema of record. The full Worker source is in this repo so the privacy claim is auditable. Every worker route — path, params, response — is documented in [`docs/WORKER-API.md`](docs/WORKER-API.md).\n\nFor a complete account of the sensitive things claude-rpc does — startup persistence, hook injection, every outbound request, and the exact telemetry payload — see [`SECURITY.md`](SECURITY.md). It's also the reference for supply-chain scanner findings (Socket.dev et al.): the flagged persistence and hook-injection behaviors are inherent to the tool and documented there.\n\n## three pieces, glued by json files\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/architecture.svg\" width=\"760\" alt=\"Architecture: Claude Code fires a lifecycle event (stdin JSON) into hook.js, which writes state.json; daemon.js reads it and pushes an IPC frame to the Discord desktop client. scanner.js reads the ~/.claude/projects transcripts and feeds aggregate.json into daemon.js.\" /\u003e\n\u003c/div\u003e\n\nNo database, no message bus, no background polling when Claude Code isn't running. State on disk you can `cat` and `jq`. **Zero runtime dependencies** — even the Discord Rich Presence IPC client is hand-rolled (`src/discord-ipc.js`).\n\n1. **hook** ([`src/hook.js`](src/hook.js)) — Claude Code spawns it on every lifecycle event. Parses the JSON from stdin and mutates the shared state file. Runs in ~20ms.\n2. **daemon** ([`src/daemon.js`](src/daemon.js)) — long-running. Connects to Discord's local IPC, watches the state file, pushes presence frames every few seconds. Exponential backoff with jitter on reconnect; `daemon.log` rotates at 5 MB.\n3. **scanner** ([`src/scanner.js`](src/scanner.js)) — walks `~/.claude/projects/**/*.jsonl` for all-time aggregates (active time, prompts, tools, tokens, streaks, hotspots, lines, languages, cost, bash, web, subagents). Incremental — re-parses only changed files.\n\nPersistent state, all human-readable JSON:\n\n| Path | What |\n| ---- | ---- |\n| `$TMPDIR/claude-rpc/state.json` | Current session, volatile |\n| `~/.claude-rpc/aggregate.json` | All-time aggregates |\n| `~/.claude-rpc/scan-cache.json` | Per-transcript scan cache |\n| `~/.claude-rpc/private-list.json` | Runtime privacy toggles |\n| `~/.claude/settings.json` | Hook registrations (managed by `setup`) |\n\nUser config lives at `%APPDATA%\\claude-rpc\\config.json` (Windows), `~/Library/Application Support/claude-rpc/config.json` (macOS), or `$XDG_CONFIG_HOME/claude-rpc/config.json` (Linux). It only needs to hold *overrides* — every key has a baked default. `{ \"clientId\": \"...\" }` is a complete config file. Defaults live in [`src/default-config.js`](src/default-config.js); the loader deep-merges over them.\n\n## privacy\n\nPer-project, runtime, or auto-detected — whichever fits how you work.\n\n```jsonc\n// drop at your project root: \u003cproject\u003e/.claude-rpc.json\n{ \"private\": true }                                  // shortcut for visibility: \"hidden\"\n{ \"visibility\": \"name-only\" }                        // project name only, no file/tool detail\n{ \"projectName\": \"redacted\" }                        // show this name on Discord instead\n```\n\nOr from the command line, in any project:\n\n```sh\nclaude-rpc private        # add cwd to ~/.claude-rpc/private-list.json\nclaude-rpc public         # remove cwd\nclaude-rpc privacy        # show the resolved visibility for the current dir\n```\n\nOr globally, in `config.json`:\n\n```json\n{ \"privacy\": { \"patterns\": [\"client-*\", \"secret-stuff\"], \"mode\": \"hidden\" } }\n```\n\nIf [`gh`](https://cli.github.com/) is installed and authenticated, GitHub-private repos auto-hide (`privacy.githubPrivateMode`, default `hidden` — opt out with `privacy.autoDetectGithubPrivate: false`). 5-minute cache, 1.5s timeout, silent skip when `gh` isn't there.\n\nAggregates and local dashboards are never affected. Privacy is a one-way valve between local state and Discord.\n\n## customizing the card\n\n```sh\nclaude-rpc preview        # render every rotation frame with your real data\nclaude-rpc vars           # dump the full template-variable list as JSON\n```\n\nFrames have a `requires` field; the daemon skips a frame when any of its required vars resolve empty / zero. Write seven frames knowing only the relevant ones render.\n\n```jsonc\n\"idle\": {\n  \"details\": \"Idle in {project}\",\n  \"state\":   \"{modelPretty} · {todayHours} today\",\n  \"rotation\": [\n    { \"details\": \"This week · {weekHours}\",      \"state\": \"{weekPromptsLabel} · {weekTokensFmt} tokens\",\n      \"requires\": [\"weekActiveMs\"] },\n    { \"details\": \"Code churn · {linesAddedFmt} added\",\n      \"state\":   \"{linesNetFmt} net · {topLanguage}\",\n      \"requires\": [\"topLanguage\"] }\n  ]\n}\n```\n\nThe full default config is in [`src/default-config.js`](src/default-config.js) — that's the canonical list of every key. Over 200 template variables are available; `claude-rpc vars` is the authoritative list.\n\n## claude code plugin\n\nPrefer to install from inside Claude Code? There's a [plugin](plugin/) for that:\n\n```text\n/plugin marketplace add rar-file/claude-rpc\n/plugin install claude-rpc@claude-rpc\n```\n\nIt's a thin bootstrapper — on the first session it just runs `npx claude-rpc@latest setup` for you (the same install as above), then stays out of the way. macOS / Linux / WSL; on Windows use the portable exe. Nothing extra is added to your sessions — the plugin is a single `SessionStart` hook with no model-context cost.\n\n## commands\n\n`claude-rpc --help` lists them all — and after `setup` you rarely need any.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003efull command reference\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n| Command          | What it does |\n| ---------------- | ------------ |\n| `setup`          | Install Claude Code hooks (test-fires one synthetic SessionStart to prove the pipe works) |\n| `uninstall`      | Remove Claude Code hooks |\n| `upgrade-config` | Re-run idempotent migrations on `config.json` |\n| `start` / `stop` / `restart` | Lifecycle for the detached daemon |\n| `status`         | Interactive TUI — heatmap, hour histogram, leaderboards (`--dump` for plain output) |\n| `today` / `week` | Focused views (today's stats, weekday breakdown) |\n| `usage`          | Subscription limits — session + weekly %, the same numbers `/usage` shows |\n| `serve`          | Open the local web dashboard (port 47474) |\n| `preview`        | Render every rotation frame against real state |\n| `scan` / `rescan`| Incremental / forced re-parse of `~/.claude/projects` |\n| `backfill \u003cdir\u003e` | Import transcripts from any folder (backup, other machine) |\n| `insights`       | Print 3–5 auto-generated lines about your week |\n| `recap`          | Standup summary — yesterday's work, paste-ready (`today\\|week\\|date`, `--md`) |\n| `badge`          | Shields-style SVG (`--metric` `--range` `--out` `--gist`) |\n| `card`           | Poster-style SVG (`--range year\\|month\\|week\\|all`) |\n| `github-stat`    | Embeddable profile stat card (`--handle` `--out` `--gist`) |\n| `calendar`       | Year activity heatmap SVG (`--out` `--gist`) |\n| `session-card`   | Recap card for the current session (`--out`) |\n| `readme`         | Paste-ready README badge markdown for your profile (`--raw` to pipe) |\n| `statusline`     | One-line status for tmux/shell prompts (`--template`) |\n| `mcp install`    | Wire the stats MCP server into Claude Code (one command) |\n| `mcp`            | Run the MCP server (stdio) for Claude Code |\n| `wrapped`        | Open your animated year-in-review (Claude Wrapped) |\n| `private` / `public` / `privacy` | Per-cwd visibility toggles + status |\n| `community`      | Opt-in community totals — `on` \\| `off` \\| `status` \\| `report` |\n| `doctor`         | Diagnostic checklist with one-line fix hints |\n| `tail` / `logs`  | Tail the daemon log |\n| `daemon`         | Run the daemon in the foreground (debugging) |\n| `vars`           | Dump the full template-var list as JSON |\n\nExit codes: `0` ok · `1` user error · `2` system error · `3` wrong state. `--version` and `--help` work as expected.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ecomplete removal\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n`claude-rpc uninstall` removes everything that *respawns or registers* the tool:\nits hooks from `~/.claude/settings.json` (only its own — third-party hooks are\nleft untouched) and the login-autostart entry (`systemd --user` unit on Linux,\nLaunchAgent on macOS, `HKCU\\…\\Run` value + `.vbs` shim on Windows). After it\nruns, nothing brings the daemon back.\n\nIt deliberately **leaves your data in place**: `config.json` (under the per-OS\nconfig dir), the stats in `~/.claude-rpc/`, and the transient files in the temp\ndir (which clear on reboot anyway). Two things it does *not* touch, by design:\n\n- a daemon already running this session keeps running until `claude-rpc stop` or\n  reboot (the autostart-managed one is stopped; a manually `start`ed one isn't);\n- the MCP server, if you wired it — that's a separate `claude-rpc mcp uninstall`.\n\nFor a clean wipe on macOS/Linux:\n\n```sh\nclaude-rpc mcp uninstall   # only if you ran `mcp install`\nclaude-rpc stop\nclaude-rpc uninstall\nrm -rf ~/.claude-rpc        # stats; plus the per-OS config dir if you want it gone\n```\n\n\u003c/details\u003e\n\n## troubleshooting\n\n**First step is always `claude-rpc doctor`** — it checks Node, hook registration, daemon liveness, Discord IPC, aggregate freshness, and privacy resolution, with a one-line fix hint per failure.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ecommon issues\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n- **Discord doesn't show anything.** Discord *desktop* must be running. The browser client doesn't expose the local IPC bridge. `claude-rpc tail` shows what the daemon is actually doing.\n- **Hooks don't fire.** `claude-rpc setup` re-registers them and now test-fires a synthetic `SessionStart` end-to-end, so a broken hook command surfaces immediately. Restart Claude Code afterwards so it re-reads its hook config.\n- **Config error.** Bad JSON in `config.json` no longer crashes anything — the daemon logs one line and falls back to baked defaults. `claude-rpc tail` shows the parse error verbatim.\n- **Old binary path baked into hooks.** Common after manual exe replacement. `claude-rpc setup` rewrites hook entries to point at the canonical install location.\n\n\u003c/details\u003e\n\n## platform support\n\n**macOS and Linux are first-class.** The daemon reacts to on-disk changes with a\ndirectory watcher (`fs.watch` over FSEvents/inotify — instant) *and* an mtime\npoll as a lazy backstop, so an event is never missed. Login autostart is a\nper-user [`launchd` LaunchAgent](src/install.js) on macOS and a\n[`systemd --user` service](src/install.js) on Linux; both start the daemon at\nlogin without `sudo` and don't fight a manual `claude-rpc stop`.\n\n**Windows is supported** — grab the portable exe (no Node required), then\n`claude-rpc setup`. One caveat documented honestly: `fs.watch` on Windows drops\nevents when a writer commits via atomic rename (which the state file, pause file,\nscanner, and settings GUI all do), so on Windows the **mtime poll is effectively\nthe primary path** and runs an order of magnitude faster (every ~3s vs ~30s\nelsewhere) to compensate. It's a reliable fallback, not yet the native-watch\nconfidence macOS/Linux get — closing that gap is on the [roadmap](ROADMAP.md).\nAutostart is an `HKCU\\…\\Run` entry launched through a windowless `.vbs` shim (no\nscheduled task, by design — see [`SECURITY.md`](SECURITY.md)).\n\nEverything else — the scanner, dashboards, cards, the worker client — is\nplatform-neutral. CI runs the full suite on Node 18/20/22 and builds the macOS\nand Windows binaries every release.\n\n## versioning\n\nWhat's a stable contract and what's an internal detail you shouldn't build on:\n[`VERSIONING.md`](VERSIONING.md). Short version — the worker HTTP API, the CLI\n(commands, flags, exit codes), the `config.json` schema, the `claude-rpc vars`\ntemplate variables, and the local data formats are stable and semver-governed;\ndaemon internals, the scan cache, the worker's KV layout, and exact wording are\nnot. The worker's HTTP surface is documented in\n[`docs/WORKER-API.md`](docs/WORKER-API.md).\n\n## development\n\n```sh\nnpm test                  # 430+ tests, ~2s\nnpm run lint              # eslint over src + test\nnpm run start             # run daemon in foreground\nnpm run serve             # web dashboard against your real data\nnpm run dashboard         # Electron settings GUI (dev mode)\nnpm run build:exe         # SEA single-file binary for the current OS\n```\n\nTests are `node --test`, zero deps; CI ([release.yml](.github/workflows/release.yml)) runs the suite (+ the Worker's) across Node 18/20/22 and gates the matrix build and npm publish. Where the project's headed (and what it'll deliberately never do): [`ROADMAP.md`](ROADMAP.md).\n\n## license\n\n[MIT](LICENSE) © Archer Simmons\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frar-file%2Fclaude-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frar-file%2Fclaude-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frar-file%2Fclaude-rpc/lists"}