Karajan v3.0.0: AI CLI를 오케스트라처럼 지휘하는 로컬 우선 멀티 에이전트 오케스트레이터

karajan-code@3.0.0이 npm에 출시되었습니다. nvm install 22.22.1 && npm i -g karajan-code@3를 실행하면 준비가 끝납니다.

내가 Karajan을 만든 이유

나는 AI와 함께 코딩하는 것을 좋아합니다. 하지만 AI를 일일이 돌보는 것(babysitting)은 좋아하지 않습니다.

만약 여러분이 Claude Code, Codex, 또는 Gemini를 사용해 본 적이 있다면, 다음과 같은 반복 루프를 알고 있을 것입니다:

원하는 것을 설명합니다.
모델이 작업하는 것을 지켜봅니다.
탄탄한 CLAUDE.md/AGENTS.md와 SKILLs가 갖춰져 있음에도 불구하고, 모델이 테스트를 건너뛰거나, API를 환각(hallucinating)하거나, 잘못된 레이어(layer)를 건드리는 것을 잡아냅니다.
작업을 중단시키고, 수정하고, 다시 실행합니다.
반복합니다.

일회성 변경 사항에는 괜찮습니다. 하지만 계획이 수립되어 있고, 실제 테스트와 실제 품질 게이트(quality gate)가 존재하는 실제 프로젝트로 확장하기에는 무리가 있습니다. 결국 여러분은 일시 중지하거나, 재시도하거나, 측정할 수 없는 비동기 루프(async loop) 사이에 끼어버린 인간이 되고 맙니다.

나는 다른 것을 원했습니다. 내가 원하는 것을 한 번만 설명하면, 일련의 AI 에이전트들(코더, 리뷰어, 테스터, SonarQube 게이트, 보안 감사관)이 스스로 루프를 실행하고 작업이 완료되면 나에게 알림을 주는 도구 말입니다. 재현 가능하게(Reproducibly). 로컬에서(Locally). 내가 이미 결제하고 있는 구독 서비스를 사용하여 말이죠.

그 도구가 바로 Karajan입니다.

이 이름은 단 하나의 악기도 연주하지 않았지만, 수십 명의 음악가들이 마치 하나처럼 소리를 낼 때까지 통일된 비전을 부여했던 지휘자 Herbert von Karajan에게서 따왔습니다. Karajan은 음악가들을 대체한 것이 아니라, 하나의 지도적인 의도 아래 그들을 조정했습니다. Karajan Code도 여러분의 AI 에이전트들에게 똑같이 수행합니다. 그들 중 누구도 주도권을 갖지 않으며, 모두가 중재하고 통합하는 단 하나의 지휘봉 아래로 수렴합니다.

Karajan의 실체

Karajan은 Node 22 기반의 vanilla JavaScript로 작성된 로컬 우선(local-first) 멀티 에이전트 오케스트레이터(multi-agent orchestrator)입니다.

사용자가 작업(마크다운 파일, 사용자 스토리, 또는 명령줄에서 직접)을 설명하면 Karajan은 그 작업에 대해 역할 기반 파이프라인(role-based pipeline)을 실행합니다:

task
  → triage      (복잡도를 분류하고 경로를 결정)
  → researcher  (기존 코드를 읽음)
...

각 역할은 CLI 에이전트입니다. 코더(coder)는 Claude가 될 수 있고, 리뷰어(reviewer)는 Codex가 될 수 있으며, 테스터(tester)는 Aider가 될 수 있습니다. Karajan은 /v1/messages를 호출하지 않습니다. 대신 claude -p, codex, gemini, aider, opencode를 자식 프로세스(child processes)로 생성하고 이들의 stdout/stderr를 읽습니다. 이 단 하나의 설계 결정이 두 가지를 가능하게 합니다:

API 비용 제로. 기존의 Pro / Plus / Max 구독 서비스가 작업을 수행합니다. 새로운 청구서가 발생하지 않습니다.
멀티 프로바이더 라우팅 (Multi-provider routing). 강력한 코더 + 엄격한 리뷰어 + 저렴한 분류(triage) 에이전트의 조합은 각 역할에 적합한 모델을 제공하며, 특정 모델이 할당량(quota)에 도달하면 자동으로 폴백(fallback)됩니다.

전체 시스템은 기본적으로 TDD(테스트 주도 개발) 우선 방식입니다. 코더는 코드와 함께 테스트를 작성하고, 테스터는 이를 실제로 실행하며, 리뷰어는 차이점(diff)을 확인합니다. 무언가 실패하면 리뷰어가 코더에게 피드백을 전달하고 루프가 반복됩니다. 이 과정은 maxIterations와 maxIterationMinutes에 의해 제한되어 통제 불능 상태로 빠지는 것을 방지합니다.

알아둘 만한 몇 가지 구성 요소가 더 있습니다:

MCP 서버. Karajan은 MCP 서버로 배포되므로, Claude Code, Cursor, Codex 또는 모든 MCP 호스트 내부에서 전체 파이프라인을 구동할 수 있습니다. kj_run, kj_plan, kj_code, kj_review, kj_audit, kj_rag_query를 통해 대화창을 벗어나지 않고도 전체 파이프라인에 접근할 수 있습니다.
Solomon, AI 판사. Brain 오케스트레이터가 실제 딜레마(보안 vs 마감 기한, 두 리뷰어의 의견 불일치 등)가 발생했을 때 자문을 구하는 독립적인 역할입니다. 모든 루프에서 작동하는 것이 아니라, Brain이 결정론적(deterministically)으로 결정할 수 없을 때만 작동합니다.
스토리 보드 (Story Board). http://localhost:4000에서 실행되는 작은 로컬 웹 대시보드로, 모든 사용자 스토리(user story), 모든 세션, 모든 계획, 모든 RAG 지표를 보여줍니다. 팀을 위한 단일 진실 공급원(Single source of truth) 역할을 합니다.
로컬 RAG. 각 프로젝트는 고유한 임베디드 코드 인덱스(~/.karajan/rag.db)를 가집니다. 파이프라인은 계획을 세우기 전에 실제 코드를 검색(retrieve)하므로, 아키텍트(architect)는 이미 존재하는 것을 확인할 수 있습니다. 6개의 임베딩 프로바이더(Ollama, OpenAI, Voyage, Cohere, Mistral, 로컬 ONNX)를 지원합니다. JS, TS, Python, Rust, Go, Java를 위한 Tree-sitter 기반 청커(chunkers)를 사용합니다.
kj audit. 결정론적 우선(deterministic-first) 감사 명령입니다: 데드 코드(dead code), 미사용 의존성(unused dependencies), 복잡도 증가(complexity growth), 보안 탐지 결과(OSV, Semgrep, SonarQube), 접근성 힌트(accessibility hints), 웹 성능 예산(Web Performance budgets), 그리고 Docker를 통해 실행되어 "현재 이 저장소가 얼마나 AI 친화적인가"에 대해 0-100 사이의 객관적인 점수를 부여하는 AI Harness Scorecard를 지원합니다. 프로젝트별 이력을 유지하며 스파크라인(sparkline) 트렌드를 그려냅니다.

v3.0.0이 가져오는 변화

v3.0.0은 기능 추가가 아닌 런타임 정렬(runtime alignment)입니다.

Node 20은 2026-04-30에 EOL(End of Life)에 도달합니다. 현재 Active LTS 라인은 Node 22입니다. Karajan의 의존성 중 세 가지가 독립적으로 Node 22 이상을 요구하는 메이저 버전으로 업데이트되었습니다: lint-staged 17, commander 15, 그리고 better-sqlite3 12.10입니다. 각 제약 사항을 개별적으로 패치하는 네 개의 시차를 둔 마이너 버전을 발행하는 대신, v3.0.0은 런타임 업데이트를 이에 의존하는 의존성 메이저 업데이트와 함께 묶어서 제공합니다.

마이그레이션은 단일 명령으로 완료됩니다:

nvm install 22.22.1 && nvm use 22.22.1
npm install -g karajan-code@3
kj doctor    # 런타임 + HW + 툴링 확인

이미 Node 22 이상을 사용 중이고 ~/.karajan/이 정상 작동한다면 변경 사항은 없습니다. 공개 API(public API) 변경 사항도 없습니다: kj run, kj plan, MCP 도구, 역할 템플릿(role templates), RAG, Story Board, audit, 텔레메트리(telemetry) 모두 그대로 유지됩니다. 기존 세션, 플랜, RAG 인덱스 및 audit 이력은 하위 호환성을 유지하므로 수동으로 마이그레이션할 것이 없습니다.

API 변경이 없는데 왜 메이저 업데이트인가요?

Semver(유의적 버전) 때문입니다. 최소 Node 버전을 올리는 것은 다운스트림 소비자에게 파괴적 변경(breaking change)입니다. Node 20에서 작동하던 설치가 이제는 완전히 실패하기 때문입니다. 이것만으로도 자격이 충분하며, 함께 업데이트된 세 가지 의존성의 메이저 버전 또한 각각의 Semver 기준에 따라 자격이 충분합니다. 단일 v3.0.0 버전을 출시함으로써 런타임 변경 사항을 네 번이 아닌 한 번만 노출하게 됩니다.

이번 릴리스에는 문서 개선 사항도 포함되었습니다. 설치 전에 무엇을 준비해야 하는지 알 수 있도록 README에 새로운 footprint(점유 공간) 및 하드웨어 요구 사항 섹션이 추가되었습니다. kj 자체는 npm에서 5.2 MB이며, ~/.karajan/은 약 40 MB를 차지합니다. Ollama (선택 사항, 6.55 GB), SonarQube (선택 사항, 1.47 GB), 그리고 qmd 캐시 (선택 사항, ~2.2 GB)가 용량이 큰 선택적 레이어들입니다. 세 가지 프로필이 있습니다: Minimal(최소) ~250 MB, Recommended(권장) ~8.5 GB, Full(전체) ~11 GB.

v1에서 v3까지: Karajan의 성장 과정

Karajan은 처음부터 멀티 에이전트 오케스트레이터(multi-agent orchestrator)로 시작된 것이 아닙니다. 시작은 단순한 쉘 스크립트(shell script)였습니다.

v0.x: 단일 스크립트. task → claude → diff → codex review → done. 두 개의 에이전트로 하드코딩되어 있었습니다. 재시도(retry), 비용 추적(cost tracking), SonarQube, 테스트 통합 기능이 없었습니다. 대략 화요일 오후에는 작동하곤 했습니다.
v1.0 ~ v1.1: 품질 게이트(Quality gates) 및 역할(roles). SonarQube가 코더(coder)와 리뷰어(reviewer) 사이의 필수 단계가 되었습니다. TDD(테스트 주도 개발) 정책에 따라 모든 코드 변경에는 테스트 변경이 수반되어야 했습니다. 이후 단일 스크립트는 역할 기반 파이프라인(role-based pipeline)으로 진화했습니다: BaseRole, BaseAgent, 12개의 설정 가능한 역할, 리뷰 프로필, Solomon 에스컬레이션(escalation), 예산 추적 기능이 도입되었습니다.
v1.2 ~ v1.3: MCP 서버 및 확장성. MCP 서버를 통해 MCP를 지원하는 모든 AI 에이전트 내부에서 Karajan을 호출할 수 있게 되었습니다. 플러그인 시스템을 통해 사용자는 포크(fork) 없이도 자신의 CLI를 Karajan 에이전트로 래핑(wrap)할 수 있게 되었습니다. Planning Game 통합을 통해 파이프라인을 프로젝트 관리와 연결했습니다. Git 자동화를 통해 자동 커밋(auto-commit), 자동 PR(auto-PR), 자동 리베이스(auto-rebase)로 루프를 완성했습니다.
v1.4 ~ v1.7: 회복 탄력성(Resilience). 지원되는 모든 CLI에 대한 속도 제한(Rate-limit) 감지 기능이 추가되었습니다. 기본 코더가 할당량(quota)에 도달했을 때의 자동 폴백(fallback) 기능이 도입되었습니다. 작업의 복잡도에 따라 모델 티어를 매핑하는 스마트 모델 선택 기능(단순 작업 → Haiku, 복잡한 작업 → Opus)이 추가되었습니다. 취약한 하드 타임아웃(hard timeout)을 대체하는 대화형 체크포인트(Interactive checkpoints)가 도입되었습니다. 프로세스 내 MCP 실행을 통해 서브프로세스의 SIGKILL이 작업 도중 에이전트를 중단시키는 문제를 해결했습니다.
v1.40 ~ v1.46: 주권(Sovereignty), OpenSkills, 병렬 스토리. 파이프라인이 호스트 AI의 오버라이드(override)에 맞서 자신의 결정을 방어하는 법을 배웠습니다 (파이프라인 주권 가드, pipeline sovereignty guard).

OpenSkills는 코더(coders), 리뷰어(reviewers), 아키텍트(architects)에게 도메인 지식(domain knowledge)을 제공했습니다. 병렬 사용자 스토리(Parallel user stories)는 git worktree에서 독립적인 스토리를 동시에 실행했습니다. 최초의 SEA 바이너리가 등장했습니다: Node가 설치되어 있지 않아도 실행되는 kj입니다.

v1.50 ~ v1.58: 텔레메트리(Telemetry), 도메인 지식, i18n, WebPerf. 드디어 무슨 일이 일어나고 있는지 측정하기 위한 텔레메트리(Telemetry, 옵트아웃 방식, 코드나 개인 데이터 미포함)가 도입되었습니다. 모든 역할에 비즈니스 컨텍스트를 주입하는 도메인 지식 파일(DOMAIN.md)이 추가되었습니다. i18n을 통해 파이프라인이 처음부터 끝까지 영어(EN) 또는 스페인어(ES)로 대화할 수 있게 되었습니다. Web Performance(웹 성능)가 일급 품질 게이트(first-class quality gate)로 도입되었습니다 (Joan Leon의 WebPerf Snippets에서 영감을 받은 Chrome DevTools MCP를 통한 Core Web Vitals 측정).
v2.0: Karajan Brain. 라우팅을 결정하고, 피드백을 풍부하게 하며, 직접적인 행동을 제안하고

시작하기

설치:

nvm install 22.22.1 && nvm use 22.22.1
npm install -g karajan-code@3

스모크 테스트 (Smoke test):

kj --version           # 3.0.0
kj doctor              # Node, 에이전트 (agents), Docker, SonarQube, RAG 등을 확인합니다...

프로젝트 초기화:

cd your-repo
kj init                # 스택 (stack) 자동 감지, 에이전트 제안, .karajan/ 스캐폴딩 (scaffolds)

태스크 실행:

kj run "Add a /healthz endpoint with a unit test that returns 200" \
  --coder claude --reviewer codex

또는 Claude Code / Cursor / 기타 MCP 호스트 내부에서 kj_run을 호출하기만 하면 됩니다.

스토리 보드 (Story Board) 열기:

kj board start         # http://localhost:4000

이것이 루프 (loop)입니다. 원하는 것을 설명하세요. 오케스트라가 연주하게 두세요.

찾을 수 있는 곳

npm: karajan-code
문서 (Docs): https://karajancode.com/docs
저장소 (Repo): github.com/manufosela/karajan-code
라이선스 (License): AGPL-3.0
저자 (Author): @manufosela, 공개적으로 구축되었습니다.

직접 사용해 보시고 놀라운 점(긍정적이든 부정적이든)이 있다면 알려주시기 바랍니다. 이슈 (issue)를 생성하거나, GitHub을 통해 연락하거나, 여기에 답글을 남겨주세요.