Skip to main content

Kestrel

Mission control for AI agents.
See what every agent is doing, what it costs, and when it gets stuck. Live, local, any framework.

CI License: MIT PyPI Python 3.11+ Zero dependencies No telemetry

Quick start · Report your agents · Docs · Event format · Roadmap · Contributing

Kestrel's demo: the overview of six projects, a live run filling its activity feed, an agent that may be stuck with its stop buttons, and a failed run

Agents now work for minutes or hours on their own: coding agents that open pull requests overnight, research agents, a lead delegating to a team of specialists. While they run you are blind. Is it compiling or dead? What did it actually do? What did it cost? What is waiting for you?

Kestrel is a small local dashboard that answers those questions for every agent on your machine, whatever it is built with. Agents report tiny JSON events; Kestrel shows every run live, the tree of agents inside it, a plain-language feed of their actions, tokens and cost, and the pull requests and questions waiting for you.

Why Kestrel

  • 🟢 Status you can trust. Kestrel never takes an agent's word that it's still working. Runs need heartbeats; silent agents decay to idle, then stale; a run that dies mid-task shows as lost, with the agents it cut off. No more green dots on dead processes.
  • 🔌 Works with any agent. A documented event format, a Python client, a CLI and an HTTP endpoint. A first-party adapter for Claude Code; bring your own for anything else.
  • 🔒 Local and private. Binds to 127.0.0.1, one SQLite file, secrets scrubbed before storage, a token on ingest, no telemetry, no third-party requests.
  • 📦 Zero dependencies. The Python package uses the standard library only. The dashboard ships pre-built inside it.
  • 🛑 In control, not just informed. Stop an agent, a run or a whole project from the dashboard, and set daily caps in tokens or dollars that actually halt agents.
  • 💵 Cost you can read. Estimated dollars next to tokens for every agent, run, project and day.
  • 🔔 Told when it matters. Alerts for stuck agents, failed or lost runs, budgets and agents waiting for you: on the dashboard, on your desktop, and to Slack or Discord.
  • 🧭 Built for the morning after. Which runs failed, which agent got stuck, which PRs need a review, which questions your agents left you, all on one screen.
A live run: status, tokens against the run's budget, agents, duration, and a feed of what each agent did in plain language

Quick start

Try it without installing anything but uv:

uvx kestrel-agents demo        # opens http://127.0.0.1:7777

Or install it (Python 3.11+, no other dependencies):

pipx install kestrel-agents    # or: pip install kestrel-agents
kestrel demo

kestrel demo runs six fictional projects through every state Kestrel knows (a live run, a stuck agent, unfinished work, a failed run, a lost run) in a throwaway folder deleted when you stop it.

Then point your own agents at it:

kestrel hook install   # every Claude Code session on this computer reports to Kestrel
kestrel watch          # the dashboard for your real runs
Docker
docker run --rm -p 127.0.0.1:7777:7777 ghcr.io/abdellahbsk/kestrel demo --no-browser
docker compose up      # the dashboard, with its data in the kestrel-data volume

The port is published on 127.0.0.1 only. Agents on the host report to it over HTTP.

From source

Node 20+ builds the dashboard once:

git clone https://github.com/abdellahBSK/kestrel && cd kestrel
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
(cd frontend && npm ci && npm run build)
kestrel demo

Report your agents

Claude Code and the Claude Agent SDK: kestrel hook install once, or one line in your SDK program: ClaudeAgentOptions(hooks=kestrel.adapters.claude_agent_sdk.hooks()). Each prompt becomes a run, subagents become child agents, tool calls and tokens appear live. Details.

Python: no server needed; events go straight into the local store.

from kestrel.client import Reporter

with Reporter("my-project").run("Fix the login bug") as run:  # heartbeats while open
    lead = run.agent("lead", role="lead", model="claude-opus-5-5")
    dev = run.agent("dev-1", role="developer", parent="lead", description="Implement the fix")
    dev.action("Bash", detail="npm test", summary="Ran the tests", result="42 passed")
    dev.tokens(input=1200, output=300, model="claude-sonnet-5-5")
    dev.finish()
    lead.finish()
# an exception inside the block marks the run failed, with the error

Any language: the CLI, or one HTTP request per event.

RUN=$(kestrel emit run.started --project my-project -d title="Fix the login bug")
kestrel emit agent.action --project my-project --run $RUN --agent dev-1 -d tool=Bash -d detail="npm test"
kestrel emit run.finished --project my-project --run $RUN

curl -X POST http://127.0.0.1:7777/v1/events \
  -H "Authorization: Bearer $(kestrel token)" -H "Content-Type: application/json" \
  -d '{"type":"agent.message","project":"my-project","run":"r1","agent":"lead","data":{"text":"hi"}}'

The event format is twelve event types, documented in one page, and writing an adapter for your framework usually takes one file.

How it works

flowchart LR
    A["Your agents<br/>Python · CLI · HTTP · Claude Code"] -->|v1 events| K["Kestrel<br/>validate · scrub · store"]
    K --> S[("SQLite")]
    S -->|"fold events + heartbeats + now"| K
    K -->|"runs, agents, health (UTC)"| D["Dashboard"]

Agents report facts, never status. Kestrel decides what is live from the evidence and the clock, every time you look. Details in the architecture and the decision records.

The Claude Code runner (optional)

Kestrel also ships a scheduled runner for teams of Claude Code agents: a lead delegating to developer, tester, QA, security and optimizer subagents, working on your repositories within a daily token budget, every task on its own branch and pull request.

kestrel setup          # create the team workspaces from [teams.*] in your config
kestrel run --dry-run  # what today's scheduled run would do
kestrel status         # tokens used today and this week, budget left

The runner guide covers setup, what happens during a run, the guard's rules and scheduling on Windows, macOS and Linux.

A guard hook blocks pushes to anything but task branches, writes outside the team folder, secret files and outbound HTTP; enforces the budget; makes QA wait for the tests; and stops a lead from ending a run while its agents still work. It is a strong guardrail, not a sandbox: review agent changes before merging, and use a container or VM for real isolation.

Configuration

Everything lives in one home folder: $KESTREL_HOME, or ~/.kestrel. A config file is optional. kestrel init writes a commented one where every value is the default, and kestrel doctor checks your setup and says how to fix what isn't right.

[budget]
agents_daily = 800_000        # token budget line on the dashboard (0 = none)

[monitor]
heartbeat_timeout = 45        # silent this long → the run is lost
stale_after = 600             # an agent idle this long may be stuck

[alerts]
webhook = "https://hooks.slack.com/services/…"   # optional; desktop notifications are on by default

[projects.my-project]
title = "My project: what it is"
daily_usd = 20                # stop its agents once they cost this much today

Roadmap

Kestrel is pre-1.0 and moving fast. Next up (full list):

  • Claude Code hooks adapter for any Claude Code session, and a Claude Agent SDK adapter
  • Adapters for more frameworks (ask for yours)
  • Alerts: stuck agent, failed run, budget threshold, PR waiting
  • Estimated cost in USD next to tokens
  • Stop buttons per agent and per project; budget caps that halt agents
  • pipx install kestrel-agents, uvx kestrel-agents demo, Docker image on GHCR
  • OpenTelemetry bridge, so any OTel-instrumented agent reports without an adapter
  • Team mode: one dashboard for several machines

Want an adapter for your framework? Ask for it, or build it: it is usually one file.

Contributing

Kestrel is built spec-first against a short constitution. Bug fixes go straight to a PR; features start as an issue and a spec. See CONTRIBUTING.md to set up a dev environment in two minutes.

License

MIT

Metadata

Release files for kestrel-agents 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kestrel-agents 0.1.0
File Size Uploaded Provenance Actions
kestrel_agents-0.1.0.tar.gz 610.6 kB With provenance Details for kestrel_agents-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kestrel-agents 0.1.0
File Interpreter ABI Platform Actions
kestrel_agents-0.1.0-py3-none-any.whl Python 3 none any Details for kestrel_agents-0.1.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / kestrel_agents-0.1.0.tar.gz

Download URL kestrel_agents-0.1.0.tar.gz
Size 610.6 kB
Tags Source
SHA-256 checksum
How to use checksums
8bfe75764bccdaa0c523882567d8f774a64a4fa031ed3a9dc744774f99e4e14a
BLAKE2b-256 checksum
How to use checksums
a62d02a1aa339bdf174bfdbe9b8f83452b2bbf372167137ef2db47c19f29d704
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / kestrel_agents-0.1.0-py3-none-any.whl

Download URL kestrel_agents-0.1.0-py3-none-any.whl
Size 596.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed1ac5048b51182adbf21be2781d320294e9d744dcc84bf2d4ae37352f50dce1
BLAKE2b-256 checksum
How to use checksums
4d2d7ccf7356ffd9cb4ab5b12ab5944839ae8f3b0c04ac8e3169f5f07d1d17ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for kestrel-agents 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kestrel_agents-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page