Claude Observatory는 ~/.claude 디렉토리를 검색 가능하고 시각적인 커맨드 센터(Command Center)로 변환합니다 — 16개의 모듈, 실시간 SSE 업데이트, 외부 네트워크 연결 없음. 그 내부 구성과 제가 이것을 구축한 이유를 소개합니다. 모든 Claude 세션, 모든 토큰, 모든 명령어를 가시화합니다. 만약 당신이 Claude Code를 매일 사용한다면, 당신의 ~/.claude/ 디렉토리에는 이미 스스로에게 던지는 대부분의 질문에 대한 답이 들어 있습니다: "지난주에 Claude에 얼마를 썼고, 어떤 프로젝트에 사용했는가?" "3주 전에 그 프롬프트를 어디에 작성했는가?" "어떤 도구 호출(Tool calls)이 가장 느리거나 가장 많이 실패하는가?" "이 프로젝트를 위해 실제로 로드된 기술(Skills), MCP, 그리고 CLAUDE.md 파일은 무엇인가?" "Claude에게 무엇을 시켰는데 내가 후속 조치를 잊어버렸는가?" 데이터는 폴더 곳곳에 흩어진 JSONL 파일, SQLite 데이터베이스, 그리고 설정 블롭(Config blobs) 형태로 바로 그곳에 있습니다. 단지 브라우징이 불가능할 뿐입니다. 그래서 저는 Claude Observatory를 구축했습니다 — ~/.claude/를 읽어 SQLite로 인덱싱하고, 16개의 모듈과 7개의 "킬러(Killer)" 기능을 제공하는 로컬 우선(Local-first) Next.js 대시보드입니다. 외부 네트워크 연결이 없으며, 127.0.0.1에 바인딩되어 있고, 텔레메트리(Telemetry)도 없습니다. 당신의 데이터는 절대 기기를 떠나지 않습니다. 이것은 기술적인 투어입니다: 무엇이 들어있는지, 어떻게 연결되어 있는지, 그리고 이를 출시하며 무엇을 배웠는지에 대한 내용입니다. 대시보드 한눈에 보기: 커맨드 센터(Command Center)는 홈 페이지입니다 — 오늘의 지출, 최근 세션, 실시간 상태 표시 점(Status dot), 그리고 각 모듈로 연결되는 빠른 링크를 제공합니다. 터미널 환경에서 작업하는 분들을 위한 다크 테마(Dark theme)도 있습니다: 왼쪽 사이드바는 내비게이션의 중추 역할을 합니다. 모든 모듈은 별도의 경로(Route)이며, 모든 경로는 북마크가 가능합니다. 상단의 실시간 상태 표시 점은 파일 와처(File watcher)가 연결되어 있는지 알려줍니다.

세 개의 계층 구조(three-layer architecture)를 가지고 있습니다: ~/.claude/ → Index Layer → UI (Next.js). 이 구조는 다음과 같습니다:
├── projects/*.jsonl
├── parser workers
├── 16개 모듈 라우트
├── sessions/
│ ├── SQLite + FTS5
│ ├── 실시간 SSE 업데이트(live SSE updates)
│ ├── todos/
│ │ └── chokidar watcher
│ ├── recharts/d3 viz
│ ├── skills/
│ ├── API 라우트
│ └── monaco editor
├── bash-commands.log
└── SSE 스트림
├── cost-tracker.log
└── 17개 이상의 소스(sources)
사용 스택(Stack): Next.js 16 (App Router) · React 19 · TypeScript strict · Tailwind 4 · shadcn/ui · FTS5를 사용한 better-sqlite3 · zod · chokidar · TanStack Query · zustand · recharts · d3 · Monaco Editor.

왜 호스팅되는 Postgres 대신 로컬 SQLite를 사용할까요? 데이터가 로컬이기 때문입니다. 클라우드 DB를 통해 대화 기록을 왕복(round-tripping)하는 것만으로도 자신의 지출에 대한 차트를 렌더링하려면 잘못된 트레이드오프(tradeoff)입니다. better-sqlite3는 동기식(synchronous)이며 앱 옆에 위치하고, 대부분의 페이지에서 전체 16개 모듈 대시보드를 50ms p95 이하로 실행합니다.

16개 모듈: 여기 전체 목록이 있습니다 — Command Center · Sessions · Search · Cost & Tokens · Tool Heatmap · Bash Explorer · File History · Skills · MCP Hub · Memory · Todos · Activity · Telemetry · Prompts · Settings · Headless & Agent Mode.

가장 놀라웠던 것들을 보여드리겠습니다. Sessions Explorer는 프로젝트/모델/상태/텍스트 내용별로 필터링할 수 있는 모든 세션 목록을 제공합니다. 클릭하면 전체 대화 내용을 볼 수 있습니다. 이 페이지는 내가 주고받은 대화를 어렴풋이 기억해내고 원문 기록(verbatim transcript)을 원할 때 여는 페이지입니다. Cost & Token Analytics는 프로젝트별, 모델별로 일간/주간/월간 USD 및 토큰 내역을 분석합니다. 이 페이지를 제 자신의 데이터로 처음 열었을 때 저는 즉시 세 가지 업무 흐름(workflow) 변경을 했습니다. 이것이 바로 대시보드의 목적입니다. Tool Usage Heatmap은 캘린더 히트맵 + 24시간 분포 + 도구별 테이블 + 이상치(outliers)를 보여줍니다. p95 = 14.9ms.

json_extract를 통해 tool_calls 테이블 위에서 구축되었으며, 스키마 마이그레이션(schema migration)이 필요하지 않습니다.

파일 히스토리 및 디프 (File History & Diff)
Claude가 작성하거나 수정한 모든 파일을 상세 페이지에서 지연 로딩(lazy-loaded)되는 Monaco DiffEditor와 함께 보여줍니다. 제 컴퓨터에는 676개의 파일이 인덱싱되어 있습니다. 커밋(commit) 내역을 일일이 읽고 싶지는 않지만 특정 편집 사항을 되돌리고 싶을 때 유용합니다.

스킬 라이브러리 (Skills Library)
~/.claude/skills/ 및 ~/.claude/plugins/*/skills/ 아래에 있는 모든 스킬의 목록을 FTS5 기반의 트리거 횟수와 함께 보여줍니다. 제 컴퓨터에는 862개의 스킬이 있습니다. 오타가 아닙니다.

MCP 허브 (MCP Hub)
선언된 MCP(mcp.json)와 관찰된 MCP 서버들을 하나의 뷰로 병합하여 보여주며, 표시 전 환경 변수(env values)를 제거(scrubbed)합니다. 무엇이 실제로 연결되어 있는지, 그리고 당신이 연결되어 있다고 생각하는 것과 무엇이 다른지를 알려줍니다.

메모리 익스플로러 (Memory Explorer)
모든 CLAUDE.md 파일과 ~/.claude/projects/<id>/memory/*.md 아래의 자동 메모리 저장소(auto-memory store)를 보여줍니다. 6가지 범위(scope)가 있습니다 (global / project / .claude / nested / auto-index / auto). 상세 페이지의 사이드바에는 형제(siblings) 항목들이 표시되어, 페이지를 떠나지 않고도 프로젝트의 전체 메모리 트리(memory tree)를 탐색할 수 있습니다.

할 일 목록 (Todos)
모든 세션에 걸친 TodoWrite 항목을 4단계 상태 필터와 함께 보여주며, '진행 중(in_progress)' 상태가 7일 이상 지속된 항목을 위한 '방치된 할 일(abandoned-todo)' 패널을 제공합니다. 처음 실행했을 때 제 컴퓨터에는 30개의 파일, 37개의 항목, 13개의 방치된 항목이 있었습니다. (그 후 저는 생산적인 오후를 보냈습니다.)

활동 히트맵 (Activity Heatmap)
일별 세션의 캘린더 히트맵, 현재 연속 기록(streak), 가장 바쁜 시간대를 보여줍니다. /tools의 히트맵 컴포넌트를 재사용했습니다. 연속 기록 추적은 예상치 못한 방식으로 동기부여가 되었습니다.

텔레메트리 (Telemetry)
에러율, 가장 느린 도구, 재시도 횟수를 보여줍니다. 30일 기준: 4,986회 호출, 에러율 9.7%, 'Write' 도구가 17.9%로 가장 성능이 저조합니다. 현재 JSONL 파일에 tool_calls.duration_ms 값이 채워져 있지 않아 지연 시간 히스토그램(latency histograms)은 제외했습니다. 페이지의 정직한 배너가 이 내용을 설명해 줍니다.

프롬프트 라이브러리 (Prompt Library)
요청 시 ~/.claude/history.jsonl을 읽습니다. 가장 많이 재사용된 프롬프트, 프로젝트 측면(facets), 슬래시 명령(slash-command) 빈도수를 보여줍니다. p95 = 3ms.

설정 (Settings, 첫 번째 쓰기 가능 인터페이스)
이곳에 변이(Mutations)가 존재합니다 — 아래의 "실수 없이 편집하기(Editing without footguns)" 섹션을 참조하세요.

Headless & Agent Mode는 claude -p 실행과 agent-harness 세션 피드(feed)를 조사합니다. 자신의 컴퓨터를 Claude 서버로 사용하고 싶다면 이를 API Server 모듈과 결합하세요: 폴링(polling) 없는 실시간 업데이트. The Observatory는 chokidar를 사용하여 ~/.claude/를 실시간으로 감시합니다 (400ms trailing-edge 디바운스 적용). Claude Code가 새로운 JSONL 라인을 작성하면, /api/stream의 SSE 스트림이 관련 TanStack Query 키를 무효화(invalidate)하며, UI는 새로고침 없이 업데이트됩니다. 사이드바의 LiveStatusDot은 다음 세 가지 상태 중 하나를 표시합니다: ● Live (녹색) — 감시자(watcher) 연결됨, 최근 이벤트 발생 ● Starting (황색) — 감시자 초기화 중 ● Offline (적색) — 감시자 연결 해제. 세 가지 색상, 하나의 컴포넌트, 혼란 제로. 처음에는 react-use-websocket을 시도했으나 제거했습니다. SSE는 더 단순하고, 단방향이며, 프록시(proxy)를 통과할 수 있고, '감시자 → 브로드캐스터(broadcaster) → SSE → 쿼리 무효화'로 이어지는 전체 파이프라인이 약 150줄 내외로 구현됩니다.

실수 없이 편집하기 (Editing without footguns)
~/.claude/에 대한 쓰기 작업은 기본적으로 꺼져 있습니다. 이를 활성화하려면:

1. /settings로 이동합니다.
2. Mutations 토글을 ON으로 전환합니다 (zustand+localStorage에 저장됨).

이후의 모든 쓰기 요청에는 X-Mutations-Confirmed: 1 헤더가 포함됩니다.

• 서버 측 핸들러는 이 헤더가 없는 모든 쓰기 작업을 거부합니다.
• 모든 덮어쓰기는 타임스탬프가 찍힌 백업을 생성합니다 (예: settings.json.bak.2026-05-15T12-30-00).
• 인메모리(in-memory) 감사 로그(audit log)는 거부된 요청을 포함하여 모든 쓰기 시도를 보여줍니다.

이는 UI뿐만 아니라 코드 수준에서 강제됩니다. 게이트(gate)를 통하지 않고 앱에서 ~/.claude/를 변이(mutate)할 수 있는 방법은 없습니다. 저는 사용자의 설정 디렉토리에 접근하는 모든 도구에 대해 이 패턴을 강력히 추천합니다 — 클라이언트 상태의 토글, 전송 중인 헤더, 서버의 게이트, 인메모리 감사 로그. 네 개의 계층이며, 모두 비용이 저렴합니다.

7가지 핵심 기능 (The 7 killer features)
모듈은 무슨 일이 일어났는지 알려줍니다. 핵심 기능은 그것으로 무엇을 할 수 있는지를 바꿉니다:

• 타임 트래블 리플레이 및 포크 (Time-Travel Replay & Fork) — AI 대화에 적용되는 Git rebase.
• 히스토리 질문하기 (Ask Your History) — 전체 Claude 히스토리에 대한 자연어 질의응답(Q&A).
• 트윈 (The Twin) — 사용자에 맞춰 미세 조정(fine-tuned)된 특화된 에이전트.

Self-Evolving CLAUDE.md — 매주 자율적으로 더 똑똑해지는 AI.
AI ROI Dashboard — "Claude를 쓸 가치가 있는가?"라는 질문에 종지부를 찍을 단 하나의 수치.
Budget Autopilot — 스스로 작동하는 지출 거버넌스 (Spend governance).
Personal Headless API — 당신의 머신이 Claude 서버가 됩니다.

일부는 오늘 알파 버전으로 배포됩니다:
Ask Your History는 로컬 프롬프트-투-SQL (prompt-to-SQL) 파이프라인을 사용합니다. 질문을 입력하면 시스템이 인덱스(index)를 대상으로 SELECT 문을 생성하고 평이한 영어로 답변합니다. "지난달 Reddit SaaS 프로젝트에 얼마를 썼지?"라는 질문은 차트와 문장으로 변환됩니다.

AI ROI Dashboard는 모든 팀이 결국 던지게 되는 단 하나의 질문에 답합니다. 이것은 마법이 아닙니다. 여러분이 이미 가지고 있는 모든 수치를 비율 (ratio)로 제시할 뿐입니다.

Budget Autopilot은 프로젝트별 및 월별 한도를 설정하고 이상 징후 알림 (anomaly alerts)을 제공합니다. 소진율 (Burn rate)을 한눈에 확인할 수 있습니다.

Self-Evolving CLAUDE.md는 사용자의 세션을 모니터링하고 매주 CLAUDE.md 개선 사항을 제안합니다. 추가(Append), 수락(Accept), 거절(Reject)은 모두 사용자의 결정이며, 절대 자동으로 이루어지지 않습니다.

개인정보 보호 (Privacy): 대부분의 관측성 (observability) 도구들이 생략하는 부분
개발 서버는 127.0.0.1에 바인딩됩니다. 절대 0.0.0.0이 아닙니다. 무료 티어에서는 외부 네트워크 트래픽 (outbound network traffic)이 전혀 발생하지 않습니다. 클라우드 동기화, AI 요약, 그리고 Headless API는 명시적인 선택 사항 (opt-ins)입니다. .credentials.json은 절대 읽거나 표시되지 않으며, UI에는 'Connected · expires in Nd'라는 문자열만 표시됩니다. SQLite 인덱스는 data/observatory.db 경로에 앱과 함께 존재하며, pnpm db:reset 명령으로 언제든 삭제할 수 있습니다. 워처 (watcher)는 읽기 전용이며, Mutations 기능이 켜져 있지 않는 한 ~/.claude/에 절대 쓰지 않습니다. 다른 도구의 홈 디렉토리를 조사하는 도구를 만든다면, 최소한 무엇을 건드리고 무엇을 건드리지 않는지에 대해 명확하게 알리는 것이 필수적입니다. 위협 모델 (threat model)은 SECURITY.md에 명시되어 있으며 테스트를 통해 강제됩니다.

첫 실행 설정:
pnpm install
pnpm scan:initial # ~/.claude/에 대한 일회성 전체 인덱싱
pnpm dev # http://127.0.0.1:7777 에서 서비스 시작

초기 스캔이 시간이 걸리는 부분이며, 그 이후의 모든 과정은 워처를 통해 증분 (incremental) 방식으로 이루어집니다. 데이터가 쌓인 ~/.claude/ 디렉토리의 경우 첫 스캔은 약 1분 정도 소요됩니다. 그 이후에는 대시보드가 1초 미만으로 빠르게 열립니다.

다시 시작한다면 다르게 구축했을 세 가지

짧게 세 가지만 말씀드리겠습니다:

1. 스캐너(Scanner)가 아닌 와처(Watcher)부터 시작하세요. 저는 전체 스캔(Full-scan) 파이프라인을 먼저 구축한 뒤 나중에 실시간 업데이트 기능을 덧붙였습니다. 첫날부터 증분(Incremental) 방식을 구축했다면 훨씬 깔끔했을 것입니다.

2. tool_calls.duration_ms를 희망 사항으로 취급하세요. 현재의 JSONL 파일에는 이 값이 안정적으로 채워지지 않습니다. 존재하지 않을 수도 있는 필드를 기반으로 히스토그램(Histogram)을 구축하지 마세요.

3. 하나의 게이트, 네 개의 레이어. Mutations 패턴(토글 → 헤더 → 서버 확인 → 감사 로그)은 제가 가장 자랑스럽게 생각하는 설계입니다. 사후에 수정하는 것이 아니라 처음부터 구축할 가치가 있습니다.

직접 사용해보고 싶으시다면 DM을 보내주세요. 저장소(Repository)를 보내드리겠습니다. Solo 티어는 MIT 라이선스의 오픈 소스로 공개될 예정입니다.

127.0.0.1에 바인딩하고, pnpm scan:initial을 실행한 뒤 http://127.0.0.1:7777 을 여세요. Claude Code를 매일 사용하신다면 10분만 투자해 보세요. 그리고 /cost와 /tools에서 무엇을 발견했는지 알려주세요. 만약 이를 기반으로 모듈을 만드신다면 꼭 보고 싶습니다. 현재 16개의 모듈이 있으며, 아키텍처는 파서 레이어(Parser layer) + 쿼리 레이어(Query layer) + 라우트(Route)로 구성되어 있어 17번째 모듈을 추가하는 데는 정말로 단 한 오후면 충분합니다.

Andy / Creative Brain Inc. — Toronto, Ontario.
andy@creativebrain.ca 로 연락주세요.