How-To · Node CLI

Recommended · Estimated time: ~10 min · Karajan iterations: 1–2

This walkthrough takes you from an empty directory to a merged feature on a small Node CLI project. The recipe is deliberately minimal so you can re-run it on a real codebase by swapping the bootstrap step for cd <your-repo>.

Prerequisites

You should already have done the common setup: npm install -g karajan-code, kj init inside the project, and a green kj doctor. If kj doctor is red, fix that first — kj run will refuse to start otherwise.

Walkthrough

1. Bootstrap the project.

   mkdir hello-cli && cd hello-cli
   npm init -y
   npm install --save-dev vitest
   git init -b main && git add -A && git commit -m "chore: scaffold"

   Edit package.json so the test runner is wired up:

   {
     "type": "module",
     "scripts": {
       "test": "vitest run"
     }
   }

   Why ESM + Vitest

   Karajan’s coder and reviewer are trained on modern Node (ESM, top-level await, node: imports). Sticking with ESM avoids back-and-forth iterations where the reviewer flags require() calls.

2. Initialize Karajan in the repo.

   kj init
   kj doctor

   kj init creates .karajan/ and writes the orchestrator config; kj doctor confirms the agent CLIs, Docker, Ollama, and ports are all healthy.

3. Describe the feature in natural language.

   No spec file. No JSON. Just the task as you’d describe it to a colleague:

   kj run "Add a 'greet <name>' command to bin/cli.js that prints \
   'Hello, <name>!'. Add a Vitest test that runs the CLI via execa \
   and asserts the stdout for the name 'world'." \
     --methodology tdd \
     --coder claude \
     --reviewer codex \
     --reviewer-fallback claude \
     --max-iterations 5

   What's happening under the hood

   With --methodology tdd, Karajan writes the failing test first, then the implementation, then re-runs the suite. The reviewer (Codex by default, Claude as fallback) checks the diff. If the reviewer rejects, Karajan loops the coder again — up to --max-iterations.

4. Watch the run on the HU Board.

   Open http://localhost:4000 in another tab while the pipeline runs. You’ll see, in real time:

   • Each role activating (planner → coder → tester → reviewer).
   • The exact prompt + response of every agent call.
   • The diff after each iteration.
   • The reviewer verdict.

   You can also tail the same trace in the terminal:

   kj tail

5. Inspect the result.

   git status
   git diff --stat
   npm test

   Expected output of npm test:

   ✓ tests/cli.test.js (1)
     ✓ greets the given name (42ms)
   
   Test Files  1 passed (1)
        Tests  1 passed (1)

6. Merge.

   Karajan does not push or merge for you by default — that’s your call. When you’re happy with the diff:

   git checkout -b feat/greet-command
   git add -A && git commit -m "feat(cli): add greet <name> command"
   git push -u origin feat/greet-command
   gh pr create --fill

   Or, if you want Karajan to also open the PR for you, add --auto-commit --auto-pr to the kj run invocation.

Possible errors and how to clear them

`vitest: command not found`

You forgot the npm install --save-dev vitest step. Karajan will detect the missing dev-dep in iteration 1 and add it — but if you want it before the run, install it manually.

Reviewer rejects with `requires CommonJS`

You’re not on "type": "module". Either set it, or accept that the coder will rewrite imports to require() — the reviewer is consistent either way.

`kj run` exits with `no coder configured`

Run kj doctor and follow the agent-CLI install instructions. The most common cause is having Claude installed but without a logged-in session (claude login).

Pipeline stalls at `coder:hibernate`

You hit a quota cap. Karajan persists the session to ~/.karajan/standby/<sessionId>.json; resume it with kj standby list then kj standby resume <sessionId> --force after the cap resets.

Variants

With MCP

The same run launched via the MCP from any MCP-capable client (Cursor, Claude Desktop, Codex):

{
  "tool": "kj_run",
  "params": {
    "task": "Add a 'greet <name>' command to bin/cli.js that prints 'Hello, <name>!'. Add a Vitest test.",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

Stricter quality gate

Add --mode strict and the deterministic security collectors:

kj run "<task>" \
  --mode strict \
  --enable-security \
  --enable-sonarcloud \
  --methodology tdd

This wires the OSV-Scanner and Semgrep collectors into the audit, and gates the merge on the Sonar quality gate as well as the reviewer verdict.

Local model only

For air-gapped or budget-constrained runs, swap the coder to OpenCode with a local model:

kj run "<task>" \
  --coder opencode \
  --coder-model gemma-local/coder \
  --reviewer claude \
  --max-iterations 8

--max-iterations is bumped because local models tend to need an extra loop or two.

Next steps

Other stacks

Same recipe, different bootstrap: Python · Web Component · REST API (Node) · Java · Go · Rust

Back to the index

How-To index · setup + troubleshooting