Kairo Runtime (@kal-elsam/kairo-runtime) is a local agent operating
system — not an installer that dumps templates. It detects the AI coding
agents you already use, writes managed and reversible sections into their
configs, and keeps that ecosystem healthy with status checks, sync, doctor
diagnostics, and rollback.
Why I built it
Every project I run with AI coding agents (Cursor, Codex, Claude, Gemini,
Copilot) needs the same governance: consistent AGENTS.md rules, spec-driven
development (SDD) before significant changes, test-driven development (TDD)
for behavior changes, and a way to verify nothing drifted between agents or
machines. Rebuilding that setup by hand for every repo doesn't scale, and
copy-pasted config drifts the moment one project changes.
Kairo Runtime abstracts that governance into a reusable, installable runtime
— one CLI (kairo) that detects your agents, applies the same discipline
everywhere, and reports on its own health.
Core Principles
- Agent-agnostic — works across Cursor, Codex, Claude, Gemini, and Copilot instead of locking into one vendor.
- Non-destructive — writes managed, clearly-bounded sections into existing configs; every change is reversible (
--dry-run, rollback). - SDD + TDD by default — spec-driven development and test-driven workflows are built into the governance model, not bolted on.
- Terminal-first — a full Ink/React control center (Overview, Governance, Activity, Orchestration, Usage, Settings) instead of a one-shot script.
- Honest usage data — the Usage panel only reports measured token/budget data; it never invents totals or savings.
- Continuous health —
status,sync,doctor, and opt-inmonitorkeep the setup from silently drifting.
Architecture
kairo CLI
Terminal entry point — setup, status, sync, doctor, monitor.
Agent detection
Scans the machine for the AI coding agents already in use.
Cursor · Codex · Claude · Gemini · Copilot
Managed config sections
Writes bounded, reversible sections into each agent config.
AGENTS.md · .cursor/rules · .codex/skills · CLAUDE.md
~/.harness control plane
Local state, governance store, and alert history shared across projects.
Continuous governance loop
status → sync → doctor → monitor keeps every project aligned.
Built with this discipline
This portfolio and Kairo Systems (ARI and MAYA) are both built using the same SDD/TDD workflow that Kairo Runtime governs — every significant change follows Requirement → Spec → Plan → Tests → Implementation → Validation → Review → Human approval before it ships. The runtime doesn't power ARI or MAYA at execution time; it powers how I build them.
Stack
Node.js (ESM, >=20.12) · TypeScript · Ink + React (terminal UI) · @clack/prompts · published via GitHub Actions with npm provenance/attestations.
Try it
npx @kal-elsam/kairo-runtime
# preview only, writes nothing
npx @kal-elsam/kairo-runtime --dry-run