Konductor

CLI orchestrator for a team of AI roles inside your project.

Set Konductor up once per repo, then hand it tasks. It reads your project, assembles the right roles (Product Owner, Tech Lead, Frontend, Backend, …), plans, and executes each task through Claude — logging every run and remembering decisions along the way.

konductor init                       # one-time setup (Claude suggests your team)
konductor -p "Add Google sign-in"    # run a task through the team
konductor                            # show project status

Contents

• Why
• Requirements
• Install
• Commands
• How it works
• Configuration
• Project layout
• Development
• Billing
• Roadmap
• License

Why

Most AI coding tools act as a single generalist. Konductor instead gives Claude a team: a small set of role cards (responsibilities + operating instructions) tailored to your product, plus persistent project memory. Every task is run through that context, so the model plans and acts like the right specialist rather than starting cold each time.

• Project-aware — infers product type, subprojects, and the smallest useful set of roles from your repository.
• Persistent — long-lived context and a per-run decision log live in .konductor/, version-controlled alongside your code.
• Autonomous — runs agentically in your working tree via the Claude Agent SDK, streaming progress to your terminal.
• Auditable — every run is saved as a JSONL log you can replay or inspect.

Requirements

• Bun ≥ 1.0 — runs the TypeScript directly, no build step.
• The Claude Code CLI, logged in. Konductor reuses that local session for auth, so no API key is needed for personal use.

Install

git clone <this-repo> konductor && cd konductor
bun install
bun link            # makes `konductor` available globally

During development you can run it without linking:

bun run dev -- -p "your task"

Commands

Command	Description
konductor init	One-time setup. Scans the repo and scaffolds .konductor/.
konductor -p "<task>"	Run a task through your AI team. Alias: --prompt.
konductor	Show project status, or launch init if the repo isn't set up.
konductor -v	Print the version. Alias: --version.
konductor --help	Show usage.

How it works

project context → roles → orchestration prompt → agent execution → run logs → memory

1. konductor init scans the repository, asks Claude to infer the product type, subprojects, and the smallest effective set of roles, then pre-fills a short wizard you confirm or edit. If Claude is unreachable it falls back to local heuristics. Setup is written to .konductor/ in your project.
2. konductor -p "…" loads the config, scans the current context, builds a single orchestration prompt from the role cards plus memory, and runs the task agentically via the Claude Agent SDK. Progress streams to your terminal; the full run is saved to runs/ and a summary is appended to memory/decisions.md.
3. konductor (bare) reports the detected project root and how to run a task, or starts init if no .konductor/ is found.

Important

During a run Konductor operates autonomously in your repository — it can read, edit, and execute. Run it on a clean working tree so you can review the diff afterwards.

Configuration

.konductor/project.yaml is plain YAML, validated on every run:

version: 1
name: My App
productType: saas          # startup | saas | internal-tool | mobile-app | library | other
subprojects:
  - name: web
    path: apps/web
    kind: web
roles:                     # product-owner | tech-lead | frontend | backend
  - product-owner          # mobile | designer | reviewer | growth
  - tech-lead
  - backend
  - reviewer
engine: claude             # only `claude` in v1
rules:
  - Use TypeScript strict
  - Conventional Commits

Field	Required	Notes
version	no	Schema version. Defaults to 1.
name	yes	Display name of the project.
productType	yes	One of the six product archetypes above.
subprojects	no	Buildable units (name, path, optional kind).
roles	yes	At least one role id from the catalog.
engine	no	Execution backend. Defaults to claude.
rules	no	Free-form constraints injected into every prompt.

Edit it directly or re-run konductor init to regenerate. Your memory/ files are preserved on re-init.

Project layout

What init writes into your repository:

.konductor/
  project.yaml        # name, product type, subprojects, roles, rules
  roles/              # one markdown role card per selected role
  memory/             # context.md (long-lived) + decisions.md (per-run log)
  runs/               # one JSONL log per task run

Konductor's own source (src/):

src/
  cli.ts              # command entry point (commander)
  commands/           # init, run, default (status) handlers
  config/             # zod schema, loader, path resolution
  context/            # repository scanner
  engine/             # Claude Agent SDK adapter + engine interface
  init/               # scaffolding and Claude-backed suggestions
  orchestrator/       # prompt assembly + run loop
  roles/              # role catalog and card generation
  logging/            # JSONL run logger
  memory/             # context + decisions store
  wizard/             # interactive init prompts
  util/               # shared helpers

Development

bun run dev -- -p "your task"   # run the CLI from source
bun run typecheck               # tsc --noEmit

The codebase is TypeScript run natively by Bun — there is no bundler or transpile step. Commits follow Conventional Commits.

Billing

On a Claude subscription, Agent SDK and claude -p usage draws from a separate monthly Agent SDK credit pool, distinct from your interactive Claude Code limits.

Roadmap

The v1 goal is a reliable single pipeline, not a swarm of agents. Next:

• Additional engine adapters (Codex, OpenAI, local).
• Real parallel subagents and review loops.
• A richer TUI and run history browser.

License

MIT