Skip to content
Karajan Code

How-To · Rust

Systems · Estimated time: ~15 min · Karajan iterations: 2–3

This walkthrough takes you from an empty directory to a merged feature on a small Rust CLI crate using cargo + clap for argument parsing. It includes the exact test loop Karajan uses to gate merges (cargo test), so you can re-run it on a real codebase by swapping the bootstrap step for cd <your-repo>.

Prerequisites

Section titled “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.

You’ll also need a Rust toolchain via rustup (rustc --version → 1.75+ recommended) and cargo on PATH.

Walkthrough

Section titled “Walkthrough”

  1. Bootstrap the project.

    Terminal window
    cargo new hello-rs --bin
    cd hello-rs
    cargo add clap --features derive
    git add -A && git commit -m "chore: scaffold"

    cargo new --bin generates Cargo.toml, src/main.rs with a Hello, world! stub, and initializes a git repo automatically. Confirm cargo test runs (it’ll report 0 tests for now):

    Terminal window
    cargo test

  2. Initialize Karajan in the repo.

    Terminal window
    kj init
    kj doctor

    kj init creates .karajan/ and writes the orchestrator config; kj doctor confirms the agent CLIs, Docker, Ollama, ports, and detects the Rust toolchain (cargo, rustc version).

  3. Describe the feature in natural language.

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

    Terminal window
    kj run "Add a 'greet --name=<name>' subcommand to src/main.rs using \
    clap with derive. It should print 'Hello, <name>!' to stdout. If \
    --name is missing, print 'Hello, stranger!'. Add unit tests in a \
    #[cfg(test)] module covering the greet function for both cases." \
      --methodology tdd \
      --coder claude \
      --reviewer codex \
      --reviewer-fallback claude \
      --max-iterations 5

  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.
    • cargo test output line by line, including rustc warnings.
    • The reviewer verdict.

    You can also tail the same trace in the terminal:

    Terminal window
    kj tail

  5. Inspect the result.

    Terminal window
    git status
    git diff --stat
    cargo test

    Expected output of cargo test:

    running 2 tests
    test tests::greet_with_name ... ok
    test tests::greet_without_name ... ok
    

    test result: ok. 2 passed; 0 failed; 0 ignored

    Sanity-check live:

    Terminal window
    cargo run -- greet --name=world
    # Hello, world!
    cargo run -- greet
    # Hello, stranger!

  6. Merge.

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

    Terminal window
    git checkout -b feat/greet
    git add -A && git commit -m "feat: add greet subcommand"
    git push -u origin feat/greet
    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

Section titled “Possible errors and how to clear them”

Variants

Section titled “Variants”

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=<name>' clap subcommand printing 'Hello, <name>!' (or 'Hello, stranger!' if missing). Unit tests in #[cfg(test)].",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

Next steps

Section titled “Next steps”