AI Agent Setup

Berserk pairs with AI coding agents to give you natural-language access to your logs, traces, and metrics — right from your editor. Ask your agent to investigate errors, explore schema, or correlate traces, and it will run the right KQL queries for you.

Two ways in:

• MCP over HTTP — point a MCP 2026-07-28 host (Claude Code 2.1.232+, MCP Inspector) at https://<your-cluster-endpoint>/mcp. Older protocol versions are not supported; agent hosts catch up quickly, so Berserk does not dual-speak them. The host signs in with OAuth (or a service-principal token). No bzrk binary.
• CLI + skill (this page) — install the Berserk CLI and skill so the agent shells out to bzrk search.

Prerequisites

Install the Berserk CLI if you haven't already:

curl -fsSL https://go.bzrk.dev | bash

Your agent runs queries through the bzrk CLI, so the CLI needs a profile pointing at your cluster and an authenticated session. This is a one-time setup.

1. Add a profile for your cluster

A profile saves your cluster endpoint locally so you don't have to pass --endpoint on every command. Point it at your cluster's base URL:

bzrk profile add --endpoint https://<your-cluster-endpoint> my-cluster

If your data lives in a non-default database, pin it to the profile with --database so queries resolve the right tables without a flag each time:

bzrk profile add --endpoint https://<your-cluster-endpoint> --database my-database my-cluster

2. Make it the active profile

bzrk profile use my-cluster

Now bzrk commands target this cluster without an explicit --endpoint. Confirm it's active:

bzrk profile list

3. Sign in

Authenticate the active profile against the gateway. This runs a browser-based device-code flow — bzrk login prints a verification URL and a one-time code, opens your browser on a TTY, and waits for you to approve:

bzrk login

On success the access and refresh tokens are saved into the active profile. The CLI short-circuits if you're already signed in; pass --force to re-authenticate unconditionally.

Verify everything works end to end:

bzrk auth status            # shows your signed-in identity
bzrk database list          # lists databases on the cluster
bzrk table list             # lists tables in the active database
bzrk search "default | count" --since "24h ago"

Install the Berserk skill

The berserk skill teaches an agent how to query Berserk well: profile routing, KQL rules (permissive fields, bracket-quoted OTel keys, filters that keep the segment indexes engaged), and how to stop streaming queries early. It uses the open Agent Skills format, so one command installs it into Codex, Cursor, OpenCode, Gemini CLI, Amp, Claude Code, and any other supported harness:

npx skills add berserkdb/berserk-skills          # pick agents interactively
npx skills add berserkdb/berserk-skills -a '*' -y # install to every detected agent

Skills are symlinked, so npx skills update picks up new revisions.

Once installed, just ask your agent to query your data:

• "Search for errors in the last hour"
• "Look at traces around 2024-01-07T08:38:00Z"
• "What services are logging?"
• "Investigate connection refused errors"

The agent will explore your schema, search for errors, correlate traces, and summarize findings.

Claude Code

Claude Code users can install the full plugin instead, which adds specialist subagents on top of the skill:

/plugin marketplace add berserkdb/berserk-skills
/plugin install berserk@berserk-skills
/reload-plugins

The plugin includes:

• berserk skill — the same skill as above: KQL syntax, bzrk flags, and the streaming early-stop contract.
• berserk:explore — autonomous data exploration: schema discovery, error investigation, mixed-signal queries.
• berserk:incident-triage and berserk:trace-analysis — root-cause investigation and cause-and-effect trace narratives.
• berserk:otel-log / berserk:otel-trace / berserk:otel-metric — signal-specific specialists for logs, traces, and metrics.
• berserk:cluster-admin — cluster operations: service health, tables, segments, ingest tokens, merge tasks.

git clone https://github.com/berserkdb/berserk-skills.git /tmp/berserk-skills
cp -r /tmp/berserk-skills/skills/berserk .claude/skills/
cp /tmp/berserk-skills/agents/explore.md .claude/agents/
cp /tmp/berserk-skills/agents/cluster-admin.md .claude/agents/

OpenCode

OpenCode is covered by the npx skills install above; it also discovers skills from .claude/skills/ automatically, so a plain copy works too:

git clone https://github.com/berserkdb/berserk-skills.git /tmp/berserk-skills
cp -r /tmp/berserk-skills/skills/berserk .claude/skills/   # project-level
cp -r /tmp/berserk-skills/skills/berserk ~/.claude/skills/ # or global

Other Agents

Any agent that supports the Agent Skills format or reads AGENTS.md can use the npx skills install above. The streaming contract below also ships in the CLI itself (bzrk search --help), so even an agent with no skill installed can discover it. See berserkdb/berserk-skills for updates.

How agents stop streaming queries early

bzrk search streams replacement snapshots over the same requested window as coverage grows — not a widening or newest-first range. Each increment looks finished; it is a lower bound you can test. In agent mode (auto-detected in Claude Code, Codex, and similar, or forced with --agent) every snapshot is also written as a TSV under ~/.cache/bzrk/history/<id>/, and each # Increment N / # Query Complete header line ends with the absolute path of its snapshot.

The skill tells the agent to write a stop predicate before starting the query (exists, n >= N, bytes ingested >= 10M) and, whenever the predicate is mechanical, hand it to the CLI so the query cancels itself the moment a completed snapshot decides the answer — on any agent runtime, in the foreground:

• --stop-when "n >= 50" for numeric thresholds (sort a column to the top to express "any row crosses X"),
• --stop-cmd 'grep -q OOMKilled "$1"' for anything a shell one-liner can test against the snapshot TSV (exit 0 stops, 1 continues).

The result is then a partial lower bound, which is exactly what a threshold question needs. Only when the stop decision requires judgment rather than a mechanical test does Claude Code fall back to Monitoring each increment header, Reading the TSV at the path the header ends with, and killing the query when satisfied (requires the Monitor tool). Waiting for # Query Complete is only for questions a partial cannot decide (absence, exact min/max over the whole window). Agents with none of these should pass --no-stream.

See the CLI reference for the full streaming contract and more --stop-when / --stop-cmd examples.