A parallel autonomous agent swarm that plans, builds, tests, secures, and deploys your software — all at once.
Every AI coding tool today is a single agent — one brain, one task at a time. You ask it to build a feature, and it writes the backend, then the frontend, then the tests, then checks security. Sequentially.
QuantumKoi is a swarm. It decomposes your request into a task DAG, spins up specialized agents in parallel (each in its own git worktree), and merges their output. A backend agent, frontend agent, QA agent, and security agent all working simultaneously — like a real engineering team.
You: "Build a user CRUD API with auth, tests, and deploy config"
QuantumKoi:
Architect ──→ decomposes into 6 parallel tasks
├── Backend agent → models, routes, middleware ─┐
├── Frontend agent → components, state, routing ─┤ parallel
├── QA agent → unit tests, integration tests ─┤
├── Security agent → auth audit, input validation ─┤
└── DevOps agent → Dockerfile, CI pipeline ─┘
Merger ──→ conflict detection, branch merge
Done. One prompt, full feature.
| Capability | What it does | Why it matters |
|---|---|---|
| DAG Orchestration | Architect agent plans tasks as a directed acyclic graph, scheduler runs them in parallel | N tasks finish in ~1 task's time, not N |
| Hash-Anchored Edits | Edits reference content hashes, not line numbers | Survives reformatting, parallel modifications, whitespace changes |
| Hybrid Code Intelligence | Structural graph (SQLite + FTS5) + semantic search | "What calls UserService.create?" AND "find payment processing code" |
| Confidence-Scored Memory | Observations strengthen with repetition, decay over time, flag on contradiction | Agents learn from past runs, don't repeat mistakes |
| Anti-Rationalization | Every agent prompt includes counter-arguments for common shortcuts | Prevents "I'll add tests later" and "this is too simple for validation" |
| Session Replay | Every run recorded as JSONL event stream | qk replay — scrub through every agent decision, tool call, and edit |
| Context Compaction | Compresses old conversation turns while preserving objectives and errors | Long tasks don't blow context windows |
| Git Worktree Isolation | Each agent gets its own filesystem via git worktree |
True parallel execution, zero file contention |
QuantumKoi routes to the right model for each task. Set an API key and it auto-registers.
| Provider | Models | Env Variable | Type |
|---|---|---|---|
| Anthropic | claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001 |
ANTHROPIC_API_KEY |
Native SDK |
| OpenAI | gpt-5.5, gpt-5.4, gpt-5.4-mini, o3 |
OPENAI_API_KEY |
Native SDK |
| Google Gemini | gemini-2.5-pro, gemini-2.5-flash, gemini-3.5-flash |
GEMINI_API_KEY |
Native SDK |
| DeepSeek | deepseek-v4-flash, deepseek-v4-pro |
DEEPSEEK_API_KEY |
OpenAI-compatible |
| Kimi / Moonshot | kimi-k2.6, kimi-k2.5 |
MOONSHOT_API_KEY |
OpenAI-compatible |
| xAI Grok | grok-4.3 |
XAI_API_KEY |
OpenAI-compatible |
| Ollama (local) | Any pulled model (qwen3:32b, llama4:scout, deepseek-r1:32b, ...) |
OLLAMA_ENABLED=true |
OpenAI-compatible |
Any OpenAI-compatible endpoint can be added at runtime:
const router = new LLMRouter();
router.registerProvider("my-provider", "https://my-api.com/v1", "sk-...");# Requires Bun (https://bun.sh)
curl -fsSL https://bun.sh/install | bash
# Clone and install
git clone https://github.com/justin08/quantumkoi.git
cd quantumkoi
bun install
# Link the CLI globally
bun link# 1. Initialize a project
qk init --name my-app
# 2. Index your codebase (builds the structural graph)
qk index
# 3. Query your code intelligence
qk query "UserService"
# 4. Run the agent swarm (requires an LLM API key)
export ANTHROPIC_API_KEY="sk-ant-..."
qk run "Build a REST API for user management with JWT auth and tests"
# 5. Replay what happened
qk replay --list
qk replay <session-id>| Command | Description |
|---|---|
qk init [--name <n>] |
Initialize a QuantumKoi project (creates .qk/ directory) |
qk index [--watch] |
Build the code intelligence graph. --watch for live updates |
qk query <question> |
Search symbols, callers, callees, impact analysis |
qk run <prompt> |
Execute a task with the agent swarm |
qk run <prompt> --dry-run |
Plan only — show the task DAG without executing |
qk status |
Show running/recent sessions |
qk replay [session-id] |
Replay a session's event stream |
qk memory list |
Show stored memories with confidence scores |
qk memory search <query> |
Search memories by content |
qk memory prune |
Remove low-confidence and stale memories |
qk skills list |
List loaded skills (built-in + user) |
qk skills validate <file> |
Validate a skill file against the anatomy spec |
qk config show |
Show full project configuration |
qk config set <key> <value> |
Update configuration (e.g., qk config set llm.default_model gpt-5.5) |
┌─────────────┐
│ qk run │
│ "prompt" │
└──────┬──────┘
│
┌──────▼──────┐
│ Architect │ Decomposes → task DAG
│ Agent │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌─────▼─────┐ ┌───▼───┐ ┌─────▼─────┐
│ Backend │ │ QA │ │ Security │ Parallel execution
│ Agent │ │ Agent │ │ Agent │ (git worktrees)
└─────┬─────┘ └───┬───┘ └─────┬─────┘
│ │ │
└────────────┼────────────┘
│
┌──────▼──────┐
│ Merger │ Conflict detection + merge
└──────┬──────┘
│
┌──────▼──────┐
│ Result │ Evidence-verified output
└─────────────┘
Supporting Systems:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Code Intel │ │ Memory │ │ Skills │ │ Session │
│ Structural │ │ Confidence │ │ Anti-rat │ │ Replay │
│ + Semantic │ │ + Lessons │ │ + Exit Crit │ │ + JSONL │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
| Role | What it does |
|---|---|
| Architect | Analyzes the prompt, decomposes it into tasks, defines interfaces and contracts, produces the task DAG. Does not write code. |
| Backend | Server-side code: APIs, business logic, data models, middleware, database queries |
| Frontend | Client-side code: UI components, state management, routing, styling |
| QA | Tests, coverage, quality gates. Verifies every success criterion with evidence. No "I think it works." |
| Security | OWASP Top 10 audit, dependency scanning, secret detection, input validation |
| DevOps | Dockerfiles, CI/CD pipelines, infrastructure-as-code, deploy scripts |
QuantumKoi indexes your codebase into a two-layer intelligence system:
Layer 1 — Structural Graph (SQLite + FTS5)
- Tree-sitter-based parsing (TypeScript, JavaScript, Python)
- Symbol nodes: functions, classes, methods, types, enums
- Edges: calls, imports, extends, implements
- Instant symbol lookup via full-text search
- Callers/callees at arbitrary depth
- Impact analysis (blast radius of any change)
- Auto-sync via file watcher
Layer 2 — Semantic Index (optional, Qdrant or in-memory)
- AST-aware code chunking
- Embedding-based similarity search
- Intent-based queries ("find payment processing code")
$ qk query "BaseAgent"
Found 7 symbol(s):
class BaseAgent
File: src/agent/base.ts:14-309
Signature: export abstract class BaseAgent
class ArchitectAgent
File: src/agent/roles/architect.ts:4-65
Signature: export class ArchitectAgent extends BaseAgent
...Instead of fragile str_replace or line-number edits, QuantumKoi anchors every edit to a content hash:
[h:3f8a1c02] import { Router } from "express";
[h:91bc4d7e] import { UserService } from "../services/user";
[h:d4e2f001]
[h:a7f10392] const router = Router();
Agents reference h:a7f10392 instead of "line 4". This means edits survive reformatting, whitespace changes, and parallel modifications from other agents. Duplicate lines (like }) are disambiguated using neighbor context hashes.
Skills follow the Addy Osmani skill anatomy format — structured workflows with anti-rationalization tables that prevent agents from cutting corners.
4 built-in skills:
| Skill | Steps | Anti-Rationalization Entries |
|---|---|---|
test-driven-development |
6 | 5 |
code-review-and-quality |
7 | 3 |
security-audit |
7 | 4 |
incremental-implementation |
6 | 4 |
Example anti-rationalization:
| Agent thinks... | Skill responds... |
|---|---|
| "This is too simple for tests" | Simple code has the longest lifespan. Untested simple code becomes untested complex code. |
| "I'll add tests after" | Tests written after implementation are 40% less effective at catching regressions. |
| "We'll add security later" | Security retrofitting costs 10-100x more. The breach happens before "later" arrives. |
Add your own:
qk skills validate my-skill.md
qk skills add my-skill.mdMemories have confidence scores that change over time:
New observation → confidence: 0.50
Confirmed (seen again) → confidence: 0.75
Confirmed (3x) → confidence: 0.90
Contradicted → confidence: 0.20 (flagged)
Stale (>30 days) → confidence *= 0.80 (decay)
Lifecycle hooks fire automatically:
| Event | Action |
|---|---|
task_start |
Load relevant project + agent memories |
agent_complete |
Write task result as observation |
task_failed |
Record failure + extract lesson |
session_end |
Compress session into mental model |
$ qk memory list
Observations: 12 | Lessons: 3 | Avg Confidence: 0.72
[90%] [fact] Project uses Express.js with Zod validation
Seen: 3x | Last: 5/22/2026 | Tags: framework, validation
[70%] [lesson] JWT middleware must check token expiry
Seen: 2x | Last: 5/21/2026 | Tags: auth, securityAll configuration lives in .qk/config.toml:
[project]
name = "my-app"
languages = ["typescript"]
[llm]
default_provider = "anthropic"
default_model = "claude-sonnet-4-6"
architect_model = "claude-opus-4-7"
max_parallel_agents = 4
[llm.ollama]
base_url = "http://localhost:11434/v1"
enabled = true # use local models
[memory]
confidence_decay_days = 30
min_confidence = 0.2
max_memories_per_prompt = 20Switch providers with one line:
qk config set llm.default_provider deepseek
qk config set llm.default_model deepseek-v4-flashsrc/
├── cli/ CLI commands (init, run, index, query, replay, ...)
├── core/ Config, project detection, logger, errors
├── types/ All TypeScript type definitions
├── agent/ Agent framework, roles, sandbox, guardrails
├── orchestrator/ DAG planner, parallel scheduler, merger
├── code-intel/ Structural graph + semantic search
├── edit/ Hash-anchored edit system
├── memory/ Confidence-scored memory + lesson extraction
├── skills/ Skill parser, validator, matcher, built-in skills
├── session/ JSONL event recorder + replayer
└── llm/ Multi-provider router (7 providers, cost tracking)
SINGLE AGENT ─────────────────── MULTI-AGENT SWARM
│ │
ASSISTS HUMAN ─────────┤ │
(copilot) │ Cursor, Copilot, Windsurf │
│ │
EXECUTES ──────────────┤ │
(agent) │ Claude Code, oh-my-pi │ QuantumKoi
│ Codex CLI, Devin │
│ │
+ DEPLOYS ─────────────┤ │
│ (none do this well) │ QuantumKoi
│ │
+ SELF-HEALS ──────────┤ │
│ (nobody) │ QuantumKoi (planned)
- Full tree-sitter AST parsing (replacing regex-based parser)
- MCP server mode (use QuantumKoi as a tool from other agents)
- CloakBrowser integration (stealth browser for agent testing)
- DAP (Debug Adapter Protocol) for programmatic debugging
- IDE plugins (VS Code, Zed, JetBrains)
- Self-healing production loop (monitor → diagnose → fix → deploy)
- Multi-channel communication (Slack, WhatsApp)
# Run tests
bun test
# Lint
bun run lint
# Type check
bun run typecheckMIT
They help you code. We ship your product. 🐟