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.

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"

Claude Code

Install the Berserk plugin from the marketplace:

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

The plugin includes:

• berserk:explore agent — an autonomous subagent that investigates your observability data. It runs queries, analyzes results, and returns a summary. Triggered automatically when you ask about errors, logs, traces, or metrics.
• berserk:cluster-admin agent — manages and troubleshoots Berserk clusters. Checks service health, manages tables, segments, ingest tokens, merge tasks, and debugs cluster issues.
• berserk skill — a quick reference for KQL syntax, bzrk CLI flags, and time formats, loaded into the main conversation when needed.

Once installed, just ask Claude 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"

Claude will automatically explore your schema, search for errors, correlate traces, and summarize findings.

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 discovers skills from .claude/skills/ automatically, so the same skill works out of the box.

Copy the Berserk skill into your project:

git clone https://github.com/berserkdb/berserk-skills.git /tmp/berserk-skills
cp -r /tmp/berserk-skills/skills/berserk .claude/skills/

Or install globally so it's available in all projects:

git clone https://github.com/berserkdb/berserk-skills.git /tmp/berserk-skills
cp -r /tmp/berserk-skills/skills/berserk ~/.claude/skills/

Once installed, OpenCode will list it as an available skill and load it when you ask about logs, traces, or metrics.

Other Agents

Support for Cursor, GitHub Copilot, and other coding agents is planned. See berserkdb/berserk-skills for updates.