Skip to content

Introduction

Jump to bottom
Wallace Ricardo edited this page Jun 3, 2026 · 2 revisions

Introduction

claude-code-graphql is a GraphQL analytics server that records Claude Code hook events into SQLite and exposes them via a GraphQL API.

What it does

When you use Claude Code, it fires hooks at key moments — before and after tool calls, when you submit a prompt, when a session ends, and more. claude-code-graphql captures these events, stores them in a local SQLite database with full-text search, and lets you query your coding activity through GraphQL.

The result is a session intelligence layer for Claude Code. You can inspect active work, reconstruct what happened in a session, see which skills and subagents were used, discover files edited, search old prompts/tool output, and identify expensive or error-prone sessions.

Key features

  • Hook ingestion — HTTP endpoint receives hook JSON from Claude Code via claudegql record
  • SQLite + FTS5 — persistent storage with full-text search across prompt, tool input, and tool response
  • Session intelligence — active/recent sessions, prompts, edited files, skills used, subagents spawned, tool usage, errors, duration, git branch, model, token usage
  • Transcript reading — reads .jsonl session files for structured message content and subagents
  • Project discovery — reads ~/.claude/projects/ to surface per-project activity
  • Structured tool inputs — parsedInput union gives typed access to Bash, Read, Edit, Grep, Glob, Write inputs
  • Stop event fields — lastAssistantMessage and stopHookActive parsed from Stop/SubagentStop events
  • Session summaries — LLM-powered summaries via an LLM CLI tool
  • Aggregate stats — top tools, hooks by day, error rates, activity by CWD

How it works

Claude Code → stdin → claudegql record → POST /hook → store.RecordHook()
                                                            ↓
                                              upserts session row
                                              inserts hook row
                                              triggers FTS5 indexing
                                                            ↓
GraphQL ← sessions · projects · hooks · transcripts · stats · search

The platform at a glance

http://localhost:8765/graphql      → GraphQL API
http://localhost:8765/playground   → GraphQL Playground
http://localhost:8765/hook         → Hook ingestion endpoint (POST)
http://localhost:8765/docs         → Documentation

Documentation map

Getting started:

  • Quick Start — build, run, and record your first hook

Concepts:

  • Session Intelligence — active work, skills used, subagents, edits, prompts, errors, token usage, and searchable context
  • Sessions — how sessions are tracked and queried
  • Hooks — the hook event system and event types
  • FTS5 Search — full-text search across hook data

API reference:

  • Sessions — session queries and summarization
  • Projects — project-level analytics
  • Hooks — raw hook queries with filtering and pagination
  • Stats — aggregate statistics
  • Search — full-text search
  • Transcripts — reading session transcripts

Reference:

Clone this wiki locally