Kestrel
Mission control for AI agents.
See what every agent is doing, what it costs, and when it gets stuck. Live, local, any framework.
Quick start · Report your agents · Docs · Event format · Roadmap · Contributing
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.
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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.