AI Agents & Headless Access

Insights is designed to be queried headlessly. Anything you can see in the web UI — server stats, JetStream assets, accounts, audit findings — is reachable as DuckDB SQL via the insights query subcommand, which talks to the running server over NATS. That makes it a natural fit for both shell automation and AI coding agents.

To make agents productive without hand-rolling prompts, every running Insights server publishes a downloadable query-insights skill packaged for the major AI coding tools.

Download

Open the running Insights web UI, click the info dialog (top-right), choose your target format, and download the bundle.

Target format	Bundle contents	Install location
Claude Skill	`query-insights/SKILL.md`	`~/.claude/skills/`
AGENTS.md	`AGENTS.md` (Codex / generic agent format)	Project root
GEMINI.md	`GEMINI.md`	Project root
Cursor Rule	`.cursor/rules/query-insights.mdc`	Project root

On Windows, ~ resolves to %USERPROFILE% (typically C:\Users\<you>); the Claude skill goes in %USERPROFILE%\.claude\skills\. The other three live alongside the project, so they're platform-independent.

The endpoint is GET /skill/query-insights/{agent}/download where {agent} is claude, codex, gemini, or cursor. You can fetch it from the CLI as well:

curl -OJ https://insights.example.com/skill/query-insights/claude/download
unzip query-insights-claude.zip -d ~/.claude/skills/

Using the Skill

Claude Code

After extracting into ~/.claude/skills/, invoke it with:

/query-insights how many connections per cluster right now?

Claude will emit insights query "<SQL>" calls, read the CSV/JSON results, and answer.

Codex / Gemini

Drop AGENTS.md or GEMINI.md at the project root. The agent picks it up automatically as ambient context whenever you ask insights-related questions in that workspace.

Cursor

Place .cursor/rules/query-insights.mdc in the project. The rule is set to alwaysApply: false, so it only kicks in when you explicitly mention insights or the query-insights skill in a chat.

Headless Use Without an Agent

The same CLI underpins the skill, so any shell or automation can drive Insights directly:

# Latest connection count per cluster
insights query "
  SELECT cluster, count(*) AS conns
  FROM hx.conns
  WHERE epoch = (SELECT max(epoch) FROM conn_stats)
  GROUP BY cluster
"

# Critical audit findings as JSON
insights query --format json "
  SELECT cr.code, cr.severity, cr.entity_type
  FROM hx.check_results cr
  WHERE cr.severity = 'critical'
    AND cr.epoch = (SELECT max(epoch) FROM server_stats)
"

The CLI honours the same --nats.* flags as the server, so the same credentials that already reach your Insights deployment are sufficient. See the CLI reference for all flags and the Search reference for the query language.