Kestrel

---

Kestrel is a single-binary error tracker designed so an AI agent — Claude Code, Cursor, or your own — can read incoming errors, diagnose them, and mark them resolved with the commit SHA that fixed them. A web UI is included for humans, but it is the secondary interface.

It is deliberately small: a stripped binary under 20 MB, idle memory under 50 MB, SQLite as the only storage. No team permissions, no alert channels, no release management screens.

Why?

Sentry-style tools were built for ops teams clicking through dashboards. Their data models reflect that — events are decomposed into the columns a human cares about. LLMs read better when the full event envelope arrives intact: every stack frame with source context, recent log entries, the git commit, the runtime banner. Kestrel stores the raw envelope as JSON and serves it back through MCP. That is the whole differentiator.

Quickstart

1. Run Kestrel

docker run -d \
  --name kestrel \
  -p 8080:8080 \
  -v kestrel-data:/data \
  ghcr.io/wearzdk/kestrel:latest

The first start prints a temporary admin password to the container logs (or set one with -e KESTREL_ADMIN_PASSWORD=...). Open http://localhost:8080, log in, create a project, and copy its ingest token.

2. Send your first event

JavaScript / TypeScript

npm install kestrel-sdk

import { init } from "kestrel-sdk";

init({
  endpoint: "http://localhost:8080/api/v1/ingest",
  token: "YOUR_PROJECT_TOKEN",
});
// `window.error` and `unhandledrejection` are now captured automatically.

Python

pip install kestrel-sdk

import kestrel_sdk
kestrel_sdk.init(endpoint="http://localhost:8080/api/v1/ingest", token="YOUR_PROJECT_TOKEN")
# sys.excepthook is wired up.

Go

go get github.com/wearzdk/kestrel/sdks/go@latest

import kestrel "github.com/wearzdk/kestrel/sdks/go"

if err := kestrel.Init("http://localhost:8080", "YOUR_PROJECT_TOKEN"); err != nil {
    panic(err)
}
defer kestrel.Recover(ctx) // captures panics

Trigger an exception in your app — a fresh issue should appear in the web UI within a second.

3. Hand the keys to an AI

Add Kestrel as an MCP server in Claude Code (~/.claude/mcp.json). Use the HTTP transport when the agent and the server are on different machines (the common Docker case):

{
  "mcpServers": {
    "kestrel": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer YOUR_PROJECT_TOKEN" }
    }
  }
}

If the agent runs on the same host as a binary install, the stdio transport also works — see the MCP overview for both forms.

The agent now has list_errors, get_error, mark_resolved, mark_ignored, and get_trend available as tools.

What's in the box

• Server — cmd/kestrel. One binary serves REST ingest, MCP (StreamableHTTP at /mcp and stdio via kestrel mcp), and the embedded web UI. SQLite via modernc.org/sqlite (pure Go, no CGO).
• Web UI — Vite + React + Tailwind. Issue list, detail, project / token management. Bilingual (English / 中文) with locale-aware timestamps.
• JS SDK — sdks/js. Zero deps, ~1 KB gzip, passive capture only.
• Python SDK — sdks/python. stdlib-only, hooks sys.excepthook and the asyncio loop.
• Go SDK — sdks/go. Independent module, stdlib-only, Recover + slog.Handler integrations.

Self-hosting essentials

Need	Pointer
Configuration	kestrel.example.toml
Docker image	ghcr.io/wearzdk/kestrel:latest (multi-arch)
Static binary	GitHub Releases (linux/macos/windows, amd64/arm64)
Backups	kestrel backup <out.tar.gz>
Health & metrics	/healthz, /healthz/ready, /metrics (Prometheus)
Reverse proxy	Self-hosting guide (Caddy / Nginx / Traefik)
MCP integration	MCP overview

Roadmap & non-goals

See ROADMAP.md. Phases 0–5 are released in v0.1.0.

The non-goals list there is firm: no distributed tracing, no session replay, no APM, no Sentry-protocol compatibility, no team RBAC, no alert channels. Kestrel is scoped tightly on purpose.

Contributing

See CONTRIBUTING.md. For security issues, see SECURITY.md.

License

MIT © wearzdk