SynadiaDocs

Synadia Insights

AI Agents

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 formatBundle contentsInstall location
Claude Skillquery-insights/SKILL.md~/.claude/skills/
AGENTS.mdAGENTS.md (Codex / generic agent format)Project root
GEMINI.mdGEMINI.mdProject root
Cursor Rule.cursor/rules/query-insights.mdcProject 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

Point the agent at the right NATS URL

The skill emits insights query calls that reach the running server over NATS, so the agent's environment must point at the correct URL for your deployment topology:

  • Embedded sink (default) — Insights runs an internal NATS server. By default it binds to 127.0.0.1 on a random port, printed to the server logs at startup; you can read it from there and pass it to the agent. For a stable URL across restarts, pin it with --sink.host / --sink.port (for example --sink.port=4222) and use that as the --nats.server value.
  • External sink (--sink.embed=false) — point insights query at the same external NATS cluster the server uses (--nats.server on the server side).

The cleanest setup is to save the connection as a NATS context and export INSIGHTS_NATS_CONTEXT=<name> once — both interactive shells and AI agents then pick it up automatically.

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.

Example Prompts

  1. What's the message throughput per cluster right now?
  2. Show me the top 10 connections by bytes sent in the last hour.
  3. Which streams haven't received a message in the past 24 hours?
  4. List all critical audit findings grouped by entity type.
  5. What accounts are using the most JetStream storage?
  6. Find consumers with growing pending counts over the last 30 minutes.
  7. How has memory usage trended across servers in the last hour?
  8. Which servers have the most subscriptions per connection?
  9. Show me streams where the leader changed in the past day.
  10. What's the slowest-draining consumer per account?
Next
Troubleshooting