Skip to content
Karajan Code

How-To · Go

Backend · Estimated time: ~12 min · Karajan iterations: 1–2

This walkthrough takes you from an empty directory to a merged feature on a small Go module using the standard library plus go test. It also covers the Cobra variant if you want a real CLI binary on top.

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 Go 1.22+ (go version).

Walkthrough

Section titled “Walkthrough”

  1. Bootstrap the project.

    Terminal window
    mkdir hello-go && cd hello-go
    go mod init dev.kj/hello
    git init -b main && git add -A && git commit -m "chore: scaffold"

    Create a minimal greeter.go skeleton so Karajan has something to extend:

    package hello
    

    // Greet returns the greeting for the given name.
    // Implementation pending — Karajan fills this in.
    func Greet(name string) string {
        return ""
    }

  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 Go toolchain.

  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 "Implement Greet(name string) in greeter.go so it returns \
    'Hello, <name>!'. If name is empty, return 'Hello, stranger!'. \
    Add a table-driven test in greeter_test.go covering both cases \
    plus a unicode name." \
      --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.
    • go test output 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
    go test ./...

    Expected output of go test ./...:

    ok      dev.kj/hello    0.002s

    With verbose mode you’ll see the table-driven cases:

    Terminal window
    go test -v ./...
    # === RUN   TestGreet
    # === RUN   TestGreet/named
    # === RUN   TestGreet/empty
    # === RUN   TestGreet/unicode
    # --- PASS: TestGreet (0.00s)

  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 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”

If you want a real CLI binary instead of a library:

Terminal window
go get github.com/spf13/cobra@latest

Then run with an explicit hint:

Terminal window
kj run "Wrap Greet(name) in a 'hello-go greet --name=<name>' command \
using Cobra. Add an integration test that runs the binary and \
captures stdout." \
  --methodology tdd \
  --max-iterations 5

The coder scaffolds cmd/root.go + cmd/greet.go and writes an exec.Command-based test. Build with go build -o hello-go ./....

Next steps

Section titled “Next steps”