Quick Start

Quick Start

Get claude-code-graphql running and recording your Claude Code activity.

Build

make build

Produces bin/claudegql.

Start the server

Run in the foreground (blocks terminal):

make run

Or in the background (recommended — logs go to claudegql.log):

make run-bg

You should see:

server:     http://localhost:8765/graphql
playground: http://localhost:8765/playground
hook:       POST http://localhost:8765/hook
docs:       http://localhost:8765/docs

Install hooks

Register the hooks in ~/.claude/settings.json so Claude Code starts sending events:

make install-hooks

This adds claudegql record as the hook command for these event types: PreToolUse · PostToolUse · Stop · SubagentStop · Notification · SessionStart · SessionEnd · UserPromptSubmit · PreCompact · PostCompact

Verify it's working

Send a test event:

make record-test

Then query with the built-in CLI:

claudegql query '{ hooks(limit: 1) { id eventType recordedAt } }'
claudegql query '{ sessions(limit:5) { id status cwd model lastSeenAt } }'

Print the compact schema for ad-hoc exploration or LLM context:

claudegql schema

Or open the Playground at http://localhost:8765/playground and run:

{
  stats {
    totalSessions
    totalHooks
    hooksByEventType { eventType count }
  }
}

Stop the server

make stop

Next steps

• Session Intelligence — discover active work, skills used, subagents, edits, prompts, errors, and token usage
• Sessions API — query your coding sessions
• Hooks API — filter and paginate raw events
• Search — full-text search across all hook data
• Environment Variables — configure the server