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

   Ask for something you can open and see working right away — a tic-tac-toe game you play against a bot, in a single file with no server:

   kj run "Create a tic-tac-toe game in a single self-contained index.html — vanilla HTML, CSS and JavaScript, no server and no build step. The human plays X, the bot plays O and blocks or takes a winning move when it can. Detect wins and draws, and add a New Game button. Opening index.html in a browser must be enough to play."

   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:

   [triage]     Simple task → lightweight pipeline
   [coder]      Writing index.html — board, styles and vanilla-JS game logic...
   [coder]      Committing: feat: create tic-tac-toe game in single HTML file
   [sonar]      Skipped — no git remote configured
   [impeccable] Design audit passed
   ✔ Pipeline completed (iteration 1/5)

   Triage classified this as a simple task, so it ran a lightweight pipeline — no test framework in an empty folder means standard methodology, and SonarQube is skipped when there’s no remote to scan. On a real repo with a remote and a test suite you’ll also see the SonarQube gate and the full reviewer loop, where the coder gets another attempt whenever the reviewer finds issues, up to the iteration limit.

4. Play it

   The result is one index.html you can open directly — no server, no build:

   git diff                  # See what changed
   open index.html           # macOS — or double-click the file (xdg-open on Linux)
   kj report                 # View session summary

   Click a square to play X, and the bot answers as O — blocking your lines and taking a win when it can. Hit New Game to reset.

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