karajan-cli 0.1.0

An AI agent harness for software engineers. Built on opencode + LangGraph.

Karajan

An AI agent harness for software engineers. Built on opencode + LangGraph.

Named after Herbert von Karajan — the conductor who coordinates every musician without playing a single instrument himself.

Research → Architect → [YOU] → PRD → [YOU] → Dev → Reviewer → QA ⟲ → [YOU] → Done

---

Install

pip install karajan

Or from source (development):

git clone https://github.com/TU_USER/karajan
cd karajan
pip install -e .

Quick start

# 1. Go to your project
cd ~/projects/my-app

# 2. Initialize karajan
karajan init --profile solo   # or: --profile team

# 3. Fill in .agent/CONTEXT.md with your project details
# 4. Copy .env.karajan.example to .env and add your API keys

# 5. Run a workflow
karajan task QR-42

---

Commands

karajan init [--profile solo|team]   # Initialize in current project
karajan task <ticket>                # Run full workflow
karajan status [ticket]              # Show active workflows
karajan models [--provider X]        # List available models
karajan profiles                     # List profiles and their defaults
karajan config --show                # Show current project config
karajan version                      # Show version

Model switching (per run)

# Use profile defaults
karajan task QR-42

# Override reasoning model (Research, Architect, PRD, Reviewer)
karajan task QR-42 --model anthropic/claude-sonnet-4-20250514

# Override dev model (what opencode uses internally)
karajan task QR-42 --dev-model ollama/qwen2.5-coder:14b

# Override all three independently
karajan task QR-42 \
  --model google/gemini-2.0-flash \
  --dev-model ollama/qwen2.5-coder:14b \
  --qa-model ollama/qwen2.5:7b

# Resume interrupted workflow
karajan task QR-42 --from-stage dev

---

Profiles

Profiles live in karajan/profiles/ and ship with the package. No separate repos needed — everything in one place.

karajan profiles   # see all profiles and their defaults

	solo	team
Use case	Personal side-projects	Company engineering team
Tracker	GitHub Issues + Projects	Jira
Dev CLI	opencode	Claude Code
Reasoning model	Gemini Flash	Gemini Flash
Dev model	Qwen2.5-Coder 14B (local)	Claude Sonnet
QA model	Qwen2.5 7B (local)	Claude Haiku
Observability	Local logs	Langfuse

---

Workflow

karajan task QR-42
  → Fetches ticket (GitHub Issues or Jira)
  → Research agent    — understands context and risks
  → Architect agent   — designs technical plan
  → [YOU review plan]                            ← HITL #1
  → PRD agent         — documents the feature
  → [YOU review PRD]                             ← HITL #2
  → Dev agent         — opencode/Claude Code implements
  → Reviewer agent    — code review
  → QA agent          — validates, auto-retries Dev if fails (max 2x)
  → PR opened in GitHub
  → [YOU review PR]                              ← HITL #3
  → Done

---

What karajan init creates

your-project/
  .agent/
    CONTEXT.md       ← what this project is
    STACK.md         ← technologies and versions
    DECISIONS.md     ← architecture decisions (ADRs)
    CONSTRAINTS.md   ← what agents can't touch
    TASKS.md         ← current work state
    AGENTS.md        ← agent instructions
  .agents/
    architect.md     ← opencode architect agent definition
    researcher.md    ← opencode research agent definition
    reviewer.md      ← opencode reviewer agent definition
    qa.md            ← opencode QA agent definition
  .karajan/
    config.toml      ← project-level config (profile, model overrides)
  .env.karajan.example

---

Structure

karajan/
  karajan/
    cli.py              ← entry point (karajan command)
    config.py           ← config loader with full hierarchy
    graph.py            ← LangGraph orchestrator
    profiles/
      solo.toml         ← solo profile defaults
      team.toml         ← team profile defaults
    nodes/
      research.py       ← Research node
      architect.py      ← Architect node
      prd.py            ← PRD node
      dev.py            ← Dev node (opencode / Claude Code)
      reviewer.py       ← Reviewer node
      qa.py             ← QA node
      hitl.py           ← Human-in-the-loop node
    agents/
      architect.md      ← opencode agent definition
      researcher.md     ← opencode agent definition
      reviewer.md       ← opencode agent definition
      qa.md             ← opencode agent definition
    commands/
      init.py           ← karajan init
      task.py           ← karajan task
      status.py         ← karajan status
      models.py         ← karajan models
      config.py         ← karajan config
    scripts/
      tracker.py        ← GitHub Issues + Jira unified
      github.py         ← PR creation
  pyproject.toml        ← pip install config
  README.md

---

Config hierarchy

CLI flags (--model, --dev-model, --profile)
  > environment variables (KARAJAN_MODEL_*, GEMINI_API_KEY, etc.)
    > .karajan/config.toml (per project)
      > karajan/profiles/<profile>.toml (package defaults)

---

Requirements

• Python 3.11+
• opencode (npm install -g opencode) — solo profile
• Claude Code — team profile
• Ollama (optional, for local models): https://ollama.com

---

License

MIT