Graphsignal Context Client

CLI for Graphsignal: login (store API key), query signal summary and signal context, and fetch signal guide content from Graphsignal API. You can also install a skill so your AI coding agent (Cursor, Claude Code, Codex, etc.) can run the CLI and use the returned context to help optimize inference, profiles, or errors.

Install

pip install graphsignal-context

Or install as an isolated CLI tool with uv:

uv tool install graphsignal-context

Usage

Login

Store your Graphsignal API key in ~/.graphsignal/config.yml:

graphsignal-context login

You will be prompted for your API key.

You can also set credentials via environment variable:

export GRAPHSIGNAL_API_KEY=<your_api_key>

Optionally override API endpoint (for local/self-hosted testing):

export GRAPHSIGNAL_API_BASE=http://signal-api:8080

Summary

Query the pre-computed signal summary (performance analysis) for a time range: engine info and all engine metrics reduced to scalars with trend hints, host info and metrics, traffic and latency stats, GPU time by kernel class, GPU memory and NVML metrics, prefill/decode phases, bottleneck findings, anomalies, and grouped errors. Requires being logged in.

The summary describes a single engine run: --tags must include the run.uid tag (set automatically by the profiler per engine process launch), otherwise the API returns an error. Find values in meta.available_tags of a signals response.

graphsignal-context summary --start 2026-03-10T00:00:00Z --end 2026-03-12T00:00:00Z --tags "run.uid:1a2b3c4d5e6f"

Additional tag filters (after run.uid) work the same as for signals. The command calls GET /api/v1/context/summary/ and prints the response summary as JSON. The summary is small and scalar-only — start with it, and fetch full signals context to drill down.

Signals

Query signal context for a time range. Requires being logged in.

graphsignal-context signals --start 2026-03-10T00:00:00Z --end 2026-03-12T00:00:00Z

Optional --tags filter (semicolon-separated key:value pairs). Tags must match exactly the tags sent to Graphsignal when the app was instrumented:

graphsignal-context signals --start 2026-03-10T00:00:00Z --end 2026-03-12T00:00:00Z --tags "env:prod"

The command calls GET /api/v1/context/signals/ on GRAPHSIGNAL_API_BASE (or https://api.graphsignal.com by default) with start_time_ns, end_time_ns, and optional tags, and prints the response context.

Guide

Fetch guide content about signals.

graphsignal-context guide

The command calls GET /api/v1/context/guide/ on GRAPHSIGNAL_API_BASE (or https://api.graphsignal.com by default) and prints the returned text.

AI agent integration

Install the Graphsignal skill so your AI coding agent can run graphsignal-context summary and graphsignal-context signals for a time range and use the returned findings and context (profiles, errors, traces) to help you optimize.

Claude Code — Clone the repo into Claude's personal skills directory:

git clone https://github.com/graphsignal/graphsignal-context ~/.claude/skills/graphsignal-context

Other agents (Cursor, Codex, Gemini) — Use the skills.sh registry:

npx skills add graphsignal/graphsignal-context

Install the CLI first (pip install graphsignal-context or uv tool install graphsignal-context), then run graphsignal-context login with your API key.

Supported agents

• Cursor — Use the skill when working in Cursor with agent/composer.
• Claude Code — Use with Claude Code (e.g. via Claude CLI or supported IDEs).
• Codex — Use with Codex agent workflows.
• Gemini CLI — Use with Gemini from the command line.

Example prompts

Once the skill is installed, you can ask the agent to:

• Find the root cause of a latency spike — e.g. "Fetch Graphsignal data for the last 2 hours and find the root cause of the latency spike" or "What's causing the slowdown? Use Graphsignal signal context from 10am to noon today."
• Explain errors or failures — e.g. "Get signal context for the last 24 hours and summarize any errors or failures" or "Why did inference fail around 3pm? Pull Graphsignal data for that window."
• Inspect profiles and bottlenecks — e.g. "Get Graphsignal context for yesterday and identify the main performance bottlenecks" or "Which operations are taking the most time? Use Graphsignal data from the last 6 hours."

The agent will call graphsignal-context signals to discover run.uid values in meta.available_tags, then graphsignal-context summary --start <ISO> --end <ISO> --tags "run.uid:<uid>" to get findings and stats, drilling into full-resolution signals context when needed.