{"id":50413554,"url":"https://github.com/gmoon92/claude-spyglass","last_synced_at":"2026-05-31T05:00:48.177Z","repository":{"id":354545520,"uuid":"1191532099","full_name":"gmoon92/claude-spyglass","owner":"gmoon92","description":"ClaudeSpyglass is a local DevTools for Claude Code CLI that intercepts and analyzes every request in real time. It tracks prompts, tool calls, and execution traces, providing structured logs, token usage, and latency insights to help developers understand and debug AI behavior.","archived":false,"fork":false,"pushed_at":"2026-05-30T06:23:16.000Z","size":12360,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T07:19:14.148Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmoon92.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"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-03-25T10:38:58.000Z","updated_at":"2026-05-30T06:23:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gmoon92/claude-spyglass","commit_stats":null,"previous_names":["gmoon92/claude-spyglass"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/gmoon92/claude-spyglass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmoon92%2Fclaude-spyglass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmoon92%2Fclaude-spyglass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmoon92%2Fclaude-spyglass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmoon92%2Fclaude-spyglass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmoon92","download_url":"https://codeload.github.com/gmoon92/claude-spyglass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmoon92%2Fclaude-spyglass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33719601,"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-05-31T02:00:06.040Z","response_time":95,"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":[],"created_at":"2026-05-31T05:00:47.534Z","updated_at":"2026-05-31T05:00:48.169Z","avatar_url":"https://github.com/gmoon92.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔭 Spyglass\n\n`claude-spyglass` helps you inspect what actually happens inside Claude Code sessions:\n\n* hidden system prompt growth\n* rule, skill, and agent injection propagation\n* context inflation\n* runtime anomalies (spike · loop · slow)\n* session structure and tool activity\n* context flow graph (turn → tool → meta-document relationships)\n* API token usage, cost, and latency\n\nUnlike most Claude tooling focused on productivity, `claude-spyglass` focuses on visibility.\n\n---\n\n## Install\n\nSpyglass supports two deployment modes — both fully supported and share `~/.spyglass/` state.\n\n### 1. Headless mode — Homebrew Formula (recommended)\n\nBun standalone server + CLI + browser dashboard.\n\n```bash\nbrew tap gmoon92/spyglass\nbrew install spyglass\n\n# Persistent (auto-start at login):\nbrew services start spyglass\nspyglass open\n\n# Or manual mode (current session only):\nspyglass start\nspyglass open\n\n# Update:\nbrew upgrade spyglass\n```\n\nThe bundled binary embeds the Bun runtime — **no system Bun required**.\n\n### 2. Local agent mode — Electron app\n\nSame backend wrapped in a dock-aware shell. Use when dock visibility and OS\nintegration matter (daily on-machine use). Download the DMG from GitHub Releases.\n\n### Uninstall\n\n```bash\nbrew uninstall spyglass\nrm -rf ~/.spyglass    # optional — wipe local data\n```\n\n### From source (contributors)\n\n```bash\ngit clone https://github.com/gmoon92/claude-spyglass.git\ncd claude-spyglass\nbun install\nbun run dev\n```\n\n---\n\n## Why this exists\n\nOne day, a non-engineer on our team suddenly started hitting 80% context usage with a single prompt.\n\nThe prompt itself was small.\nNo large attachments were used.\nThe session was nearly empty.\n\nSomething inside the runtime had changed.\n\nUsing `claude-spyglass`, we traced the issue to:\n\n* ~30 rule documents\n* accidentally committed without proper scoping metadata\n* globally injected into Claude Code system prompts\n\nThe system prompt had silently exploded.\n\nWithout runtime visibility, finding the root cause would have been extremely difficult.\n\n---\n\n## What spyglass helps you see\n\n### Hidden system prompt growth\n\nSee how rules, CLAUDE.md files, hooks, and runtime injections affect the actual prompt size.\n\n### Context inflation sources\n\nIdentify which files or runtime components consume context budget.\n\n### Runtime tracing\n\nHook path — inspect:\n\n* tool call flow and timing (PreToolUse / PostToolUse)\n* session structure and event sequence\n* turn-level token accumulation\n\nProxy path (opt-in) — inspect:\n\n* full API request and response metadata\n* input / output / cache tokens and estimated cost\n* tokens per second (TPS) and time to first token (TTFT)\n* system prompt content and hash\n\n### Context flow graph\n\nSee how a session actually unfolds as a graph of relationships, not just a flat log.\nTurn → tool call → meta-document edges are streamed from SQLite into a local\nembedded Ladybug graph by a background sync worker, so the dashboard can show\nancestor/descendant flows, hot paths, and which rules or agents a given tool\ncall pulled in.\n\n### Behavior definition catalog\n\nUnderstand which agents, skills, and commands are active in a session.\nSpyglass scans `.claude/agents`, `.claude/skills`, and `.claude/commands` across the project\nchain and global `~/.claude`, resolves priority, and shows the effective catalog per workspace.\n\n### Rule propagation\n\nUnderstand how CLAUDE.md files and rules are injected and propagated across sessions.\nSee which rules are active in each project and where they originate.\n\n### Runtime anomaly detection\n\nDetect three categories of runtime anomaly:\n\n* **spike** — prompt token input exceeds 200% of the session average\n* **loop** — the same tool is called 3 or more times consecutively within a turn\n* **slow** — tool call duration exceeds the P95 threshold across all calls\n\n---\n\n## Local-first by design\n\n`claude-spyglass` runs entirely on your machine.\n\nNo hosted backend.\nNo remote telemetry.\nNo prompt uploads.\n\nYour:\n\n* prompts\n* source code\n* internal rules\n* session artifacts\n* runtime metadata\n\nnever leave your local environment.\n\n---\n\n## How it works\n\n`claude-spyglass` collects runtime data from Claude Code through two independent paths.\n\n**Hook path** (always active): Claude Code fires events at each turn via registered hooks.\nThe hook script pushes raw payloads to the local server, which normalizes and stores them.\n\n**Proxy path** (opt-in): When `ANTHROPIC_BASE_URL` is pointed at the local server,\nall API traffic is intercepted. This unlocks full request/response capture, TPS, and TTFT.\n\nBoth paths write to the same local SQLite database. Updates stream to clients via SSE\n(`GET /events`), and a background sync worker projects the data into the Ladybug graph.\n\n```text\n── Hook Path (always on) ──────────────────────────────\nClaude Code CLI\n  →  spyglass-collect.sh\n        →  POST /collect   (UserPromptSubmit · Pre/PostToolUse)\n        →  POST /events    (SessionStart · Stop · SessionEnd · …)\n── Proxy Path (opt-in) ────────────────────────────────\nClaude Code CLI  →  Spyglass Server :9999/v1/*  →  Anthropic API\n── Storage \u0026 streaming ────────────────────────────────\nboth paths  →  ~/.spyglass/spyglass.db (SQLite)\n            →  SSE  GET /events                (live dashboard push)\n            →  graph sync worker  →  Ladybug context-flow graph\n```\n\nThis enables:\n\n* runtime tracing\n* prompt inspection\n* context analysis\n* token and latency telemetry\n* meta-document catalog (rules, skills, CLAUDE.md)\n* runtime diffing\n\n---\n\n## Architecture\n\n![Claude Spyglass Architecture — Hook Path + Proxy Path with Storage, Meta-docs Catalog, Metrics \u0026 Analysis, SSE/REST channels, and Web/TUI clients](docs/architecture/images/architecture.png)\n\n---\n\n## Use cases\n\n* Investigating sudden context inflation\n* Understanding hidden prompt and rule injections\n* Debugging Claude Code runtime behavior\n* Auditing active agents, skills, and commands per workspace\n* Analyzing session structure and tool call patterns\n* Measuring real API cost and token burn rate\n* Detecting prompt spikes, tool loops, and slow calls\n* Team-level Claude Code governance\n\n---\n\n## Philosophy\n\nAI coding assistants are becoming increasingly complex runtime systems.\n\nBut most of their behavior remains invisible.\n\n`claude-spyglass` exists to make Claude Code observable.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmoon92%2Fclaude-spyglass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmoon92%2Fclaude-spyglass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmoon92%2Fclaude-spyglass/lists"}