Metadata-Version: 2.4
Name: karajan-cli
Version: 0.1.0
Summary: An AI agent harness for software engineers. Built on opencode + LangGraph.
License-Expression: MIT
Keywords: ai,agents,langgraph,opencode,workflow,engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: langgraph>=0.2.0
Requires-Dist: litellm>=1.40.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"

# Karajan

**An AI agent harness for software engineers.**
Built on [opencode](https://opencode.ai) + [LangGraph](https://langchain-ai.github.io/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

```bash
pip install karajan
```

Or from source (development):

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

## Quick start

```bash
# 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

```bash
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)

```bash
# 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.

```bash
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](https://opencode.ai) (`npm install -g opencode`) — solo profile
- [Claude Code](https://claude.ai/code) — team profile
- Ollama (optional, for local models): https://ollama.com

---

## License

MIT
