Skip to content
Karajan Code

How-To · Python

Python · Estimated time: ~12 min · Karajan iterations: 1–3

This walkthrough takes you from an empty directory to a merged feature on a small Python project (CLI / library / data script). 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

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 Python 3.10+ on PATH (python --version). On macOS we recommend pyenv; on Linux use the distro package; on Windows use the official installer with “Add to PATH” checked.

Walkthrough

Section titled “Walkthrough”

  1. Bootstrap the project.

    Terminal window
    mkdir hello-py && cd hello-py
    python -m venv .venv
    source .venv/bin/activate    # Windows: .venv\Scripts\activate
    pip install --upgrade pip
    pip install pytest
    git init -b main && git add -A && git commit -m "chore: scaffold"

    Create a minimal pyproject.toml so Karajan’s tester knows how to invoke pytest:

    [project]
    name = "hello-py"
    version = "0.0.1"
    requires-python = ">=3.10"
    

    [tool.pytest.ini_options]
    testpaths = ["tests"]

  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, and ports are all healthy. kj doctor also detects your Python version and registers it in the project profile.

  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)' function in src/hello.py that returns \
    'Hello, <name>!'. Add a pytest test in tests/test_hello.py that imports \
    the function and 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.
    • The pytest 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
    pytest

    Expected output of pytest:

    ============================= test session starts ==============================
    collected 1 item
    

    tests/test_hello.py .                                                    [100%]
    

    ============================== 1 passed in 0.02s ===============================

  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-function
    git add -A && git commit -m "feat: add greet(name) function"
    git push -u origin feat/greet-function
    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)' function in src/hello.py that returns 'Hello, <name>!'. Add a pytest test.",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

Next steps

Section titled “Next steps”