Discord Rich Presence를 위한 Claude Code

카드에 표시되는 라이브 상태 — 작업 중(working) · 생각 중(thinking) · 대기 중(waiting) · 유휴(idle)

Claude Code용 Discord Rich Presence — Claude Code가 이미 발생시키는 훅을 통해 사용자의 라이브 모델, 프로젝트, 토큰 및 평생 통계를 표시합니다.

claude-rpc.com → — 한 페이지에서 확인하세요.

라이브 상태는 기본적으로 활성화되어 있으며, 언제든지 비활성화할 수 있습니다. 커뮤니티 총계도 확인해 보세요.

Claude Code가 이미 발생시키는 라이프사이클 이벤트를 가져와 사용자의 프로필에 있는 Discord rich-presence 카드로 전달하는 작은 Node 데몬입니다. 친구들은 당신이 무엇을 만들고 있는지 볼 수 있고, 미래의 당신은 평생 통계를 얻게 됩니다. 주말 동안 혼자 제작되었습니다.

macOS / Linux / 모든 Node 18+ 환경에서 — 하나의 명령어로 실행할 수 있습니다:

npx claude-rpc@latest setup

(@latest는 중요합니다 — 단순히 npx claude-rpc를 사용하면 오래된 캐시 복사본을 재사용하게 됩니다.)

이 명령어는 claude-rpc를 전역적으로 설치하고, 훅을 Claude Code에 연결하며, 데몬을 시작합니다. 별도의 start 단계가 필요 없습니다. Claude Code에서 어떤 프로젝트를 열어도 1초 이내에 카드가 나타납니다. 뭔가 잘못된 것 같나요? claude-rpc doctor
(또는 자동 복구를 위해 claude-rpc doctor --fix)

자동으로 설정해 주는 원라인을 선호하시나요?

curl -fsSL https://claude-rpc.com/install | sh

이 명령어는 Node를 감지하여 (npm 패키지를 설치) 하거나, 미리 빌드된 Apple-Silicon 바이너리로 대체하고, 사용자 대신 setup을 실행합니다.

Homebrew (macOS / Linux):

brew install rar-file/claude-rpc/claude-rpc && claude-rpc setup

Windows (Node가 필요하지 않음) — 최신 릴리스에서 포터블 exe를 다운로드한 다음:

claude-rpc setup

이것이 전체 설명입니다.

setup 명령어는 Windows 시작 항목을 등록하고, Claude Code의 settings.json에 훅을 연결하며, 데몬은 기본적으로 익명 총계를 보고합니다. 마지막에는 선택적인 y/N 질문(GitHub 연결?)으로 끝나는데, '예'라고 답할 경우에만 인증된 공개 리더보드 프로필이 게시됩니다 (한 번만 요청됨; Enter를 누르면 건너뜁니다). 모든 과정은 되돌릴 수 있습니다 (claude-rpc uninstall, community off, profile off)이며, SECURITY.md에 완전히 문서화되어 있으니 — 정확히 무엇이 실행되는지 알고 싶다면 먼저 읽어보세요.

Discord의 데스크톱 앱이 실행되어야 합니다. 브라우저 클라이언트는 Rich Presence가 사용하는 로컬 IPC 브리지를 노출하지 않습니다.

다른 플랫폼 / 소스에서 설치하기

git clone https://github.com/rar-file/claude-rpc.git
cd claude-rpc
npm install
...

또는 전역 bin에 설치하려면 npm install -g claude-rpc && claude-rpc setup을 사용합니다. setup은 데몬을 시작하며, 이후에는 claude-rpc start | stop | status로 관리할 수 있습니다.

모든 모드는 npm update 후에도 clientId를 잃지 않습니다. 사용자 설정은 node_modules 내부가 아닌 OS별 설정 디렉토리에 저장됩니다.

자신만의 Discord 앱 사용하기

작동하는 공개 Discord 애플리케이션이 기본 설정에 포함되어 있어, 시작하기 위해 직접 등록할 필요가 없습니다. 카드에 다른 앱 이름을 원한다면, Discord Developer Portal에서 하나를 만들고 Application ID를 복사하여 설정 파일에 붙여넣으세요:

# Linux
echo '{ "clientId": "YOUR_ID" }' > ~/.config/claude-rpc/config.json
# macOS
...

만약 v0.3 시대의 파일을 가지고 있다면 claude-rpc upgrade-config를 사용하세요.

작업하는 동안 업데이트되는 카드입니다. 큰 이미지는 다섯 가지 상태(working / thinking / idle / stale / notification — 이 README 상단의 gif들) 사이에서 전환됩니다. 두 줄의 텍스트는 현재 파일, 오늘 시간, 평생 총합, 최고 활동지, 코드 변경량, 비용 등 사용자가 템플릿화한 프레임들을 순환하며, 데몬은 필요한 템플릿 변수가 비어 있는 프레임은 건너뜁니다. SessionEnd 후크는 Claude Code를 닫을 때 카드를 즉시 지웁니다. '아직 실행 중인가요?'와 같은 시간 초과가 없습니다.

사용자의 현재 작업 디렉토리(cwd)가 github origin이 있는 git 저장소인 경우, View on GitHub → 버튼이 자동으로 나타납니다. 데몬은 셸 명령을 사용하거나 예상치 못한 GH API 호출을 하는 대신, .git/config를 직접 확인합니다.

회전 프레임에는 구독 사용량(Usage · 34% weekly)과 같은 내용을 표시할 수 있습니다. 이는 Claude Code 자체의 /usage가 보여주는 정확한 수치입니다.

화면에 표시됩니다. 데몬은 Claude Code가 이미 로컬에 저장하고 있는 OAuth 토큰을 사용하여 Anthropic의 사용량 엔드포인트를 요청합니다. 이 토큰은 발급자에게만 전송되며, 백분율 값은 템플릿팅하는 곳에만 전송되고 usage.enabled: false는 전체 기능을 비활성화합니다 (SECURITY.md §3d).

claude-rpc usage: 터미널에서 히트맵 형태로 표시되는 것과 동일한 데이터를 출력합니다.

세 개의 로컬 인터페이스가 모두 동일한 ~/.claude-rpc/aggregate.json 파일을 읽습니다:

• 웹 대시보드: claude-rpc serve · 포트 4747
• 설정 GUI: npm run dashboard · Electron

claude-rpc status (TUI — 히트맵, 시간별 히스토그램, 리더보드)
claude-rpc today (오늘의 통계, 집중)
claude-rpc week (요일별 분석)
...

웹 대시보드는 SSE(Server-Sent Events)를 통해 업데이트를 푸시하고, TUI는 3초 간격으로 새로고침됩니다.

쉴드 스타일 배지(Shields-style badges)와 README에 붙여넣을 수 있는 포스터 스타일 요약 카드를 제공합니다. 가장 빠른 방법은 하나의 명령입니다:

claude-rpc readme # 붙여넣기 준비가 된 README 배지 마크다운 출력
claude-rpc readme --raw | pbcopy # 클립보드로 바로 복사

실시간 통계 + 연간 히트맵, 한 번에 붙여넣으세요. 공개 프로필(claude-rpc profile set --handle <you> && claude-rpc profile on)을 설정하면 커뮤니티 워커가 지난 12개월을 히트맵으로 표시하는 항상 최신 통계 카드를 제공합니다. gh나 gist가 필요하지 않으며, 다시 실행할 것도 없습니다:

[![Claude Code stats](https://claude-rpc-totals.claude-rpc.workers.dev/stats/<you>.svg)](https://claude-rpc.com/u/<you>)
?metric=hours

그리드(grid)를 토큰 대신 시간으로 음영 처리합니다. /heatmap/<you>.svg는 그리드 자체입니다. 여러 기기를 연결하면 해당 날짜들이 합산됩니다. 음영 처리는 사용자 본인의 연도를 기준으로 하므로, 사용량이 적은 사람과 많은 사람 모두 읽기 쉬운 지도를 얻을 수 있습니다. 평생 누적 총합만 게시하려면 config.json에 `

is one of tokens · sessions · hours · streak

(optional &label=

to retitle). Both refresh themselves as the daemon flushes your profile (~every 30 min). Your profile page at /u/<you>
has a one-click "copy" for the whole block.

로컬에서 렌더링하는 것을 선호하십니까? badge
/card
/calendar
/github-stat
모두 SVG를 작성하며, --gist는
직접 호스팅되는 라이브 배지를 제공합니다:

claude-rpc badge --metric hours --range 7d --out claude-hours.svg
claude-rpc badge --metric streak --out claude-streak.svg
claude-rpc badge --metric hours --gist # gist에 게시 (라이브 README 배지)
...

badge --gist는 SVG를 사용자의 GitHub gist에 작성합니다(첫 실행 시 생성하고, 이후에는 업데이트합니다 — id는 config.json에 기억됩니다).
반환되는 URL은 README 준비가 되어 있으며 명령을 다시 실행할 때마다 업데이트됩니다. 사용 가능한 경우 gh를, 그렇지 않으면 gist 범위의 GH_TOKEN을 사용합니다.

데몬이 작동 중일 때의 라이브 동등물:

http://127.0.0.1:47474/api/badge.svg?metric=hours&range=7d
http://127.0.0.1:47474/api/card.svg?range=year

비용 숫자는 src/pricing.js에서 가져오며, 근사치 공공 목록 가격으로 시드됩니다. 실제 Claude Code 구독 청구액과는 무관합니다.

이 README 상단에 있는 배지들은 라이브이며, 보고하는 모든 설치의 세션 및 토큰 누적 합계를 담고 있는 작은 Cloudflare Worker (worker/)가 제공합니다. v0.7 기준 신규 설치는 기본적으로 활성화되어 있으며 — setup은 익명의 UUID v4를 생성하고 데몬이 30분마다 변화량(delta)을 플러시하기 시작합니다. pre-v0.7 구성에서 업그레이드하는 기존 사용자는 명시적으로 community on을 실행할 때까지 비활성화 상태를 유지합니다 (동의 흐름은 정확한 페이로드를 먼저 출력합니다).

claude-rpc community # 상태 + instanceId 표시 (마지막 8자)
claude-rpc community off # 옵트아웃; 재활성화를 위해 instanceId 유지
claude-rpc community on # 명시적 동의 흐름 (업그레이더 / 재활성화)
...

각 보고는 다음만 전송합니다: sessionsDelta,
tokensDelta, claude-rpc 버전, OS 계열 (linux/darwin/win32)

)), 그리고 익명 UUID v4. 프롬프트, 경로, 모델, 리포지토리, 비용, 사용자 이름 또는 호스트 이름은 없습니다 — Worker의 validateReport는 기록 스키마입니다. 전체 Worker 소스 코드는 이 리포에 있으므로 개인 정보 보호 주장이 감사 가능합니다. 모든 worker 라우트(경로, 매개변수, 응답)는 docs/WORKER-API.md에 문서화되어 있습니다.

claude-rpc가 수행하는 민감한 작업들 — 시작 시 지속성(startup persistence), 훅 주입(hook injection), 모든 아웃바운드 요청 및 정확한 원격 측정 페이로드(telemetry payload) — 에 대한 완전한 계정은 SECURITY.md를 참조하십시오. 이곳은 또한 공급망 스캐너 검사 결과(Socket.dev 등)에 대한 참고 자료입니다: 플래그가 지정된 지속성 및 훅 주입 동작은 도구 자체에 내재되어 있으며 여기에 문서화되어 있습니다.

데이터베이스도, 메시지 버스도, Claude Code가 실행되고 있지 않을 때의 백그라운드 폴링도 없습니다. 디스크상의 상태는 cat과 jq로 확인할 수 있습니다. 런타임 종속성 제로(Zero runtime dependencies) — 심지어 Discord Rich Presence IPC 클라이언트조차 직접 구현되었습니다(src/discord-ipc.js).

hook(src/hook.js) — Claude Code는 모든 라이프사이클 이벤트마다 이를 실행합니다. stdin에서 JSON을 파싱하고 공유 상태 파일을 수정합니다. 약 20ms 만에 실행됩니다.daemon(src/daemon.js) — 장시간 실행되는 프로세스입니다. Discord의 로컬 IPC에 연결하고, 상태 파일을 감시하며, 몇 초마다 존재 프레임(presence frames)을 전송합니다. 재연결 시 지터가 포함된 지수 백오프를 사용하며, daemon.log는 5MB 단위로 순환됩니다.scanner(src/scanner.js) — 모든 시간대의 집계 데이터(활성 시간, 프롬프트, 도구, 토큰, 스트릭, 핫스팟, 줄, 언어, 비용, bash, 웹, 서브 에이전트)를 위해 ~/.claude/projects/**/*.jsonl을 순회합니다. 증분적(Incremental)으로 작동하여 변경된 파일만 재파싱합니다.

영구 상태는 모두 사람이 읽을 수 있는 JSON 형식입니다:

사용자 설정은 %APPDATA%\claude-rpc\config.json에 있습니다.

(Windows)의 경우 ~/Library/Application Support/claude-rpc/config.json
(macOS) 또는 $XDG_CONFIG_HOME/claude-rpc/config.json (Linux). 오버라이드(overrides) 값만 포함하면 됩니다. 모든 키는 기본값이 내장되어 있습니다. { "clientId": "..." } 자체가 완전한 설정 파일입니다. 기본값은 src/default-config.js에 있으며, 로더가 이를 깊게 병합(deep-merges)합니다.

사용자가 작업하는 방식에 따라 프로젝트별, 런타임별 또는 자동 감지된 설정을 사용할 수 있습니다.

// 프로젝트 루트 디렉토리에 추가: <project>/.claude-rpc.json
{ "private": true } // 가시성(visibility)의 단축키: "hidden"
{ "visibility": "name-only" } // 프로젝트 이름만 표시, 파일/도구 상세 정보 없음
...

또는 모든 프로젝트에서 명령줄을 통해 설정할 수 있습니다.

claude-rpc private # 현재 작업 디렉토리(cwd)를 ~/.claude-rpc/private-list.json에 추가합니다.
claude-rpc public # 현재 작업 디렉토리를 제거합니다.
claude-rpc privacy # 현재 디렉토리에 대해 해결된 가시성을 표시합니다.

또는 config.json에서 전역적으로 설정할 수 있습니다.

:

{ "privacy": { "patterns": ["client-*", "secret-stuff"], "mode": "hidden" } }

만약 gh가 설치되어 인증되었다면, GitHub 비공개 저장소는 자동으로 숨겨집니다 (privacy.githubPrivateMode, 기본값은 hidden이며, privacy.autoDetectGithubPrivate: false로 비활성화할 수 있습니다). 5분 캐시, 1.5초 타임아웃을 가지며, gh가 없을 때는 조용히 건너뜁니다.

데이터 집계(Aggregates) 및 로컬 대시보드는 영향을 받지 않습니다. 개인 정보 보호는 로컬 상태와 Discord 사이의 일방향 밸브 역할을 합니다.

claude-rpc preview # 실제 데이터로 모든 회전 프레임을 렌더링합니다.
claude-rpc vars # 전체 템플릿 변수 목록을 JSON으로 출력합니다.

프레임에는 requires 필드가 있습니다. 이 필수 변수 중 하나라도 비어 있거나 0인 경우 데몬은 해당 프레임을 건너뜁니다. 관련 있는 프레임만 렌더링된다는 것을 알고 7개의 프레임을 작성하세요.

"idle": {
"details": "프로젝트에서 유휴 상태: {project}",
"state": "{modelPretty} · {todayHours} 오늘",
...

전체 기본 설정은 src/default-config.js에 있습니다. 이곳이 모든 키의 표준 목록입니다. 200개가 넘는 템플릿 변수를 사용할 수 있으며, claude-rpc vars가 권위 있는 목록입니다.

Claude Code 내부에서 설치하는 것을 선호하시나요? 이를 위한 플러그인이 있습니다:

/plugin marketplace add rar-file/claude-rpc
/plugin install claude-rpc@claude-rpc

이것은 단순한 부트스트래퍼(bootstrapper)입니다. 첫 세션에서 npx claude-rpc@latest setup을 실행하여 사용자님을 위해 (위와 동일하게 설치하며), 그 후에는 방해되지 않게 유지됩니다. macOS / Linux / WSL의 경우, Windows에서는 포터블 exe를 사용합니다. 세션에 추가되는 것은 아무것도 없으며, 이 플러그인은 모델 컨텍스트 비용이 없는 단일 SessionStart 훅입니다.

claude-rpc --help

여기서 모든 것을 나열하며, setup 이후에는 거의 필요하지 않습니다.

전체 명령어 참고 자료