kageops-core.mp4
Sensei orchestrates eight specialist agents (the Autonauts) through a full six-phase product lifecycle: discover → design → build → verify → deploy. Runs on your laptop. Zero Docker. Your keys, your code, your machine — with a hard USD kill-switch you control.
Quickstart · Watch it work → · How it works · The Autonauts · Why it's different · Open core · Contributing
▶ Nine narrated how-to videos — real screen captures of the actual app, from first launch to a full run. Watch the series →
You describe what you want. Sensei — the orchestrator — decomposes it into tasks and routes each to the specialist best suited for it. Eight agents plan, write code, run the tests, fix what fails, and hand you a built, verified project — with a live activity feed the whole way and a hard budget cap you set.
Not another chat wrapper. KageOps is a real orchestration engine: task decomposition, phase gates, a build gate that actually runs
npm install/build/test, an acceptance gate that checks the output against your brief, tiered retry-with-repair, and non-negotiable cost guardrails.
git clone https://github.com/hmanoor/kageops-core.git && cd kageops-core
npm install && npm run build
# The "wow" — preview a full run. Decomposition + routing. Zero AI spend.
npx tsx src/cli/headless-runner.ts --dry-run \
--name "TaskFlow" \
--description "A kanban board with drag-and-drop columns and localStorage. Include #board, #add-task, #columns."👉 What the dry-run prints (click to expand)
═══ DRY-RUN PLAN (no AI calls, no spend) ═══
Project: TaskFlow
Simple-app: NO
Phase plan:
discovery full: ~4 task(s)
poc full: ~4 task(s)
business-viability full: ~4 task(s)
design-planning full: ~4 task(s)
development full: ~8 task(s)
launch-growth full: ~4 task(s)
Total tasks: ~28
Estimated cost by preset:
openrouter_budget (DeepSeek/Gemini) ~$0.13
ollama (local) ~$0.00
═══════════════════════════════════════════
It shows the exact plan Sensei would execute — every phase, every task, and which Autonaut each is routed to — without making a single paid API call.
Ready for real? Point it at a provider and lift the cap:
export OPENROUTER_API_KEY=sk-... # or ANTHROPIC_API_KEY, or Ollama (fully local), …
KAGEOPS_PRESET=openrouter_budget KAGEOPS_MAX_RUN_USD=0.50 \
npm run run:headless -- --name "TaskFlow" --description "..."Prefer a GUI? npm run dev launches the Command Center — Mission Control for
watching agents work, intercepting tasks, and reviewing output live.
Sensei never does task work itself — it orchestrates. It decomposes the brief, routes each task to the right specialist, runs the phase gates, and drives the retry-and-repair loop when something fails.
flowchart LR
B([Your brief]) --> S{{Sensei<br/>orchestrator}}
S -->|decompose + route| A[8 Autonauts]
A --> G1{Build<br/>Gate}
G1 -->|fails| FIX[Forge<br/>repairs] --> G1
G1 -->|passes| G2{Acceptance<br/>Gate}
G2 -->|violations| FIX
G2 -->|passes| OUT([Built + verified project])
S -.hard USD kill-switch.-> A
Every project flows through a six-phase lifecycle, each phase gated by your trust level:
flowchart LR
D[1· Discovery] --> P[2· POC] --> V[3· Business<br/>Viability] --> DP[4· Design<br/>& Planning] --> DEV[5· Development] --> L[6· Launch<br/>& Growth]
After development, two automated gates run before anything is called "done":
| Gate | What it does |
|---|---|
| BuildVerificationGate | Runs the real npm install → build → test. No green build, no pass. |
| AcceptanceGate | Checks the output against your brief (required elements, preview-URL reachability), with two-tier MUST/SHOULD severity. On failure it spins a repair task for Forge and retries. |
Real apps the agents built end-to-end — from a brief to a deployed site:
| Project | What it is | Live |
|---|---|---|
| DevPulse | A full SaaS — Clerk auth + Stripe billing + Neon Postgres, deployed to Vercel | devpulse.kageops.dev |
| Prism | A CSS design toolkit / playground | prism.kageops.dev |
Nine specialists. Each an expert in one slice of the lifecycle — because eight sharp tools beat one fuzzy one.
| Agent | Role | Owns |
|---|---|---|
| 🧭 Sensei | Orchestrator | Decomposition, routing, phase gates, retries — never writes task code itself |
| 🔍 Scout | Strategist | Research, discovery, concept briefs, cost estimates |
| 📐 Blueprint | Architect | System + data design |
| 🎨 Pixel | Designer | UI / UX |
| 🔨 Forge | Engineer | Implementation + repair |
| 🔐 Cipher | Data specialist | Schemas, migrations, data flows |
| 🛡️ Aegis | Platform engineer | Build, deploy, preview |
| 👁️ Vigil | Quality guardian | Tests + review |
| 📣 Herald | Marketer | Copy + launch assets |
- 🛑 Agents that spend money answer to a kill-switch. Every real run requires
an explicit
KAGEOPS_MAX_RUN_USDcap. A budget poller checks spend every 3s and cancels the run before it blows past. Per-task call caps and a zombie-guard back it up. Always--dry-runfirst. - 🧪 It verifies its own work. The build gate runs your actual toolchain; the acceptance gate checks the output against the brief. Failures trigger a bounded retry-with-repair loop, not a shrug.
- 🏠 Local-first, zero-Docker. An embedded Postgres (PGlite, WASM) boots in-process on first run. No database to install, no containers, no cloud dependency. Your code never leaves your machine.
- 🔌 Bring your own provider. Claude (API + CLI), OpenRouter, Ollama (fully local, $0), OpenAI, Gemini — swap with a preset. Your provider bill stays on your own account.
- 🎛️ Watch and steer. The Command Center desktop app streams a live activity feed; intercept, approve, or redirect tasks as they run.
| Provider | Mode | Cost |
|---|---|---|
| Claude | API or local CLI | Metered / subscription |
| OpenRouter | API (DeepSeek, Gemini, GPT, …) | Cheapest metered |
| Ollama | Fully local | $0 |
| OpenAI | API | Metered |
| Gemini | API | Metered |
- 6,300+ tests passing across 290+ files,
tsc --strictclean throughout. - Deterministic guardrails: budget-kill, per-task caps, zombie-guard, path-traversal prevention on all agent file I/O, parameterized SQL only.
- CI runs build · test · lint · secret-scan (gitleaks + a home-grown scanner) on every PR.
flowchart TB
subgraph UI[Command Center · Electron]
CC[Mission Control renderer]
end
subgraph ENGINE[Engine · TypeScript]
SEN[Sensei orchestrator]
BUS[(Event bus<br/>LISTEN/NOTIFY)]
AG[Autonaut agents]
AD[Multi-provider<br/>AI adapter]
GATES[Build + Acceptance gates]
end
subgraph DATA[Local-first data]
PG[(Embedded PGlite<br/>+ pgvector)]
end
CC <--> SEN
SEN <--> BUS
BUS <--> AG
AG --> AD
SEN --> GATES
SEN <--> PG
AG --> PG
| Layer | Tech |
|---|---|
| Desktop app | Electron 34 + TypeScript |
| Engine | Sensei orchestrator + 8 agents, event bus (Postgres LISTEN/NOTIFY) |
| Database | Embedded PGlite (default) · external Postgres 16 + pgvector (opt-in) |
| AI | Multi-provider adapter (Claude / OpenRouter / Ollama / OpenAI / Gemini) |
| CLI | Headless runner (--dry-run, budget caps, resume) |
| Tests | Vitest · tsc --strict |
See docs/architecture/ for the full picture.
KageOps is open-core. This repository is the engine and everything you need to run it locally — under AGPL-3.0, free forever:
- ✅ Sensei orchestrator, the 8 Autonauts, the agent framework
- ✅ Task decomposition, routing, phase gates, build + acceptance gates
- ✅ Embedded PGlite database, event bus, headless CLI runner
- ✅ The Command Center desktop UI
- ✅ Multi-provider AI adapter + cost guardrails + APO (prompt optimization)
The commercial KageOps Cloud layer — managed cloud compute, team
collaboration, hosted identity, billing, and outbound connectors — lives in a
separate private repository. The boundary is documented in
OPEN-CORE.md, and there are zero open → commercial imports;
the engine runs fully standalone. What you pay for is the hosted business, never
the engine.
Requires Node 20+. No Docker, no database setup.
git clone https://github.com/hmanoor/kageops-core.git
cd kageops-core
npm install
npm run build
# 1. Preview (no spend)
npx tsx src/cli/headless-runner.ts --dry-run --name "MyApp" --description "..."
# 2. Real run (budget-capped)
export OPENROUTER_API_KEY=sk-...
KAGEOPS_PRESET=openrouter_budget KAGEOPS_MAX_RUN_USD=0.50 \
npm run run:headless -- --name "MyApp" --description "..."
# 3. Or the desktop Command Center
npm run devCost safety is built in. Real runs require an explicit
KAGEOPS_MAX_RUN_USDcap; the budget-kill poller cancels the run if spend approaches it.
Short narrated screen-captures of the real app — no mockups. They're produced by an automated pipeline that drives the actual UI and records it, so every guide is re-cut when the interface changes and can't go stale. Index: docs/how-to.
Episode 01 — First launch & the setup wizard (1:55). Model presets and their cost trade-offs, trust levels, keychain-stored API keys, and the per-run budget kill-switch — ending at your first New Project screen.
2026-07-25-ep01-first-launch-16x9.mp4
Episode 02 — Your first project: writing the brief (1:44). The New Project screen end to end: brief-writing, project types + deployment config, the Phases & Tasks tree, budget and trust, and Dry Run vs Create & Start.
2026-07-25-ep02-first-project-16x9.mp4
Episode 03 — The live run, end to end (2:11). A real supervised run filmed start to finish: six phases, six on-camera approvals, agents working in timelapse, and completion.
2026-07-26-ep03-live-run-16x9.mp4
Episode 04 — What did it build? (1:20). Reviewing the output honestly: Completed tab, artifact browser, the generated code, the build report, and the produced page rendered live.
2026-07-27-ep04-what-it-built-16x9.mp4
Episode 05 — The Command Center tour (1:36). Operating modes, project board, orchestration flow graph, the bottom panel (activity, approvals, logs, build), agent roster, model routing, cost intel, and the Sensei chat dock.
2026-07-27-ep05-command-center-16x9.mp4
Episode 06 — Agents & model routing (1:36). The nine-agent roster and scorecard, per-agent model config, the preset grid with a switch on camera, fallback chains, and custom presets.
2026-07-27-ep06-agents-model-routing-16x9.mp4
Episode 07 — Trust, gates & intervention (1:24). A live run where a gate is approved, the next is denied — and returns after rework — plus pause/resume mid-run and the cascade to completion.
2026-07-27-ep07-trust-gates-intervention-16x9.mp4
Episode 08 — Cost controls (1:57). The budget cap as a hard kill, dry-run-first, the Cost Intelligence ledger, editing a run's cap mid-flight, and the guardrail layers underneath.
2026-07-27-ep08-cost-controls-16x9.mp4
Episode 09 — Headless runner & CLI (2:12). The engine from a plain terminal: env config, the dry-run plan and cost estimate, a live run in timelapse — ending with the acceptance gate refusing to sign off an artifact that missed a required element.
2026-07-28-ep09-headless-cli-16x9.mp4
We'd love your help. Read CONTRIBUTING.md — dev setup, conventional-commit + test-coverage bars, and the one-time CLA sign-off (automated on your first PR). All participation is governed by our Code of Conduct.
Found a vulnerability? Don't open a public issue — see SECURITY.md for private disclosure via GitHub Security Advisories.
KageOps is built on ideas from the open-source community. With thanks to:
- graphify — inspiration + the engine behind the in-app Code Graph (turn any input into a navigable knowledge graph).
- Agent Lightning (Microsoft) — inspiration for APO, KageOps's opt-in Automatic Prompt Optimization loop.
- caveman (Julius Brussee) — inspiration for Caveman Mode, our terse agent-to-agent prompting that trims inter-agent tokens ~65%.
These projects shaped how KageOps works; any rough edges are ours, not theirs.
AGPL-3.0 © KageOps. Contributions are accepted under the project CLA, which preserves the option to offer KageOps under a commercial license alongside the AGPL open core.