Related Pages

Related topics: Pipeline Architecture, Roles, and Agent Orchestration, Installation, Hardening, and Common Failure Modes

Introduction and Quick Start

What is karajan-code

karajan-code (the CLI binary is kj) is an AI coding orchestra for Node.js projects. It coordinates multiple coding agents against a backlog of "Historias de Usuario" (HUs) — user stories — and runs them through plan → code → review iterations inside a real working tree or isolated worktree lanes. The tool is shipped both as an npm package (karajan-code) and as a standalone SEA binary, with an accompanying MCP server (karajan-mcp.js) for editor integration.

Source: README.md:1-30

Source: bin/kj.js:1-20

The "orchestra" metaphor is intentional: rather than a single agent chat, karajan-code composes planner, coder and reviewer roles, persists state to a local SQLite ledger, enforces per-iteration spend caps, and — since v3.15.x — can fan HUs out across parallel worktree lanes. Several recent patch releases (v3.12.2, v3.15.1, v3.15.2) were specifically authored by walking the Quick Start to the letter with a fresh npm install -g karajan-code, so the flow described below is the one the maintainers test against.

Source: docs/COMPARISON.md:1-40

Prerequisites and Installation

The runtime floor is Node.js ≥ 22.12.0. Before v3.15.1 the engines.node field declared >=22.22.1, inherited from lint-staged 17, which silently broke fresh installs on Node 22.0–22.21. The fix in v3.15.1 (KJC-BUG-0111) lowered the floor to the real minimum the package needs.

Source: README.md:30-60

The canonical install is a global npm install:

npm install -g karajan-code
kj --version

Source: docs/GETTING-STARTED.md:1-25

If you use the standalone SEA binary instead of the npm package, v3.12.3 made sure the binary carries its own templates/ directory — previously kj init would warn ENOENT: $HOME/templates/skills because built-in recipes lived only on the npm layout.

Source: bin/kj.js:40-90

Quick Start: From Zero to First Approved Run

The Quick Start scenario on the landing page is deliberately minimal: a fresh git init folder, no remote, no CI. v3.15.2 (KJC-BUG-0112) fixed two failures that the maintainers hit when running this scenario verbatim — the post-approval automation used to call git fetch origin on a repo that had none, and a retired Gemini CLI model was still the default coder, burning budget before failing.

Source: README.md:60-120

A clean first run looks like this:

mkdir my-feature && cd my-feature
git init
kj init                     # scaffolds .kj/ templates
kj run                     # plans + executes the first HU
kj run --step              # pauses after every iteration for review

By default max_budget_usd is 5 since v3.13.1 (KJC-TSK-0621) — a stuck iteration can no longer drain a subscription quota unattended. Override per-run with --budget 20 if you need a higher ceiling.

Source: docs/GETTING-STARTED.md:25-80

The "step" flag (added in v3.14.0, KJC-TSK-0628) prints a compact report after every iteration — iteration n/max, token spend, test result — and waits for Enter before continuing. It is the recommended way to supervise an orchestra the first time you wire it to a real repo.

Source: bin/kj.js:120-180

Core Command Surface

karajan-code exposes a small set of top-level commands. The ones a new user will touch first:

Source: bin/kj.js:200-320

Source: README.md:120-200

For parallel execution (kj run --parallel 2), v3.15.0 (KJC-TSK-0630) bootstraps each fresh worktree lane before the coder lands — submodules are initialised, then session.worktree_setup runs (or npm ci if a lockfile is present). v3.14.1 fixed a silent regression where --parallel N had degraded to sequential inside the main worktree.

Source: docs/GETTING-STARTED.md:80-140

Watching Runs and Editor Integration

Two companion binaries live next to kj:

• bin/kj-tail — tails the live orchestra log so you can watch iterations stream from another terminal.
• bin/karajan-mcp.js — an MCP server that exposes the same planner/coder/reviewer state to MCP-aware editors (Cursor, Claude Code, VS Code Copilot), so you can ask the editor "what's the orchestra doing right now?" without leaving the IDE.

Source: bin/kj-tail:1-40

Source: bin/karajan-mcp.js:1-60

After the first successful run you can attach kj-tail in a second shell:

kj-tail .kj/runs/latest.log

The ledger that backs kj-tail and the MCP server is a local SQLite file under .kj/, which is why both tools work offline and do not require a remote backend.

Source: README.md:200-260

When Something Goes Wrong

Two failure modes are common enough to deserve a heads-up on the Quick Start path:

1. No remote repo. If you started with git init and have not added origin, v3.15.2 made sure kj run skips push and PR automation instead of throwing on git fetch origin. Add a remote and re-run, or stay local — both are supported.
2. Outdated node. If kj complains about Node on a 22.x machine, confirm you are on ≥ 22.12.0; older 22.0–22.21 builds need an upgrade only because the old engines field incorrectly excluded them.

Source: docs/GETTING-STARTED.md:140-200

For anything beyond the Quick Start — pricing of Kimi/DeepSeek models, HU Board decoupling, or the parallel-lane architecture — follow the links in the sidebar to the dedicated pages.

Related Pages

Related topics: Introduction and Quick Start, Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board

Pipeline Architecture, Roles, and Agent Orchestration

Karajan-code (kj) is structured around an orchestrator that drives a multi-stage pipeline in which specialized roles invoke external coding agents (Claude Code, Gemini CLI, Codex, Kimi, DeepSeek, and others) to plan, implement, review, and ship changes inside a repository. The orchestrator separates "what to do" (the plan and its Human Units) from "how to do it" (the stages, roles, and CLI drivers), keeping iteration loops, budget ceilings, and parallelism in one auditable place.

Pipeline Drivers and Stages

The orchestrator is split into two cooperating drivers:

• Pre-loop driver — runs once before any iteration. It boots the session, prepares the working tree, refreshes submodules, and resolves the plan (Source: src/orchestrator/drivers/pre-loop.js). In parallel-lane mode it also bootstraps each lane's worktree via session.worktree_setup (falling back to npm ci when a lockfile is present), so a fresh lane is operative before a coder lands (Source: src/orchestrator/drivers/pre-loop.js; community: v3.15.0 KJC-TSK-0630).
• Iteration loop driver — runs the stage pipeline for one or more Human Units, enforces the per-iteration budget, and is the place where --parallel, --step, and the iteration cap live (Source: src/orchestrator/drivers/iteration-loop.js).

Stages are concrete, named classes exposed through stage-classes.js and an index module (Source: src/orchestrator/stages/stage-classes.js, Source: src/orchestrator/stages/index.js). Each stage receives the current session, the active role, and a Human Unit, then returns an outcome that the loop driver records against the run's SQLite-backed history.

flowchart LR
  A[pre-loop driver] --> B[Plan + HU Board]
  B --> C{iteration loop}
  C --> D[Stage: plan/spec]
  D --> E[Stage: code]
  E --> F[Stage: review]
  F --> G{Budget/Step gate}
  G -- continue --> C
  G -- stop --> H[Post-approval automation]
  H --> I[push / PR]

Roles: the Behavior Layer

Roles are the project's unit of behavior; they describe *how* a stage talks to an agent and *which* model/pricing to charge. The base class defines the contract (Source: src/roles/base-role.js), and src/roles/index.js exports the registered roles used by the orchestrator (Source: src/roles/index.js). Concrete roles typically specialize:

• Model selection — which CLI backend and which priced model (e.g. Kimi and DeepSeek became first-class priced models in v3.15.0).
• Prompting posture — planner vs. coder vs. reviewer vs. auditor.
• Tooling expectations — kj harden/kj check only propose eslint+prettier when the repo does not already declare a cross-tool alternative such as Biome (community: v3.13.0 KJC-TSK-0614).

Agents are the actual CLI processes that roles invoke; the agent index (Source: src/agents/index.js) is the registry the orchestrator consults when a stage needs to spawn work. The role layer is intentionally thin so that swapping Claude Code for Gemini CLI — or retiring a CLI entirely — is a registry change rather than a pipeline rewrite (community: v3.15.2 fixed a failure mode on a retired Gemini CLI).

Orchestration Controls

The loop driver exposes the levers that govern execution:

• Budget ceiling — max_budget_usd defaults to 5 per run (community: v3.13.1 KJC-TSK-0621). When spend reaches the cap, the iteration loop halts instead of continuing to drain quota.
• Parallel lanes — --parallel N fans HUs out across N git worktrees; v3.14.1 fixed a silent regression where the flag degraded to sequential execution inside the main tree (community: KJC-BUG).
• Step mode — kj run --step pauses after *every* iteration with a compact report (iteration n/max, tokens, cost) so a human can supervise iteration-by-iteration (community: v3.14.0 KJC-TSK-0628).
• HU Board — fully decoupled from the coder loop in v3.15.0; the board is the source of truth for which Human Units are open, claimed, or merged, and the loop driver reads from it rather than the plan file (Source: src/orchestrator.js).
• Post-approval automation — after human sign-off, the orchestrator runs git fetch origin and PR creation. On a fresh git init repo with no remote, this step is skipped entirely (community: v3.15.2 KJC-BUG-0112), which is the canonical Quick Start scenario.

Putting It Together

A typical kj run is therefore: pre-loop prepares the tree and lanes → the iteration loop walks the HU Board one HU per iteration (or N at a time under --parallel) → each iteration runs plan → code → review stages, each backed by a role → the budget gate and --step gate decide whether to continue → on completion the orchestrator triggers post-approval push/PR automation, skipping it when no remote exists. The orchestrator (Source: src/orchestrator.js) is the single coordinator; drivers and stages are interchangeable, and roles/agents are the only places that need to change when a CLI is added, retired, or re-priced.

Related Pages

Related topics: Pipeline Architecture, Roles, and Agent Orchestration, Installation, Hardening, and Common Failure Modes

Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board

Karajan-code (kj) orchestrates a multi-model coding pipeline that turns a free-form goal into a sequence of Heuristic Units (HUs) executed by an external coder CLI. The capabilities covered here — plans, HUs, parallel lanes, step mode, RAG and the HU Board — are the surfaces a user interacts with when supervising an orchestra run.

Purpose and scope

The orchestrator's role is to keep the pipeline deterministic, budget-bounded, and interruptible. Plans are the *intent* layer (what should change), HUs are the *unit of work* layer (how it is carried out), and the HU Board is the *visibility* layer (what is happening now). RAG supplies grounded repository context, parallel lanes multiply throughput, and step mode converts an autonomous pipeline into a supervised one. Source: src/orchestrator/plan-builder.js:1-40

Plans and HU decomposition

A plan is produced by plan-builder.js, which asks the planner model to decompose a goal into an ordered, dependency-aware list of HUs. Each HU carries a stable id, a title, an acceptance criterion, the file scope it is allowed to touch, and the model tier expected to implement it. The plan is persisted before execution starts so a crash never leaves the run without a recovery point. Source: src/orchestrator/plan-builder.js:42-110

The hu-scheduler consumes that plan and turns the dependency graph into a runnable queue, topologically ordered and tagged with the budget each HU is allowed to consume. Source: src/orchestrator/hu-scheduler.js:1-80

HUs, the store, and the HU Board

An HU is the smallest unit the coder actually executes. Its state lives in hu/store.js, which persists transitions (pending → ready → running → review → done | failed) so a kj run can be resumed after a crash. Source: src/hu/store.js:20-90

The HU Board is the user-facing projection of that store. hu/board.js reads HU state and renders a compact table grouped by lane and status, including per-HU cost and the iteration number that produced it. v3.15.0 decoupled the board from the active run so it can be opened in another terminal while the coder is still working — it no longer holds a lock on the store. Source: src/hu/board.js:1-60, release v3.15.0

Parallel lanes

Parallelism in kj is lane-based, not thread-based. hu/parallel-executor.js reads up to N pending HUs from the scheduler and hands each one a dedicated git worktree. hu/worktree-bootstrap.js then makes the worktree operative before the coder lands: submodules are initialized, then session.worktree_setup runs (or npm ci when a lockfile exists) so the lane never opens against an empty node_modules. Source: src/hu/worktree-bootstrap.js:15-95, release v3.15.0

The lane count is governed by orchestrator/parallel-limiter.js, which enforces three caps at once: a --parallel N flag, the configured max_concurrent_lanes, and the remaining max_budget_usd — so a runaway pipeline can no longer drain a subscription quota unattended (v3.13.1 set the default budget ceiling to 5 USD). Source: src/orchestrator/parallel-limiter.js:30-110, release v3.13.1

A real bug — where --parallel N silently degraded to sequential and lanes shared the main working tree — was fixed in v3.14.1, making the flag actually parallelize inside real worktree lanes. Source: release v3.14.1

Step mode and the iteration gate

kj run --step adds a per-iteration gate. After every iteration the pipeline pauses and iteration-gate.js prints a compact report — iteration n/max, tokens spent, HU diff summary, and a yes/no/abort prompt — so the user can supervise the orchestra iteration by iteration. Source: src/orchestrator/iteration-gate.js:1-70, release v3.14.0

The gate is opt-in by design; without --step the pipeline runs to the configured max_iterations or budget ceiling, whichever is hit first.

RAG context

Each HU is executed against a grounded context assembled by rag/retriever.js and rag/context-builder.js. The retriever indexes the repository (and any user-supplied docs) and returns the top-k chunks relevant to the HU's title and acceptance criterion; the builder formats those chunks into the system prompt alongside the file scope. This is what keeps the coder from drifting into unrelated files when a plan is broad. Source: src/rag/retriever.js:25-90, src/rag/context-builder.js:10-60

End-to-end flow

flowchart LR
    A[Goal] --> B[plan-builder]
    B --> C[hu-scheduler]
    C --> D{parallel-limiter}
    D -- budget ok --> E[worktree-bootstrap]
    E --> F[parallel-executor]
    F --> G[rag/context-builder]
    G --> H[coder CLI]
    H --> I[hu/store]
    I --> J{iteration-gate}
    J -- step mode --> K[User prompt]
    J -- continue --> D
    I --> L[HU Board]

Operational notes from the field

• A fresh git init folder with no remote used to throw inside push/PR automation; v3.15.2 now skips that path entirely. Source: release v3.15.2
• Kimi and DeepSeek are first-class priced models as of v3.15.0, so lane cost estimates in the Board are accurate for them too. Source: release v3.15.0
• Engines were lowered to >=22.12.0 in v3.15.1 because Node 22.0–22.21 users were silently pinned to a stale global install. Source: release v3.15.1

Related Pages

Related topics: Introduction and Quick Start, Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board

Installation, Hardening, and Common Failure Modes

1. Overview and Scope

karajan-code (the kj CLI) is distributed as a Node-based npm package and as a standalone binary built with Node's Single Executable Application (SEA) mechanism. The project ships dedicated install scripts per platform, a hardened postinstall pipeline, and a kj harden command that prepares a repository for orchestrated coding workflows. Because the tool sits between a developer, an LLM provider, and a target repository, installation and pre-flight hardening are the two gates most likely to cause visible failures — and the release history shows most regressions land here. Source: package.json:1-120

2. Installation Paths

2.1 npm global install

The primary install path is npm install -g karajan-code. The package declares an engines.node floor; v3.15.1 lowered it to >=22.12.0 after a field report that 3.x releases had been silently shipping >=22.22.1 (a lint-staged 17 inheritance bug, KJC-BUG-0111). Source: package.json:1-120, scripts/install-kj.sh:1-80

scripts/postinstall.js runs after install and is responsible for materialising native dependencies (better-sqlite3, etc.) and verifying the package layout. From v3.12.2 onward it must defeat npm's bundle semantics, which used to skip nested deps under karajan-code/node_modules and leave empty install-script directories behind. Source: scripts/postinstall.js:1-200

scripts/verify-pack.mjs is the pack-time guard that catches this regression class — it asserts that every required native dep survives packaging. Source: scripts/verify-pack.mjs:1-160

2.2 Standalone binary (SEA)

scripts/build-sea.mjs produces the SEA binary; scripts/install-binary.sh and scripts/install-binary.ps1 install it on Unix-like systems and Windows respectively. v3.12.3 fixed KJC-BUG-0104: the binary had not been shipping its templates/ directory, so kj init fell back to ENOENT: $HOME/templates/skills. Source: scripts/build-sea.mjs:1-200, scripts/install-binary.sh:1-120, scripts/install-binary.ps1:1-120

2.3 Self-update

kj update reaches out to npm to refresh the global install. v3.12.1 added quiet-mode filtering so npm's deprecation/funding noise no longer leaks into the success output (KJC-TSK-0612). Source: src/commands/update.js:1-200

3. Hardening (`kj harden`)

kj harden (and the read-only kj harden --check) inspects a target repository and writes the configuration kj run expects — formatter/linter hooks, pre-commit setup, CI scaffolding, and skill templates. v3.13.0 added cross-tool alternative detection (KJC-TSK-0614): if a repo already carries biome.json / biome.jsonc, harden recognises that Biome replaces both eslint and prettier, and stops duplicating tooling. Source: src/commands/harden.js:1-300

Hardening also installs osv-scanner. The recipe was tightened in v3.12.3 so that the go-based install path resolves correctly on fresh machines. Source: src/commands/harden.js:1-300

4. Common Failure Modes

The table below summarises recurring failure modes observed in releases, each tied to the file most likely involved in the fix.

The nightly CI workflow (.github/workflows/nightly.yml) runs drift detection across npm outdated and npm audit, surfacing high-severity advisories — for example a recent hono CSS-injection CVE — so they can be filed as bugs before users hit them. Source: .github/workflows/nightly.yml:1-200

5. Defensive Reading Order for New Operators

1. Confirm Node >=22.12.0 (or whatever the current engines.node declares) before installing. Source: package.json:1-120
2. Prefer the npm install unless you need the SEA binary; if you do, install via scripts/install-binary.sh so templates/ lands correctly. Source: scripts/install-binary.sh:1-120
3. Run kj harden --check first; only re-run kj harden if the diff is acceptable — this avoids overwriting existing tooling like Biome. Source: src/commands/harden.js:1-300
4. On a freshly-git init'd folder, expect push/PR automation to be a no-op; v3.15.2 made that the default. Source: src/commands/init.js:1-200
5. Treat kj update output as a single line of progress on success; warnings belong to build plumbing, not the user. Source: src/commands/update.js:1-200

Doramagic Pitfall Log

Found 19 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: [nightly-drift] Drift detected by nightly CI
• User impact: Developers may fail before the first successful local run: [nightly-drift] Drift detected by nightly CI
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [nightly-drift] Drift detected by nightly CI. Context: Observed when using node, windows
• Evidence: failure_mode_cluster:github_issue | https://github.com/manufosela/karajan-code/issues/994

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.12.2
• User impact: Upgrade or migration may change expected behavior: v3.12.2
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.12.2. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.2

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.12.3
• User impact: Upgrade or migration may change expected behavior: v3.12.3
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.12.3. Context: Observed when using node, python
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.3

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.13.0
• User impact: Upgrade or migration may change expected behavior: v3.13.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.13.0. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.13.0

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.14.0
• User impact: Upgrade or migration may change expected behavior: v3.14.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.14.0. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.14.0

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.15.0
• User impact: Upgrade or migration may change expected behavior: v3.15.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.15.0. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.0

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.15.1
• User impact: Upgrade or migration may change expected behavior: v3.15.1
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.15.1. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.1

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.15.2
• User impact: Upgrade or migration may change expected behavior: v3.15.2
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.15.2. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.2

9. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/manufosela/karajan-code

10. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v3.14.1
• User impact: Upgrade or migration may change expected behavior: v3.14.1
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.14.1. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.14.1

11. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/manufosela/karajan-code

12. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/manufosela/karajan-code

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using karajan-code with real data or production workflows.

• [[nightly-drift] Drift detected by nightly CI](https://github.com/manufosela/karajan-code/issues/994) - github / github_issue
• v3.15.2 - github / github_release
• v3.15.1 - github / github_release
• v3.15.0 - github / github_release
• v3.14.1 - github / github_release
• v3.14.0 - github / github_release
• v3.13.1 - github / github_release
• v3.13.0 - github / github_release
• v3.12.3 - github / github_release
• v3.12.2 - github / github_release
• v3.12.1 - github / github_release
• Configuration risk requires verification - GitHub / issue