Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code — Karajan governs how it happens. kj installs a method your agent follows on every task (RAG before assuming, card first, tests first) and enforces it with git gates: every commit requires a verdict from a different AI, security findings are never overridable, and the base branch only moves via PR. The maker never grades its own work — and a false green is structurally impossible.
Prompt engineering got one good answer from one good prompt. Context engineering curated what the model saw. The 2026 frontier is loop engineering: you stop prompting the agent by hand and design the system that prompts it, checks it, and decides what happens next — until the goal is met or it hands back to you. Karajan was built around that loop before the term caught on:
interactive | assisted | autonomous axis (v3.7.0). Report, then assisted fixes, then unattended kj autorun — defaulting to interactive, so you opt in.kj resume keep the loop alive across runs.The caveat loop engineering insists on — unattended loops make unattended mistakes — is designed in: autonomous runs list their residual defects, every story lands behind a PR, and kj-trash snapshots destructive operations. Read the full building-block mapping →
One-liner setup
Tell your agent: “read karajancode.com/start.md and do what it says”. It installs the full stack, detects new vs existing project, activates the environment — and stops to WAIT for you whenever a step needs sudo or an account. Install →
Your agent, governed
The playbook lands in CLAUDE.md, AGENTS.md and GEMINI.md from one source: RAG first, card first (kj hu), TDD, ADRs in git (kj adr). Role briefs (kj brief) give your agent the distilled method of triage, planner, architect, tester, security and audit. Work with your agent →
Cross-AI review + git gates
kj review --staged binds a verdict from a different AI to the exact diff — change the code and it must be reviewed again. Disagree? A third AI arbitrates (kj solomon); security findings nobody overrides. The pre-commit gate makes it law. The gates →
RAG over your codebase
Built on install, refreshed on drift: kj rag query answers what the code does so no agent guesses. On existing projects, kj onboard produces an Architecture Brief before anyone touches anything.
Self-healing ecosystem
Your agent hits a kj bug? kj report-issue diagnoses and files it upstream — sanitized, deduped, and only with your approval. Fixes ship back to everyone. Command reference →
Headless mode
The classic multiagent pipeline lives on for CI and automation: kj run orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Headless mode →
The most recent releases, newest first. Older versions live in Architecture › History and the CHANGELOG.
Minor closing the trio of controls born from field convergence. When a task touches auth, user input, secrets, network or dependencies, the playbook now orders the agent to run kj audit --security — a focused deterministic pass (prompt-injection + OSV + Semgrep + Sonar, zero tokens) — and remediate the findings BEFORE requesting review. The injection scan covers the agent-context surface (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, templates/, .rulesync/): whatever lands in your agent’s context every session is the real injection vector. Design → scan → remediate, same session.
Minor with two controls born from convergence: a payments processor published how it operates AI agents safely, and their principles mapped almost one-to-one onto Karajan’s gates — except two. Now closed: spawned agents receive an env allowlist (system essentials + their own CLI’s auth + lane vars — your cloud keys and registry tokens never reach a subprocess, so an injected prompt cannot exfiltrate what it never received), and kj check keeps an AI-surface inventory — every MCP reachable in the project, with drift detection: NEW since last check: x — approved by you?. Every new tool an agent gains is one more access, and it should be a conscious one. Named escapes as always: security.env_passthrough, security.env_allowlist: false.
Patch closing the first externally-diagnosed v4 bug: running kj inside Claude Code with coder: claude silently handed the coder role to the host and hung headless runs (issues #1301/#1303 by @jorgecasar). CLI providers now always spawn their own subprocess even when kj runs inside them; delegating to the host is an explicit opt-in (roles.coder.host_delegation: true). Also from the field: kj harden CI workflows now detect the repo’s package manager (pnpm/yarn repos no longer die on npm ci), and the brace-expansion HIGH advisory caught by the nightly drift is resolved. Drop-in upgrade from v4.6.2.
Patch, straight from the field: a session rationalized a 522-line PR past the warning, left commits without card refs while asking whether to adopt the convention, and decided a schema unilaterally. Three answers: method_gates.pr_size: block rejects oversized diffs deterministically (named escape, default stays warn — now worded as not an opinion); design decisions outside the card’s acceptance criteria must come back as a proposed ADR and a question; and a prepare-commit-msg hook stamps the branch’s card ref into every commit subject — a convention that enforces itself needs no adoption. Drop-in upgrade from v4.6.1.
Patch. Every kj invocation already checked for updates; now the notice tells you WHAT the new version brings — the release headline travels with it — the check refreshes every 6 hours instead of daily, and both the notice and the playbook order the agent: tell your user and ask before updating, never kj update on your own. Updating stays a human, informed decision. Drop-in upgrade from v4.6.0.
Minor closing the v4 trade: the agent gained intelligence, the rules gained teeth. Card-first is now a gate (no live card, no commit — with external boards, a presence check); code without tests warns or blocks; a second concurrent task gets the exact kj worktree start command at the exact moment; and kj check reports adherence — commits without cards, verdicts by workspace, testless commits — because legitimate one-offs aggregate into visible drift. Every escape hatch is explicit and named. Phase 106 →
Minor with a contract change. Projects already living in Linear, Trello, Jira or GitHub Issues declare their board and card-first points THERE, worked through your agent’s own MCP/tools — kj never mirrors it into a parallel half-board. The counterweight: kj env install now verifies an operational access path to whatever board you declared (bundled, MCP, or API token) and blocks with the exact steps when there is none. There is no none — Karajan does not run without a board. Phase 105 →
Patch with a first inside: v4.4.0’s install-anywhere fallback died on clean machines because the index probe silently created the vector table at the wrong dimension — fixed with a non-creating probe and an empty-store reset, verified on the exact failing scenario. And when the cross-AI reviewer rejected the fix on a factually wrong premise, kj solomon had its first real run: a third AI arbitrated, ruled on the empirical evidence, and opened the gate. Drop-in upgrade from v4.4.0.
Minor with a family milestone: the first dependency between the two Karajan products. Cloud embedders now require an explicit rag.sensitivity: public — the safe default blocks them with an actionable error — and even when allowed, every chunk passes through karajan-rag’s independently audited PII redaction before leaving the machine. Plus: machines where nothing can be installed get a working RAG — no Ollama found means falling back to the built-in in-process ONNX embedder, with the choice persisted. Drop-in upgrade from v4.3.1.
Patch, both halves from the field. kj hu add now takes the full spec in one call — --ac, --tests, --scope, --task-type — and warns immediately when a story is born incomplete, naming the exact missing flag. And parallel lanes learn resource isolation: worktree_setup documented with a lane-aware example, and the generated coder/review rules teach env-var discipline deriving per-task ports and DB names from the lane slots kj already injects. Drop-in upgrade from v4.3.0.
Minor. An agent narrated worktree isolation while editing the project root — so isolation became a command and a trail. kj worktree start|list|done gives the host agent real task lanes (worktree + branch + dependency bootstrap, one command); the playbook demands the proof before any isolation claim; and every review verdict stamps where it ran — [root] or [worktree:<name>]. If the story and the trail disagree, the trail wins. Drop-in upgrade from v4.2.1.
Patch with a milestone inside: the board’s per-HU play button now feeds the HU’s own title to kj run instead of a generic plan description — no more false spec-review failures on well-defined stories — and the fix came from the field, contributed by @jorgecasar. Plus: the playbook now orders one git worktree per task for parallel work, so any host agent inherits the lane isolation the headless pipeline already practices. Drop-in upgrade from v4.2.0.
Minor. kj review --staged runs SonarQube as a deterministic pre-gate before any AI opinion: findings on the changed files print first, BLOCKER/CRITICAL ones reject on the spot without spending a single reviewer token, and advisory ones travel inside the reviewer’s task. A machine without sonar degrades loudly and continues. On its first live run it caught three pre-existing issues in the very file that implements it. Phase 104 →
Patch, both halves straight from the field. Agents and CI can finally run kj unattended: --non-interactive (or KJ_NON_INTERACTIVE=1) auto-answers safe gates — warnings continue with the decision on stderr, FAIL findings stop the run with a real exit code instead of blocking on a modal nobody watches. And the board now refuses twins: kj hu add rejects duplicate titles across every plan and the playbook orders kj hu list first. Drop-in upgrade from v4.1.10.
Patch. Born from a real CPU storm: every scanner kj launches now runs governed — one scan per tool machine-wide (a second kj waits instead of piling on), semgrep capped at half the CPUs instead of its default 14 jobs, reduced priority, and hard timeouts that kill the whole process tree so an interrupted scan can never leave orphans burning cores. kj doctor finds any pre-existing orphans and offers to kill them. Drop-in upgrade from v4.1.9.
Patch. The dashboard prompt modal now shows every spec-review finding — severity, message and the concrete suggestion — instead of “4 findings at severity fail” and a JSON blob: the fourth issue filed by a user’s own Karajan, fixed and auto-closed within hours. Plus a flaky CI smoke test stabilized for good with mocks that describe the world, not a fragile sequence. Drop-in upgrade from v4.1.8.
Patch. The dashboard-vs-agent fights end, the Planning Game way: HUs can no longer be deleted by anyone’s agent (the fix loop archives, kj hu add refuses to recreate, the API answers 405 with the norm), kj brief board teaches any brain how the board works, and the board stops silently hiding version-drifted plans — the root cause behind “my tasks disappeared”, the third issue filed by a user’s own Karajan and auto-closed by its fix. Drop-in upgrade from v4.1.7.
Patch. A field day, literally: the Windows installer goes npm-first (full product, checksum-verified Node auto-provisioning, SEA behind an env opt-in), every HU on the board now says who created it and what to do next, and the second issue filed by a user’s own Karajan (kj report-issue) was fixed and auto-closed — kj init now writes the gitignore contract block so review verdicts stay local while the gate stays inherited. Plus: external scanners can never fire from the test suite again. Drop-in upgrade from v4.1.6.
Patch. The free-tier era of AI CLIs keeps shrinking — Copilot rides a subscription many developers already have: seventh built-in agent, eligible solomon arbiter (roles.solomon.provider: copilot), verified live end-to-end. The bootstrap prompts are now OS-aware: Windows gets the npm route, never a unix-only curl | sh. Drop-in upgrade from v4.1.5.
Patch. The gemini individual tier retirement left machines without an operational third AI — v4.1.5 restores arbitration: Qwen Code joins as the sixth built-in agent (gemini-cli fork, cloud, free with a Qwen account), and kj solomon survives large diffs (prompt via stdin), trusts headless workspaces, and fails with the way out when an arbiter is dead. Bonus: the README is v4-first, and the bootstrap prompts ship versioned with kj behind karajancode.com/start.md. Drop-in upgrade from v4.1.4.
Patch. A user’s Karajan diagnosed a real install friction and filed it upstream with kj report-issue (sanitized, deduped, human-approved) — and this release ships the fix: semgrep guidance is now distro-aware and PEP 668 safe (Debian/Ubuntu get sudo apt install pipx, never a pip bootstrap that cannot work there). Dependency drift also cleared: npm audit down to zero vulnerabilities. Drop-in upgrade from v4.1.3.
Patch. Never continue degraded: anything kj install-tools cannot install unattended becomes one PENDING USER ACTION block with the exact commands for your OS and a distinctive exit code 3, so your agent stops, shows it, and waits for you. kj env install refuses to call an empty RAG a success. And kj harden recognizes every same-tool config variant (eslint.config.mjs, .eslintrc.*…) so it never eclipses your real linting. Drop-in upgrade from v4.1.2.
Patch. Setting up a Karajan machine is now one command with a complete result. kj install-tools covers the FULL stack — rtk, squeezr and qmd join git, agent CLIs, Semgrep, OSV-Scanner, Lighthouse, Docker and SonarQube in the default list, asking before each install. And the curl installer is npm-first: it installs the complete product (RAG, HU Board, MCP included), auto-provisioning the official checksum-verified Node LTS into ~/.karajan/node when Node is missing — the CLI-only single binary moved behind --standalone. Drop-in upgrade from v4.1.1.
Patch. Three frictions reported by the environment’s first real installs, folded back in: doctor frames a missing MCP as a degraded optional (the standalone curl binary ships without native modules by design — RAG, board and MCP need the npm install), kj review --install-gate rewrites .gitignore by itself so the gate contract is actually inherited by the whole team, and the generated pre-push drops the test suite when CI already runs it per PR. Drop-in upgrade from v4.1.0.
Minor. The environment generalizes: the brain can be Claude Code, Codex, Gemini CLI or Cursor (kj env install --target all writes the playbook for every host from one source). kj solomon brings a neutral third AI to arbitrate when brain and reviewer clash — security findings are never arbitrable. kj brief <role> hands the brain the distilled method of each role it absorbs, rewritten outcome-first (mission + invariants + deliverable — frontier models pick better paths alone; the limits stay explicit). kj agent run is the inter-agent bus, and kj report-issue closes the loop: any user’s brain files kj frictions upstream, sanitized and deduped, never publishing without a human click. New five-page v4 docs (EN+ES) with everything prior grouped as v3 legacy. Drop-in upgrade from v4.0.1.
Patch, folded back from the environment’s first real installs. Hooks generated by kj harden now chain the machine’s previous global hooks (personal guards like an AI-attribution commit-msg keep applying, with the chained hook’s real exit code preserved), and branch-first is both ordered and enforced: the playbook gains an explicit “never commit on the base branch” step and the pre-commit rejects direct commits on the configured base branch (KJ_ALLOW_BASE_COMMIT=1 to override). Drop-in upgrade from v4.0.0.
Major. Karajan becomes an ENVIRONMENT that attaches to the agent you already work with. kj env install writes the method into your agent’s rule file (CLAUDE.md for Claude Code, AGENTS.md for Codex, one single source): query the project RAG before coding, card first, TDD, cross-AI review before committing. kj review --staged sends your diff to an AI different from your orchestrator and records the verdict tied to the sha256 of the exact diff — change the code and it must be reviewed again. kj review --install-gate enables the pre-commit gate: without an approved cross-AI verdict, the commit does not enter, so a false green is structurally impossible. The RAG is built on install and delta-updates before every query; state_backend chooses where work items live (HU Board or Planning Game); and the classic subprocess pipeline continues as the headless mode — its sessions stamp their reviewer’s verdict so both worlds share the same gate. karajan-code itself runs under its own environment: every commit carries a cross-AI verdict.
Patch, the last 3.x release before v4. A complex real-world demo exposed a chain where a run could end “approved” with zero reviewer passes: with RTK installed, the TDD gate parsed an empty compressed diff and failed forever, short-circuiting the reviewer on every iteration; hitting max iterations then finalized as approved without tester, security, audit or push. All four layers are closed — internal git/diff commands always run raw, the TDD gate proceeds to the reviewer with its failure queued as feedback, approval at the iteration cap runs the full post-loop + git finalize path (or honestly reports the rejection), journals record every iteration, and the budget ceiling never shows a phantom $0.00. Drop-in upgrade from v3.15.2.
Patch, born from following our own Quick Start to the letter with a fresh install. On a fresh git init folder, push/PR automation now skips cleanly (“No remote configured”) instead of escalating to Solomon on every iteration and burning the run’s budget. A retired Gemini Code Assist CLI on the PATH no longer poisons runs: its error classifies as an auth failure with an actionable message, binary probes carry a timeout, and Solomon’s fallback provider is now Claude. Also released today: v3.15.1, whose engines fix stops npm from silently installing a months-old version on Node 22.0-22.21. Drop-in upgrade from v3.15.0.
Minor. Three pieces. Parallel lanes now survive real projects: each fresh worktree is bootstrapped (submodules + npm ci or your session.worktree_setup command) and receives KJ_LANE_SLOT / KJ_PORT_OFFSET env vars from a file-locked slot registry, so services started by tests don’t collide on ports. Kimi K2 and DeepSeek join the model registry with real pricing — used through OpenCode as OpenAI-compatible providers, the per-HU $ badge and the budget ceiling price them correctly (setup snippet in docs/providers-via-opencode.md). And the HU Board is fully decoupled from the CLI source tree: the rag subtree lives in karajan-core/rag and an architecture test keeps it that way. Drop-in upgrade from v3.14.1.
Patch. --parallel now actually parallelizes — inside real worktree lanes. The 3.14.0 flag silently degraded to sequential (the plan→batch conversion dropped the scope field the scheduler pairs by), and lanes shared the main working tree. Now the coder, acceptance tests, diffs, sonar and the final commit all run INSIDE each lane’s worktree on its own branch, with per-lane config and session state — verified with a live end-to-end run: two HUs coding concurrently in their worktrees while the main tree stays parked. Also fixed: kj plan ready rejected every generated plan (the auto-injected preflight HU shipped without a status), and unattended --yes runs stopped cold on questions that declare a safe default. Drop-in upgrade from v3.14.0.
Minor. Two new ways to run the orchestra. kj run --step pauses after every iteration with a compact report — what happened, the reviewer’s must-fix list, what the next iteration will do, spend vs cap — and asks: continue, stop, or type instructions that the coder reads next iteration. And kj run --parallel <n> runs a plan’s HUs concurrently, each in its own git worktree, scheduled over the dependency graph with conservative scope isolation and a plan-level budget ceiling. Parallel execution — which previously ran unbounded — now defaults to 1 (fully sequential) and is strictly opt-in. Drop-in upgrade from v3.13.1.
Patch. A stuck or runaway pipeline can no longer drain your subscription quota unattended: max_budget_usd now defaults to 5 (USD-equivalent, checked every iteration). Exceeding it stops the run with an honest summary — what was spent, the limit, how to raise it — and kj resume continues consciously with a fresh window. Set it to null to remove the cap. Born from a field report of a stuck full-orchestra run burning a user’s whole quota. Drop-in upgrade from v3.13.0.