Quick Start

This guide assumes you’ve already installed Karajan Code and run kj init.

Your first run

1. Navigate to your project

   cd /path/to/your/project

2. Run a task

   kj run "Add input validation to the signup form"

   This launches the full pipeline with your configured defaults (e.g., Claude as coder, Codex as reviewer, TDD methodology).

3. Watch the pipeline

   You’ll see real-time output as each role executes:

   [coder]    Writing validation logic and tests...
   [sonar]    Quality gate passed — 0 blockers, 0 critical
   [reviewer] APPROVED — no issues found
   ✔ Pipeline completed in 2m 34s (iteration 1/5)

   If the reviewer finds issues, the coder gets another attempt. The loop continues until approval or the iteration limit is reached.

4. Check the results

   git diff                  # See what changed
   kj report                 # View session summary
   kj report --trace         # Detailed cost breakdown per stage

Three ways to use kj

1. Full pipeline (kj run)

The standard workflow — coder writes, SonarQube scans, reviewer checks, loop until approved:

kj run "Fix the login bug that ignores empty passwords"

2. Coder only (kj code)

Skip the review loop. Useful for quick changes you’ll review yourself:

kj code "Add a loading spinner to the dashboard"

3. Reviewer only (kj review)

Review the current diff without writing code. Useful after manual changes:

kj review "Check my authentication refactor"

Using via MCP (recommended)

The most powerful way to use Karajan Code is as an MCP server inside your AI agent. After npm install -g karajan-code, the MCP server auto-registers in Claude and Codex.

From your agent, simply ask it to run a task:

“Use kj_run to fix the SQL injection vulnerability in the search endpoint”

The agent sends the task to kj_run, gets real-time progress notifications, and receives structured results — all without leaving the conversation.

Manual MCP configuration (if needed):

{
  "mcpServers": {
    "karajan-mcp": {
      "command": "karajan-mcp"
    }
  }
}

See the MCP Server guide for the full list of 23 available tools.

Common options

Flag	What it does
--coder claude	Choose which agent writes code
--reviewer codex	Choose which agent reviews
--methodology tdd	Enforce test-driven development
--mode paranoid	Use the strictest review profile
--enable-triage	Auto-classify task complexity
--enable-security	Run OWASP security audit
--auto-commit	Git commit after approval
--no-sonar	Skip SonarQube analysis
--max-iterations 3	Limit coder/reviewer loops

For the full list, see the CLI Reference.

What happens during a run

triage? → researcher? → planner? → coder → refactorer? → sonar? → reviewer → tester? → security? → commiter?

1. Triage (optional) classifies task complexity and activates only necessary roles
2. Coder writes code and tests following TDD methodology
3. SonarQube (optional) runs static analysis with quality gates
4. Reviewer checks the code with configurable strictness
5. If issues are found, the coder gets another attempt with the reviewer’s feedback
6. Loop until approved or the iteration limit is reached

Built-in guardrails prevent runaway sessions: max iterations, per-iteration timeouts, total session timeouts, and optional estimated budget caps. Karajan itself adds no cost — it runs CLI agents under your existing subscriptions.

Next Steps

• Pipeline — Understand each role in detail
• Configuration — Customize the pipeline
• CLI Reference — All commands and flags
• Examples — Real-world workflow examples