Introduction

One command. Multiple AI agents. Full quality pipeline.

Karajan Code (kj) orchestrates AI agents like a conductor orchestrates an orchestra. You define what needs to happen — code, review, test, secure — and Karajan assigns who does each part.

15 specialized roles. Triage, researcher, architect, planner, coder, reviewer, tester, security, and more.

5 AI agents. Claude, Codex, Gemini, Aider, OpenCode. Mix and match freely.

Zero extra cost. Runs on your existing subscriptions — no API keys needed.

The Problem

There are two ways to use AI coding agents today, and both have serious issues:

Manual usage — You run an agent, wait for the code, check it yourself, find issues, re-prompt, and repeat. No systematic quality enforcement. Slow. Entirely dependent on your own review skills.

Automated usage (CI/CD) — You wire agents into pipelines that run on every push. This removes the manual bottleneck, but introduces uncontrolled costs. A single task can burn through tokens indefinitely — agents retrying, reviewers looping, flaky APIs triggering unlimited retries. Real money, no visibility.

In both cases: no standard way to enforce quality, control spending, or know when to stop.

The Solution

Karajan Code solves both problems by chaining roles with quality gates and cost controls:

💻

Coder

The coder role writes code and tests — executed by the AI agent you choose (e.g. Claude, Codex, Gemini).

🛡

Deterministic Guards

Regex-based guards scan the diff for destructive operations, credential leaks, and performance anti-patterns. No LLM needed.

🔍

Static Analysis

SonarQube performs full static analysis with quality gates. Optionally complemented by SonarCloud for cloud-based advisory analysis.

👁

Reviewer

The reviewer role checks the code for issues (e.g. Codex). Scope filter auto-defers out-of-scope items as tech debt.

🔄

Iterate or Approve

If problems are found, the coder gets another attempt. The loop runs until the code is approved or the iteration limit is reached.

💪

Built-in Guardrails

Max iterations, per-iteration timeouts, session timeouts, and budget caps (USD/EUR). Fail-fast stops loops early. Full cost reports with kj report --trace.

Key Features

Role-based Pipeline

15 specialized roles — each assignable to any agent. Triage, discover, researcher, architect, planner, coder, refactorer, sonar, reviewer, hu-reviewer, tester, security, audit, solomon, commiter.

5 AI Agents

Claude, Codex, Gemini, Aider, OpenCode — mix and match per role. Extensible via plugins in .karajan/plugins/.

MCP Server — 23 Tools

Use kj from your AI agent. Standalone tools: kj_discover, kj_triage, kj_researcher, kj_architect, kj_hu. Real-time progress notifications.

Deterministic Guards

Output guard blocks destructive operations and credential leaks. Perf guard catches frontend anti-patterns. Intent classifier pre-triages without LLM cost.

Injection Guard

Prompt injection scanner that protects AI code review from manipulation. Detects directive overrides, invisible Unicode characters, and oversized comment payloads. Also runs as a GitHub Action on every PR.

Integrated HU Manager

Auto-decomposes complex tasks into formal user stories (HUs). Triage activates hu-reviewer for medium/complex tasks, generating 2-5 HUs with dependencies. Each HU runs its own sub-pipeline (coder→sonar→reviewer) with state tracking. Full PG integration and board visualization.

SonarQube + SonarCloud

Dual static analysis: SonarQube (local Docker, blocking quality gates) and SonarCloud (cloud, advisory). Both run together in the same pipeline.

TDD Enforcement

Test changes required when source files change. The pipeline rejects iterations without matching tests.

Standalone Role Commands

kj discover, kj triage, kj researcher, kj architect — run any pre-build role independently from CLI or MCP.

Budget Tracking

Per-session token counting with estimated API-equivalent costs. Karajan itself adds no cost — it uses your CLI subscriptions.

Resilient Run

Auto-diagnoses failures and resumes crashed sessions — up to 2 retries. Non-recoverable errors fail immediately. Configurable via session.max_auto_resumes.

Git Automation

Auto-commit, auto-push, auto-PR after approval. Review profiles: standard, strict, relaxed, paranoid.

Smart Session Management

Pause/resume with fail-fast detection. Rate limit resilience with auto-fallback. Interactive checkpoints every 5 minutes.

Task Decomposition

Triage detects when tasks should be split and creates linked subtasks in Planning Game.

Quality & Testing

Karajan Code is tested with 2473 automated tests across 190 test files, covering every pipeline role, guard, config option, and MCP tool. The test suite runs in under 14 seconds using Vitest.

Quality is enforced at multiple layers:

SonarQube (local, via Docker) — full static analysis with quality gates, blocking on critical issues
SonarCloud (cloud, no Docker needed) — complementary cloud-based analysis, advisory mode by default
Deterministic guards — regex-based checks for destructive operations, credential leaks, and perf anti-patterns
TDD enforcement — source changes require corresponding test changes

Both SonarQube and SonarCloud can run together in the same pipeline — SonarQube as the primary gate and SonarCloud as an additional lens.

Two Modes

Karajan offers two ways to work:

Skills mode — 8 slash commands (/kj-code, /kj-review, /kj-run, etc.) installed directly in Claude Code. Each command includes built-in guardrails. No MCP server needed — ideal for single-agent workflows. Install with kj init.

Orchestrator mode — Full MCP server with 23 tools. Multi-agent pipeline with subprocess orchestration, session management, budget tracking, and rate-limit resilience. Ideal for complex tasks and CI/CD integration.

Both modes can coexist. Use skills for quick tasks and the orchestrator when you need multiple agents or full pipeline control. See the Skills Guide for details.

Next Steps

Installation — Install Karajan Code
Quick Start — Run your first task
Skills Mode — Use as slash commands