Cirdan

Cirdan

Cirdan はオンコール対応のソフトウェア修復エージェントです。 Grafana、 Alertmanager、または Slack で本番環境のアラートが発生すると、Cirdan は cirdan.yaml の明示的な services: レジストリから影響を受けたサービスとその リポジトリを特定し、分離されたランナー（Docker Compose または Kubernetes）で 障害を再現します。コーディングエージェント（ログイン済みの Claude Code / Codex CLI、 または API プロバイダー）にコードを修正させ、固定された再現プローブとリポジトリの テストスイートで修正を再検証し、検証済みのプルリクエストを作成します。ポリシーで 許可されている場合は、マージ、デプロイ、本番環境の復旧確認まで行います。復旧に失敗 した場合は、すべての証拠を添えて manual_required の状態で停止します。

alert ─▶ resolve service + repo (the services: registry) ─▶ reproduce in an isolated runner
      ─▶ coding agent fixes the code ─▶ verify (pinned repro probe + sandboxed test suite)
      ─▶ verified PR (@cirdan review loop; CI checks watched) ─▶ optional merge + deploy
      ─▶ verify recovery in production

Cirdan が行うのは、コードに起因する障害で午前3時にアラートが発生したとき、 ページャー通知の代わりに、検証済みの修正 PR（またはデプロイ完了と復旧確認）が 待っている状態にすることです。

Cirdan は意図的に、インフラストラクチャーマッパー、トポロジーエクスプローラー、 オブザーバビリティダッシュボード、汎用エージェントランチャー、ChatOps ボットでは ありません。 登録したサービスだけを修復します。自動で検出されるものはなく、 暗黙に修復されるものもありません。

クイックスタート

pipx install "cirdanops[all]"      # or uv / pip / npm / brew / curl / docker — see Install
cirdan setup                       # opens the local, loopback-only setup UI

cirdan setup は短い手順を案内し、このインストールで実際に修復できる状態になった 場合にのみ 「修復の準備完了」 に切り替わる準備状況バナーを表示します。

1. 実行方法を選択 — CLI を使う（このマシンにすでにログインしているツール） または API を使う（管理された認証情報と GitHub App）。2 つの実行方法を参照してください。
2. アラートソースを接続 — Grafana webhook（+ HMAC）、ネイティブの Alertmanager 受信、または Slack。
3. 修復対象のリポジトリを選択 — ソースコード接続で、Cirdan は gh のログイン アカウントがプッシュできるリポジトリを一覧表示します。修復を許可するものを選択して ください。選択したリポジトリのみが修復対象になります。
4. ルーティングを検証 — アラートルーティングの手順では、サンプルアラートを 生成するか、貼り付けた実際のペイロードを受け取り、それが選択したリポジトリに解決 され、さらにコード修復パイプラインにルーティングされることを確認します。
5. デーモンを起動し、デモアラートを送信します。

cirdand serve --http
curl -X POST localhost:8090/v1/ingest/grafana -d @examples/demo/alert.firing.json

examples/demo/ の実行可能なデモでは、これらすべての手順を エンドツーエンドで実行できます。同じチェックリストはヘッドレスでも利用できます。 cirdan status --checks は同一の表を出力し、インストールの準備が整うまでは終了 コード 1 で終了します。便利なセットアップフラグ：

• cirdan setup --terminal — UI の代わりにテキスト形式のステップフローを使用
• cirdan setup --all — プロンプトを表示せず、すべての手順を実行（スクリプト / CI）
• cirdan setup --system — リポジトリではなく ~/.cirdan をマシンレベルのスコープとして使用

インストール

PyPI から（推奨）：

uv tool install "cirdanops[all]"
# or
pipx install "cirdanops[all]"
pip install "cirdanops[all]"

Python を使わない場合 — npm / Homebrew / curl：

npx -y @cirdanops/cli serve-mcp        # run the MCP server, zero install
npm install -g @cirdanops/cli          # or put the `cirdan` command on your PATH
brew install adanb13/tap/cirdan        # macOS / Linux (Homebrew)
curl -LsSf https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.sh | sh
# Windows: irm https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.ps1 | iex

これらには自己完結型のバイナリが含まれているため、Python 3.11 以降は不要です。対応環境：macOS（arm64）、Linux x64/arm64（glibc）、Windows x64。Intel 搭載 Mac、Alpine/musl、その他のプラットフォームでは、上記の PyPI からのインストールを使用してください。

次に、1 つのコマンドでセットアップします（クイックスタートを参照）：

cirdan setup              # inside a repo
# or, machine-level scope in ~/.cirdan:
cirdan setup --system

どちらも同じガイド付きセットアップを開始します。経路を選び、アラートソースと GitHub を接続し、修復リポジトリを選択して、ルーティングを検証し、常時稼働デーモンを起動します。

用途を絞ったインストール：cirdanops[mcp]、cirdanops[api]、cirdanops[slack]、 cirdanops[agent]、cirdanops[github-app]、cirdanops[secrets]、または cirdanops[api,mcp]のような組み合わせ。サンドボックスランナーには追加パッケージは不要です。すでに PATH にある docker／kubectl CLI を使用します。

プラットフォーム別の前提条件（Python 3.11 以降とuvまたはpipx）：

# macOS
brew install [email protected] uv

# Windows
winget install astral-sh.uv

# Ubuntu / Debian
sudo apt install python3.12 python3-pip pipx
# or get uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

Docker（Python 不要）：

# run the always-on repair daemon: alert receiver + isolated repair runner,
# using the host's Docker for sandboxes
docker run -d \
  -v "$PWD":/workspace:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 127.0.0.1:8090:8090 \
  ghcr.io/adanb13/cirdan

（または、用意されているdocker-compose.ymlを使ってdocker compose upを実行します）

ソースから（未リリースの最新版）：

pip install "cirdanops[all] @ git+https://github.com/adanb13/cirdan.git"

次の 2 つのコマンドがインストールされます。

コマンド	内容
cirdan	人間／エージェント向け CLI
cirdand	長時間稼働する常時稼働デーモン

ローカル開発（クローンから）

コントリビューターはクローンから編集可能な仮想環境を使って作業します。そのため、作業ツリーへの変更はすぐに反映され、編集のたびに再インストールする必要はありません。make installは.venvを作成し、パッケージ（配布名cirdanops）を[all,dev]追加パッケージとともに編集可能モードでインストールします。これにより、すべての実行時機能とテストツール一式が利用できます。

git clone https://github.com/adanb13/cirdan.git
cd cirdan
make install     # ≈ python3 -m venv .venv && .venv/bin/pip install -e ".[all,dev]"
make test        # .venv/bin/python -m pytest tests/ -q

Python 3.11 以降が必要です。手動で実行する 2 行の同等手順は標準的な Python で動作します。make installではさらに、pip がない仮想環境にも対応します（python3 -m venv --without-pipにフォールバックし、仮想環境に pip をブートストラップします）。

編集可能インストールでは、両方のコンソールスクリプトが.venv/binに配置され、再ビルドせずに作業ツリーのコードを実行できます。

.venv/bin/cirdan setup                                    # or: .venv/bin/python -m cirdan.cli.main setup
.venv/bin/cirdand serve --http
.venv/bin/python -m pytest tests/test_slack_events.py -q  # a single test module

よく使う Make ターゲット（一覧はmake helpで確認できます）：

ターゲット	処理内容
make install	.venvを作成し、[all,dev]とともに編集可能モードでインストールします
make test	pytest の全テストスイートを実行します
make build	sdist と wheel をdist/にビルドします
make setup-wipe DIR=<dir> [KEY=1]	プロジェクトのオンボーディングをリセットし、cirdan setupを手順 0 から再開します（KEY=1を指定すると、グローバルマスターキーも削除します）
make demo-up … make demo-clean	examples/demo/の実行可能なスタックをビルドして操作します

OS のキーリングがないヘッドレスマシンでcirdan setup中に認証情報を保存するには、先に環境変数でマスターキーを設定する必要があります： export CIRDAN_MASTER_KEY=$(.venv/bin/python -c 'import os,base64;print(base64.b64encode(os.urandom(32)).decode())')。

実行方法は 2 通り：CLI を使用する／API を使用する

最初のセットアップ画面でデプロイ方式（cirdan.yaml の deployment_mode:）を選択します。この選択によって、その後のすべての設定が決まります。

CLI を使用する（cli、デフォルト） — Cirdan は、このマシンですでにログイン済みのツールを使って実行されます。GitHub への書き込みには gh auth login を使用します。コーディングエージェントには、検出されたログイン済みの Claude Code または Codex CLI が使われ、隔離された修復ワークスペース内でヘッドレスに起動します。サンドボックスランナーには、ローカルの Docker（または kubectl）を使用します。通常の手順では、保存するキーも GitHub App も不要です。環境変数の API キーと GitHub App は、明示的に「詳細」と表示された切り替え項目から引き続き利用できます。

API を使用する（api） — 共有環境／エンタープライズ環境向けの、ヘッドレスで管理された方式です。プロバイダーの API キーは暗号化して保存され（cirdan secret、AES-256-GCM）、GitHub への書き込みには GitHub App（ガイド付きマニフェストオンボーディング）と、有効期間の短いリポジトリごとのインストールトークンを使用します。エンタープライズセキュリティプロファイルは自動的に適用され、継承した gh 認証とホスト上で起動する CLI エージェントは、設定の読み込み時に拒否されます。

どちらの方法も、同じ準備完了条件を満たす必要があります。セットアップ UI のバナーと cirdan status --checks には同じ表が表示されます。内容は、修復対象のリポジトリが選択済みであること（各リポジトリを解決可能であること）・アラートソースが接続済みであること・ルーティングの証明があること（サンプルまたはライブアラートが、選択済みのリポジトリに解決され、コードパイプラインにルーティングされたことを確認できること）・remediation.mode が {develop, deliver} のいずれかであること・ライブプローブで確認済みのコーディングエージェントがあること・選択済みの各リポジトリへのアクセスを含む、検証済みの GitHub 書き込み経路があること・git が PATH 上にあること・サンドボックスランナーが正常に動作すること・デーモンが実行中であることです。赤色で表示される各行には、修正に必要な正確なコマンド、または解決につながるセットアップ手順が示されます。

従来の設定ファイルは引き続き読み込めます。deployment_mode: single-user は cli として、business は api として読み込まれます。また、ファイルの内容は次回のセットアップ保存時に移行されます。

設定

cirdan setup を実行すると、cirdan.yaml が作成されます。すべて手動で編集することもできます。詳しくは cirdan.yaml.example をご覧ください。このファイルの中核となるのは services: レジストリです。Cirdan が修復できるサービスの明示的な一覧、アラートをサービスに対応付ける方法、そしてコードの場所を定義します。

services:
  - name: checkout-api                 # canonical id (lowercase, node-id-safe)
    repo: acme/checkout                # "org/name" — the PR / repair target
    aliases: [checkout, checkout-svc]  # extra alert-label names for this service
    match_labels: {team: payments}     # optional exact label matchers (first match wins)
    deploy:                            # how it runs in prod + how the runner rebuilds it
      kind: compose                    # compose | k8s | helm
      compose_service: checkout-api    # defaults to the entry name
      compose_files: [docker-compose.yml]
    deploy_workflow: deploy.yml        # per-service GitHub Actions deploy (optional)
    telemetry_service: checkout        # Loki/PromQL service label; defaults to name

  - name: payments-api
    repo: acme/payments
    source_root: ~/src/payments        # local checkout (cli pathway only)
    deploy:
      kind: k8s
      namespace: prod
      workload: payments-api           # kubernetes_kind defaults to Deployment

アラートは、明示的な cirdan_node ラベル、次に match_labels、その後、一般的なラベル（service、service_name、app、job、 deployment、statefulset、pod、container、instance のホスト、annotations.service、alertname）を順に使って、名前とエイリアスに照合され、サービスに対応付けられます。暗黙のデフォルトはありません。どのサービスにも一致しないアラートはトリアージインシデントを作成し、「登録されている唯一のリポジトリ」を自動修復することはありません。

ルーティングポリシー。 すべてのアラートソースは、最初に一致したルールを適用する単一のポリシーを通過します。

routing_policy:
  rules:
    - when: {service: checkout-api, severity: [high, critical]}
      pipeline: full_remediation       # may merge/deploy — only under mode: deliver + the auto_* gates
    - when: {source: slack}
      pipeline: triage_only

一致するルールがない場合、登録済みサービスに対応付けられ、リポジトリを解決できるアラートは、該当する重大度（responder.severities。デフォルトは high／critical）で reproduce_and_pr_only に設定されます。それ以外は安全側に倒して triage_only になります。パイプラインは、対応範囲の広い順に、full_remediation · reproduce_and_pr_only · lightweight_pr_only · triage_only です。

安全ゲート（source_hosts.github と remediation の下に設定）：

ゲート	デフォルト	機能
require_verified_pr	true	失敗を再現でき（ベースラインプローブが失敗）、かつ修正を検証できた（修正後のプローブが成功した）場合にのみ PR を作成します
require_tests	false	PR を作成する前に、サンドボックス化されたリポジトリテストが成功することも必須にします
auto_merge	false	Cirdan の PR で GitHub のネイティブ自動マージを有効にします。ブランチ保護とレビュー担当者による承認は、引き続き実際のマージの条件となります。Cirdan が強制マージすることはありません
auto_deploy	false	デリバリーのマスタースイッチです。マージされた修正をデプロイし、本番環境で再検証します
require_checks	true	マージコミットの CI チェックがすべて成功するまで、デプロイの実行をブロックします（ブロックのみ。デプロイを停止することはできますが、開始することはありません）
remediation.mode	develop	すべてのパイプラインで実行可能な処理の上限です。deliver にすると、マージとデプロイが有効になります

デプロイまたは本番環境での検証に失敗すると、デリバリーは manual_required で停止し、失敗の証拠が通知され、監査ログに記録されます。Cirdan は手動介入が必要な状態で停止します（自動ロールバックは意図的に後回しにしています）。

コマンド

cirdan setup                  # guided setup: loopback UI (default) or --terminal
cirdan install --project      # scripted variant: hook agents, register MCP, arm responder, start daemon
cirdan incidents              # detection pass + list incidents
cirdan explain <incident-id>  # evidence-backed explanation
cirdan respond <incident-id>  # write the incident brief + invoke the responder once under a mode
cirdan remediate <incident-id>  # durable fix: isolated workspace → reproduce → fix → verify → PR
cirdan deliver <incident-id>  # manually drive an in-flight delivery (merge → deploy → prod-verify)
cirdan watch                  # foreground event + incident stream
cirdan status [--checks]      # daemon status; --checks runs the full readiness checklist
cirdan stop                   # stop the daemon for this scope
cirdan secret set|get|list|delete   # encrypted credential store (provider keys, App key)
cirdan slack-app              # emit the importable Slack app manifest for the configured intake
cirdan preview-intake         # dry-parse a sample payload; --source/--service runs the routing proof
cirdan serve-mcp              # MCP server (stdio; --transport streamable-http)

常時稼働

cirdand serve                        # ingest alerts, detect incidents, repair, deliver — forever
cirdand serve --http                 # + the HTTP API (alert ingestion endpoints)
cirdand serve --http --mcp           # + MCP mounted at /mcp

デーモンは、アクセスの更新、アラートの取り込みとインシデントの検出、デリバリー、PR チェックの監視、@cirdan コメントの処理、Slack の受信トレイ（設定に応じて、Socket Mode クライアントと Webhook 起動処理も含む）を、監視下のループで実行します。ループがクラッシュした場合はログを記録して再起動し、デーモン全体が停止することはありません。

スコープごとに実行できるインスタンスは 1 つです。同じスコープに対して 2 つ目の cirdand serve（または cirdan watch）を起動すると、実行中の PID が通知され、起動は拒否されます。cirdan status／cirdan stop（cirdand からも利用可能）で状態を確認し、停止できます。

エージェント連携

Cirdan は、コーディングエージェント向けのツールサーフェスでもあります。CLI の背後にある同じエンジンが、ちょうど 6 つの読み取り／証拠取得ツールとして MCP 経由で公開されます。list_incidents、explain_incident、get_recent_errors、get_logs、get_state、get_audit です。 get_logs と get_state は、services: に登録されたサービス名（またはエイリアス）を受け取り、ライブコンテナ／ポッドを自動で特定します。返される内容はすべて秘匿化されます。

cirdan install --project             # full guided setup (recommended)
cirdan setup                         # re-run the guided setup anytime
cirdan install --platform claude     # .claude/skills/cirdan/SKILL.md + CLAUDE.md + .mcp.json
cirdan install --platform codex      # AGENTS.md + .codex/cirdan.md
cirdan install --platform cursor     # .cursor/rules/cirdan.mdc + .cursor/mcp.json
cirdan install --platform gemini     # GEMINI.md
cirdan install --platform vscode     # .github/copilot-instructions.md + .vscode/mcp.json
cirdan install --platform windsurf   # .windsurf/rules/cirdan.md  (MCP: global config)
cirdan install --platform roo        # .roo/rules/cirdan.md + .roo/mcp.json
cirdan install --platform cline      # .clinerules/cirdan.md  (MCP: editor UI)
cirdan install --platform opencode   # AGENTS.md + opencode.json
cirdan install --platform goose      # .goosehints  (MCP: global config)
cirdan install --platform generic    # .agents/skills/cirdan/SKILL.md + AGENTS.md

cirdan install --project はガイド付きセットアップです。Cirdan を単にドキュメントに記載するだけでなく、修復ループを実行する状態にします。

1. マシン上のエージェントを検出し（claude/codex/cursor/gemini/vscode/windsurf/opencode/goose の設定または CLI）、検出したものだけに指示ファイルを書き込みます（汎用の AGENTS.md も含みます）
2. MCP サーバーを .mcp.json に登録します
3. インシデントレスポンダーを有効にし、デーモンのアラートをエージェントにルーティングします
4. 常時稼働するデーモンを起動します（デタッチ実行。cirdand status / cirdand stop）

手順 3～4 は確認を求めます（デフォルトは yes）。または、スクリプト用のフラグで実行できます。 --responder/--no-responder、--daemon/--no-daemon、--all-platforms。後で cirdan setup を実行すると、各手順の現在の状態が表示され、不足しているものだけが提案されます。インストールは冪等で、Cirdan 独自のマーカーブロック外の内容には決して触れません。

対応エージェント。 ファーストクラスの自動登録（ネイティブの指示ファイルと、エージェントが書き込み可能な設定をサポートしている場合は MCP）に対応するのは、Claude Code、Codex、Cursor、Gemini、VS Code（＋ GitHub Copilot）、Windsurf、Roo Code、Cline、opencode、Goose です。その他のエージェントも、汎用の AGENTS.md と .agents/skills/cirdan/SKILL.md を通じて使用できます。自動検出では claude/codex/cursor/gemini/vscode/windsurf/opencode/goose が検出されます。--platform roo または --platform cline を明示的に指定してください（これらは検出用 CLI のない VS Code 拡張機能です。また、Cline は MCP の設定をエディターのストレージに保存するため、Cline の UI から追加してください）。

記載されていない MCP クライアントでは、Python を使わずに Cirdan を手動で登録できます。

// npx form — zero install
{ "command": "npx", "args": ["-y", "@cirdanops/cli", "serve-mcp"] }
// or, if `cirdan` is already on PATH (pip / npm -g / brew / curl install):
{ "command": "cirdan", "args": ["serve-mcp"] }

HTTP API

[api] エクストラを使用すると、cirdand serve --http により、/health、/incidents、/incidents/{id}、/incidents/{id}/explain、/audit、アラート受信エンドポイント /v1/ingest/{grafana|alertmanager|…}（および /v1/ingest/slack/events、署名検証済みの /v1/ingest/github ウェブフック起動エンドポイント）、/v1/slack/interactions、最小限の OTLP/HTTP JSON レシーバー /v1/logs、さらに /setup 配下のセットアップ UI と API が公開されます。--mcp を追加すると、MCP サーバーが /mcp にマウントされます。状態を変更するルートにはガードが設定されています。SECURITY.md を参照してください。

アップグレード

自動では何も行われません。PyPI はプル専用のため、インストール済みのバージョンはアップグレードするまでそのまま動作します。新規インストールでは常に最新リリースが取得されます。インストール方法に応じて、次のいずれか 1 つのコマンドでアップグレードできます。

インストール方法	アップグレードコマンド
uv tool install	uv tool upgrade cirdanops
pipx install	pipx upgrade cirdanops
pip install	pip install -U cirdanops
npm（-g）	npm install -g @cirdanops/cli@latest（または npx @cirdanops/cli@latest … を実行）
Homebrew	brew upgrade cirdan
curl インストーラー	インストールスクリプトを再実行します（最新版が取得されます）
Docker	docker pull ghcr.io/adanb13/cirdan:latest（その後、コンテナを再起動します）

運用上の注意が 2 点あります。これまでのところ、既存の cirdan-out/ アーティファクトと SQLite ストアはリリース間で互換性があります（1.0 より前にスキーマバージョンキーとマイグレーションが導入される予定です）。また、新しいリリースがある場合、CLI は stderr に薄い色の 1 行を表示します（確認は 1 日に最大 1 回で、対話型ターミナルのみ）。CIRDAN_NO_UPDATE_CHECK=1 で表示を無効にできます。

マッピングリリース（≤ 0.9）からのアップグレード

Cirdan は、修復ワークフローという単一の製品に注力しています。インフラストラクチャのマッピング機能（グラフ／探索コマンド、ランタイムプロファイル、およびそれらの成果物）は削除されました。削除されたコマンドと、その代わりとなるものは次のとおりです。

削除されたコマンド	代わりとなるもの
map、graph、enrich、fingerprint	cirdan.yaml の明示的な services: レジストリ — Cirdan に修復を許可する対象を宣言します。自動検出は行われません
query、show	cirdan incidents、cirdan explain <id>、および MCP の証拠ツール（get_logs、get_state、get_recent_errors）
access	cirdan status --checks — 準備状況チェックリスト

古い設定も引き続き読み込まれます。adapters:、enrich:、profile: キーは受け入れられますが、無視されます（profile は一度だけ警告します。Cirdan は常に修復ワークフローを実行します）。また、deployment_mode: single-user／business は cli／api に正規化されます。パッケージから [map] と [terraform] の追加機能は削除されました。古い成果物（infra.graph.json、INFRA_REPORT.md、infra.html、fingerprint.json、…）は単に書き込まれなくなります。Cirdan がファイルを削除することはありません。

セキュリティ

Cirdan は実行環境のプロセスのアクセス権限をそのまま使用し、権限を昇格することはありません。書き込む内容はすべて秘匿化され、監査されます。2 つの運用形態では、信頼境界が異なります。「CLI を使う」では、ユーザー自身のログイン済みツールを、ユーザー自身の権限で実行します。一方、「API を使う」では、エンタープライズプロファイル（GitHub App と保存済みキー、ホスト上の CLI は使用しない）が適用されます。ネットワーク動作や、PR の対象が設定済みのリポジトリに限られる理由を含む詳細は、SECURITY.md をご覧ください。

ライセンス

Apache-2.0