adanb13/cirdan

**Cirdan is an on-call software repair agent.** A production alert fires — Grafana,
Alertmanager, or Slack. Cirdan resolves the affected service and its repo from the
explicit services: registry in cirdan.yaml, reproduces the failure in an isolated
runner (Docker Compose or Kubernetes), has a coding agent fix the code — your own
logged-in Claude Code / Codex CLI, or an API provider — re-verifies the fix against
the pinned reproduction probe and the repo's test suite, and opens a verified pull
request. When policy allows, it merges, deploys, and verifies production recovery,
stopping at manual_required with full evidence when recovery fails.
The job it does: when an alert fires at 3am for a code-shaped failure, a verified fix
PR (or a completed deploy plus recovery confirmation) is waiting instead of a page.
Cirdan is deliberately **not** an infrastructure mapper, a topology explorer, an
observability dashboard, a generic agent launcher, or a ChatOps bot. It repairs the
services you register — nothing is discovered, and nothing is repaired implicitly.
Quickstart
cirdan setup walks one short path and shows a readiness banner that flips to
**"Ready to repair"** only when this install can actually fix something:
1. **Choose a pathway** — *Use the CLI* (the tools already logged in on this machine)
or *Use the API* (managed credentials + a GitHub App). See
Two ways to run.
2. **Connect an alert source** — a Grafana webhook (+ HMAC), native Alertmanager
intake, or Slack.
3. **Select repair repositories** — in *Source Code Connection*, Cirdan lists the
repos your gh login can push to; pick which ones it may repair. Only selected
repositories are ever repaired.
4. **Prove routing** — the *Alert routing* step synthesizes a sample alert (or takes a
real payload you paste) and must show it resolving to a selected repository **and**
routing to a code-repair pipeline.
5. **Start the daemon** and post a demo alert:
The runnable demo in examples/demo/ wires this end to end. The
same checklist is available headlessly — cirdan status --checks prints the identical
table and exits 1 until the install is ready. Useful setup flags:
- cirdan setup --terminal — the text step flow instead of the UI
- cirdan setup --all — run every step without prompting (scripts / CI)
- cirdan setup --system — machine-level scope in ~/.cirdan instead of a repo
Install
**From PyPI (recommended):**
**Without Python — npm / Homebrew / curl:**
These ship a self-contained binary — no Python 3.11+ required. Supported: macOS (arm64), Linux x64/arm64 (glibc), Windows x64. On Intel Macs, Alpine/musl, or other platforms, use the PyPI install above.
**Then set it up in one command** (see Quickstart):
Both open the same guided setup: choose a pathway, connect an alert source + GitHub,
select repair repositories, prove routing, and start the always-on daemon.
Targeted installs: cirdanops[mcp], cirdanops[api], cirdanops[slack],
cirdanops[agent], cirdanops[github-app], cirdanops[secrets], or combinations
like cirdanops[api,mcp]. The sandbox runners need no extras — they use the
docker/kubectl CLIs already on your PATH.
**Prerequisites by platform** (Python 3.11+ and uv or pipx):
**Docker (no Python needed):**
(or docker compose up with the provided docker-compose.yml)
**From source (latest unreleased):**
Two commands are installed:
| Command | What it is |
|---|---|
| cirdan | Human/agent CLI |
| cirdand | Long-running Always ON daemon |
Local development (from a clone)
Contributors work from a clone with an **editable** virtualenv, so changes to the
working tree take effect immediately — no reinstall between edits. make install
creates .venv and installs the package (distribution name cirdanops) editable with
the [all,dev] extras — every runtime feature plus the test toolchain:
Requires Python 3.11+. The manual two-line equivalent works on a standard Python;
make install additionally handles the pip-less-venv case (it falls back to
python3 -m venv --without-pip and bootstraps pip into the venv).