Skip to content
Karajan Code

How-To · Java

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

This walkthrough takes you from an empty directory to a merged feature on a small Java CLI project (Maven + JUnit 5). It also covers the Gradle variant — the only differences are the wrapper and the test command.

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 JDK 17+ (java --version) and either Maven 3.8+ (mvn --version) or a Gradle wrapper.

Walkthrough

Section titled “Walkthrough”

  1. Bootstrap the project.

    Terminal window
    mkdir hello-java && cd hello-java
    mvn -q archetype:generate -DgroupId=dev.kj.hello \
      -DartifactId=hello-java -DarchetypeArtifactId=maven-archetype-quickstart \
      -DinteractiveMode=false
    mv hello-java/* . && rm -rf hello-java
    git init -b main && git add -A && git commit -m "chore: scaffold"

    Open pom.xml and bump JUnit to 5, plus add the surefire plugin so mvn test runs JUnit 5:

    <properties>
      <maven.compiler.source>17</maven.compiler.source>
      <maven.compiler.target>17</maven.compiler.target>
      <junit.version>5.10.2</junit.version>
    </properties>
    

    <dependencies>
      <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
      </dependency>
    </dependencies>

  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 JDK + build tool.

  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 static method 'greet(String name)' to \
    src/main/java/dev/kj/hello/Greeter.java that returns 'Hello, <name>!'. \
    Add a JUnit 5 test in src/test/java/dev/kj/hello/GreeterTest.java \
    that asserts the output for the name 'world'." \
      --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.
    • Maven’s surefire output (or Gradle’s test report) line by line.
    • 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
    mvn test

    Expected output of mvn test:

    [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
    [INFO] BUILD SUCCESS

  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/greeter
    git add -A && git commit -m "feat: add Greeter.greet(name)"
    git push -u origin feat/greeter
    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”

Same flow, different build tool. Bootstrap with the Gradle wrapper:

Terminal window
mkdir hello-java && cd hello-java
gradle init --type java-application --dsl kotlin --test-framework junit-jupiter
git init -b main && git add -A && git commit -m "chore: scaffold"

Then run the same kj run invocation. Karajan auto-detects build.gradle.kts and uses ./gradlew test instead of mvn test.

Next steps

Section titled “Next steps”