Open source · AGPL-3.0 · Local-first

Run KageOps yourself

KageOps is an open-core, local-first autonomous software-engineering team: an orchestrator named Sensei coordinates eight specialist agents through a six-phase product lifecycle — on your own machine, against your own AI keys, under a budget cap you set. This is the engine. Clone it, read it, run it.

What is KageOps?

You describe what you want — a sentence, a brief, a half-formed prompt — and a team of AI agents research, design, build, test, and ship it. KageOps is the orchestration layer that coordinates that team. The engine is open source; you bring the AI keys.

Three things make it different from a single-chat coding tool:

It's a team, not a chat. Eight specialists each own a slice of the lifecycle, coordinated by an orchestrator called Sensei — nine agents in all.
It runs on your machine. An embedded Postgres (PGlite/WASM) database, a local event bus, and your project files — all local, no Docker required to start.
You set the budget. Every run has a hard USD cap and a budget-kill that cancels the run before it overspends.

Open core, in one line

The orchestration engine, agent framework, CLI, local database path, and cost guardrails are open (AGPL-3.0). The managed cloud-execution and team/enterprise layer is commercial. See Open core for the exact boundary.

Quickstart

Node.js 20+ is the only prerequisite. The first build you preview costs nothing.

1. Clone & install

# clone the open core
git clone https://github.com/hmanoor/kageops-core
cd kageops-core && npm install

2. Preview a build (zero spend)

The dry-run never makes an AI call. It decomposes the brief, shows the phase plan and a heuristic cost estimate, and exits.

npx tsx src/cli/headless-runner.ts --dry-run \
  --name "MyApp" --description "Build a counter with <h1 id=\"count\"> and <button id=\"increment\">"

3. Run it for real (with a budget cap)

A real run must have an explicit cap. The budget-kill polls spend and cancels the moment the cap is hit.

KAGEOPS_PRESET=openrouter_budget KAGEOPS_MAX_RUN_USD=0.50 \
  npm run run:headless -- --name "MyApp" --description "..."

Spec tip — give the gate something to check

Include HTML-style id="..." markers in your description. The AcceptanceGate extracts them and verifies each appears in the produced output — that's how a run knows it actually built what you asked for.

The headless runner

The headless runner drives the full pipeline without the desktop UI — it's the fastest way to see the engine work and the entry point most contributors start from.

Flag	What it does
`--dry-run`	Preview the plan + cost. No AI calls, no spend. Always run this first.
`--name`	Project name. Becomes the workspace folder under `~/.kageops/projects/`.
`--description`	The brief, inline. Embed `id="..."` acceptance markers here.
`--description-file`	Read the brief from a file (preferred for anything non-trivial).
`--resume <id>`	Resume an interrupted run from `projects.current_phase`.
`--trust <level>`	`low` / `medium` / `high`. Controls phase-gate auto-advance.

Key environment variables:

Variable	Default	Purpose
`KAGEOPS_PRESET`	—	Provider preset: `ollama`, `openrouter_budget`, `openrouter_standard`.
`KAGEOPS_MAX_RUN_USD`	`0.25`	Hard per-run cap. Budget-kill cancels the run when breached.
`KAGEOPS_MAX_AI_CALLS_PER_TASK`	`8`	Per-task ceiling on AI calls.
`KAGEOPS_ZOMBIE_TIMEOUT_MS`	`60000`	Abort a run if no tasks decompose within this window.
`KAGEOPS_DISABLE_GIT`	off	Short-circuit all git ops to no-ops (useful for throwaway test runs).

The Autonauts

KageOps coordinates Sensei (orchestrator) plus eight specialist agents — nine in total. Each extends a common AutonautAgent base class and owns a slice of the lifecycle.

Sensei

Orchestrator

Routes work between agents, manages phase gates, never does task work directly.

Scout

Strategist

Research, scope, competitive landscape. Runs first to figure out what's worth building.

Blueprint

Architect

System design, technical decisions, file structure. Hands Forge a plan it can execute.

Pixel

Designer

UI design, layout, copy, brand consistency. Owns everything the user sees.

Forge

Engineer

Writes the code. Implements features against Blueprint's architecture and Pixel's designs.

Cipher

Data specialist

Schema design, migrations, queries. Owns everything that touches the database.

Aegis

Platform engineer

Build pipelines, deployment, infrastructure. Makes sure what Forge writes actually ships.

Vigil

Quality guardian

Tests, acceptance gates, regression checks. Says "no" so a bad build never reaches you.

Herald

Marketer

Launch copy, landing pages, growth hooks. Runs in the final phase once the product works.

Project lifecycle

Every project flows through up to six phases. You choose which to run.

Discovery — Scout researches the problem space.
POC — Smallest thing that proves the idea works.
Business viability — Costs, market fit, pricing assumptions.
Design & Planning — Pixel designs, Blueprint architects.
Development — Forge, Cipher, and Aegis build. Vigil tests.
Launch & Growth — Herald handles announcement, copy, growth.

Two automated gates run between development and launch: a BuildVerificationGate (runs install/build/test) and an AcceptanceGate (verifies the required id="..." markers from your brief appear in the output). On failure, Sensei spins up a fix task for Forge and retries before escalating.

Phase gates respect a trust level: low pauses at every gate, medium auto-advances routine ones, high is autonomous after the design phase.

AI providers

You bring your own AI keys — KageOps ships with no built-in key. Set them via environment variables or a .env file. The adapter supports five providers:

Provider	Best for	Where to get a key
Claude API	Premium quality, complex projects	console.anthropic.com
OpenRouter	Pay-as-you-go, many models, budget runs	openrouter.ai/keys
Ollama	Fully local, free, no internet needed	ollama.ai (install locally)
OpenAI	GPT-class models	platform.openai.com/api-keys
Gemini	Google's models	aistudio.google.com

Presets bundle a sensible per-agent provider/model mix. Select one with KAGEOPS_PRESET or by dropping an agent-config.<preset>.json into your data dir. Mix freely — Claude for Forge, a budget model for Scout, local Ollama for dry runs.

Subscription CLIs (no per-call cost)

If you already pay for Claude.ai or ChatGPT, the CLI providers run against your subscription quota with no per-call charge — KageOps spawns the official binary and reads its cached session.

Claude CLI

npm install -g @anthropic-ai/claude-code
claude   # sign in once; session cached in ~/.claude/

Then select the Claude CLI preset. KageOps locates the binary automatically; set KAGEOPS_CLAUDE_CLI_PATH if it lives somewhere unusual.

Codex CLI

npm install -g @openai/codex
codex    # sign in once with your ChatGPT account

Tune with KAGEOPS_CODEX_CLI_PATH / KAGEOPS_CODEX_CLI_ARGS.

Subscription mode shows $0

Under subscription mode the cost panel reads $0 (no per-call pricing is exposed) — but the call still burns your monthly quota. The token count is shown alongside so you can track it. Hit your limit and KageOps falls back to whatever metered provider you've configured.

Cost controls

The biggest fear with autonomous agents is runaway spend. The guardrails are non-negotiable and on by default.

Per-run budget cap — hard USD limit (KAGEOPS_MAX_RUN_USD). The run is killed the moment cumulative spend hits the cap.
Per-task call cap — each task makes at most N AI calls (default 8).
Per-agent token cap — a max-tokens ceiling per call so one response can't run away.
Zombie guard — abort if no tasks decompose within the timeout window.
Dry-run mode — preview the full plan without making any AI calls.

Always dry-run an unfamiliar prompt

It costs nothing and shows you the full task decomposition and a cost estimate before you commit a single token.

Open core

KageOps is open core, not open everything — and we're upfront about the boundary. The engine that does the work is genuinely open source under AGPL-3.0. We monetize the managed cloud-execution layer, not the binary you run locally.

Open · AGPL-3.0

The engine

Sensei orchestrator + event bus
The eight Autonauts + agent framework
The headless CLI runner
Embedded local database path
Build & acceptance gates
Cost guardrails

Commercial

The managed layer

Cloud burst execution (Azure ACI)
Team / enterprise collaboration
Hosted auth & SSO
Client billing & deploy
Signed installers + auto-update

Self-hosting the open core is a first-class path — it never phones home for the work itself. The commercial layer is opt-in and lives in a separate repository.

Self-hosting & data

KageOps is local-first. Nothing about a run requires our servers.

Database — an embedded Postgres (PGlite/WASM) boots in-process; data persists at ~/.kageops/pgdata. No Docker needed. For a team deploy, point DATABASE_URL at your own Postgres 16 + pgvector.
Your code — every run's workspace lives under ~/.kageops/projects/<name>. Git, files, build artifacts: local only.
Your prompts — sent only to whichever AI provider you configured. KageOps doesn't proxy them.
Your AI keys — read from your environment / OS keychain, never committed.

Data dir isolation

Set KAGEOPS_DATA_DIR to run multiple isolated instances (handy for tests and benchmarks) — each gets its own database and project workspaces.

Contributing

Contributions are welcome. The bar is simple and enforced by CI:

Conventional commits — feat:, fix:, refactor:, docs:, test:, ci:.
Type-clean — npx tsc --noEmit must pass under --strict.
Tests green — npm test (Vitest). New behavior ships with tests.
Secret-clean — a secret scanner runs pre-commit and in CI; no keys in diffs.

Read CONTRIBUTING.md in the repo for the full process and the CLA sign-off. Look for good first issue labels to get started.

No SLA on community support

This is an open-source project maintained alongside a commercial product — issues and PRs are triaged on a best-effort basis. Be specific and include a reproduction.

Troubleshooting

Run hits the budget cap immediately

Some models charge a lot per token — a single premium call can exceed a tight cap. Raise KAGEOPS_MAX_RUN_USD or switch to openrouter_budget.

Run starts but no agents do anything

Most often the provider key is missing/invalid or the model isn't available. Confirm your .env / preset and try a provider you know works (Ollama for a free local check).

"Database system was not properly shut down"

A stale PGlite lock from a previous crash. Delete ~/.kageops/pgdata/postmaster.pid and re-run; the embedded DB recovers automatically on next boot.

Workspace "not a git repository"

Harmless — agents write files directly. If a gate needs a real repo, git init the workspace, or set KAGEOPS_DISABLE_GIT=1 to skip git entirely.

Community & support

GitHub: github.com/hmanoor/kageops-core — issues, discussions, PRs.
Security: see SECURITY.md for responsible disclosure.
The product: the polished desktop app, cloud burst, and team features live at kageops.ai.
Built with KageOps: see what the engine has shipped on the showcase.