태스크를 분해하고 전문 에이전트(specialist agents)에게 위임하는 자기 개선형 멀티 에이전트 (multi-agent) AI 시스템입니다. Sprout는 재귀적 에이전트 아키텍처 (recursive agent architecture)를 기반으로 구축된 자율 코딩 어시스턴트이며, 여기서 모든 행동은 서브 에이전트 (subagent)로의 목표 지향적 위임입니다.

Sprout는 단순하지만 강력한 루프(loop)를 통해 작동합니다:

인지 (Perceive) → 회상 (Recall) → 계획 (Plan) → 실행 (Act) → 검증 (Verify) ─── 루프
│
└──→ 학습 (Learn) (비동기)

**루트 에이전트 (root agent)**는 사용자의 목표를 수신하여 이를 하위 목표(subgoals)로 분해하고, 각각을 전문가에게 위임합니다. 전문가(Specialists)는 그 자체로 오케스트레이터(orchestrators, 추가 위임 수행)가 될 수도 있고, 프리미티브(primitives)를 직접 실행하는 리프 워커(leaf workers)가 될 수도 있습니다. 이 시스템은 실수로부터 학습합니다. 실수, 실패, 비효율성을 감지하여 시간이 지남에 따라 에이전트 게놈 (agent genome)을 변이시키는 비동기 학습 파이프라인 (asynchronous learning pipeline)에 전달합니다.

끝까지 이어지는 에이전트 (Agents all the way down) — 모든 행동은 서브 에이전트 (subagent)로의 위임입니다. 루트(root)는 도구(tools)를 직접 실행하지 않습니다.

게놈 (Genome) — 에이전트 정의, 메모리, 라우팅 규칙 및 학습된 행동을 저장하는 git 기반 지식 베이스입니다. 모든 변이(mutation)는 완전한 감사 가능성(auditability)과 롤백(rollback)을 위해 커밋됩니다.

프리미티브 (Primitives) — 불변의 커널 연산입니다:
read_file, write_file, edit_file, apply_patch, exec, grep, glob, fetch. 오직 리프 에이전트 (leaf agents)만이 이를 실행합니다.

학습 신호 (Learn signals) — 실패, 타임아웃, 재시도 및 비효율성이 자동으로 감지됩니다. 패턴이 나타나면 (3회 이상의 반복된 실수, 2회 이상의 미해결 오류), 시스템은 향후 성능을 개선하기 위해 게놈 변이 (genome mutations)를 트리거합니다.

멀티 프로바이더 LLM (Multi-provider LLM) — 통합 어댑터 인터페이스를 통해 Anthropic (Claude), OpenAI (GPT/o-series), OpenAI Codex 및 Google (Gemini)을 일급으로 지원합니다.

root (최적의 모델 — 오케스트레이터)
├─ utility/reader (빠름 — 읽기 전용 파일 탐색)
├─ utility/editor (균형 잡힘 — 파일 편집 및 생성)
...

에이전트는 root/ 내의 마크다운(Markdown) 명세(specs)로 정의됩니다. 각 명세는 다음을 선언합니다:

필드 (Field)	설명 (Description)
name	에이전트 식별자 (Agent identifier)
description	에이전트의 역할 (상위 에이전트에게 표시됨)
model	LLM 계층 (LLM tier): best, balanced, 또는 fast
tools	이 에이전트가 사용할 수 있는 프리미티브 (primitives) 목록
agents	이 에이전트가 위임할 수 있는 하위 에이전트 (subagent) 경로 목록
max_turns	강제 중단 전 최대 계획 반복 횟수 (Maximum planning iterations)
max_depth	이 에이전트가 위임 트리(delegation tree)에서 나타날 수 있는 최대 깊이
can_spawn	에이전트가 하위 에이전트에게 위임할 수 있는지 여부
timeout	에이전트의 최대 실제 실행 시간 (Maximum wall-clock time)
can_learn	이 에이전트로부터의 학습 신호가 게놈 변이 (genome mutations)를 트리거하는지 여부
system_prompt	에이전트의 성격, 지침 및 제약 사항

Quartermaster는 Sprout가 무엇을 할 수 있는지 이해하고 이를 확장하도록 돕는 메타 에이전트 (meta-agent)입니다:

Oracle 모드 (Oracle mode)— "어떤 도구/에이전트가 존재하는가?" → 모든 역량을 인덱싱하고 종합된 결과를 반환합니다.
Planner 모드 (Planner mode)— "X를 어떻게 달성하는가?" → 사용 가능한 도구를 사용하여 구체적인 계획을 수립합니다.
Fabricator 모드 (Fabricator mode)— "Y를 위한 전문가를 구축하라" → 새로운 에이전트 YAML을 생성하고, 이를 게놈 (genome)에 기록하며, 역량 인덱스 (capability index)를 갱신합니다.

이는 Sprout가 런타임 (runtime) 중에 자체적인 에이전트 명단을 확장할 수 있음을 의미합니다.

에이전트들은 토픽 기반 메시징 (topic-based messaging)을 사용하는 WebSocket 발행/구독 (pub/sub) 버스를 통해 통신합니다:

session/{session_id}/agent/{handle_id}/{channel}

채널에는 inbox, events, ready가 포함됩니다. 에이전트는 별도의 프로세스로 생성(spawn)될 수 있어, 비차단 위임 (non-blocking delegations)을 위한 진정한 병렬 처리가 가능합니다.

커널 (kernel)은 불변의 토대(immutable foundation)로, Sprout에서 절대 변하지 않는 부분들입니다:

코어 루프 (Core loop)— 인지 (Perceive) → 회상 (Recall) → 계획 (Plan) → 행동 (Act) → 검증 (Verify)
프리미티브 (Primitives)— 8가지 내장 도구 작업
학습 프로세스 (Learn process)— 오류 감지 (Stumble detection) 및 게놈 변이 (genome mutation)
감사 로그 (Audit log)— 모든 세션에 대한 JSONL 이벤트 스트림
안전 제약 사항 (Safety constraints)— 경로 검증 (Path validation), 타임아웃 (timeouts), 깊이 제한 (depth limits)

Sprout는 세션 전반에 걸쳐 지속적인 메모리 (persistent memory)를 유지합니다:

Memories (메모리)— 시간 경과에 따라 신뢰도가 감소(30일 반감기)하는 키워드 태그 기반의 관찰 기록. 현재 작업과 관련이 있을 때 자동으로 호출됩니다. Routing rules (라우팅 규칙)— 특정 작업 패턴에 대해 어떤 에이전트에게 위임할지에 대해 학습된 휴리스틱 (heuristics). Metrics (메트리크)— 에이전트별 실수율 (stumble rates) 및 작업 횟수. 학습을 트리거할 시점을 결정하는 데 사용됩니다. Git history (Git 히스토리)— 모든 게놈 변이 (genome mutation)는 커밋되므로, 모든 변경 사항을 검사하거나 롤백 (rollback)할 수 있습니다.

• Bun 런타임 (v1.0+)
• TypeScript 5+
• 최소 하나 이상의 LLM 제공업체 자격 증명 (credential)

# 저장소 클론 (Clone the repository)
git clone <repo-url>
cd sprout
...

OpenAI Codex 제공업체 유형 (openai-codex)은 제공업체 설정에서 ChatGPT OAuth를 사용합니다. OPENAI_API_KEY를 사용하지 않으며, 붙여넣은 API 키도 허용하지 않습니다. 설정에서 OpenAI Codex 제공업체를 추가하거나 편집한 다음, 제공업체 설정의 로그인/로그아웃 액션을 사용하여 ChatGPT로 로그인하거나 로그아웃하세요.

Sprout는 추상적인 티어 (tiers)를 구체적인 모델에 매핑합니다:

티어 (Tier)	Anthropic	OpenAI	Google
best	claude-opus-4-6	gpt-4.1	gemini-2.5-pro
balanced	claude-sonnet-4-6	—	—
fast	claude-haiku	gpt-4.1-mini	gemini-2.0-flash

제공업체는 사용 가능한 제공업체 자격 증명 (credentials)에 따라 선택됩니다.

# 대화형 세션 시작 (Start an interactive session)
bun run src/host/cli.ts
# 또는 바이너리 이름 사용
...

이를 통해 다음과 같은 기능이 포함된 터미널 UI (terminal UI)가 열립니다:

• 도구 세부 정보를 접고 펼칠 수 있는 풍부한 대화 보기 (Rich conversation view)
• 컨텍스트 사용량, 턴 (turns), 토큰 (tokens) 및 모델을 보여주는 상태 표시줄 (status bar)
• Emacs 스타일 키 바인딩 (keybindings) (Ctrl+A/E, Ctrl+K/U 등)
• 명령 히스토리 (command history) (위/아래 화살표)
• 런타임 중 모델 전환 (model switching)

# 단일 목표 실행 후 종료 (Execute a single goal and exit)
bunx sprout --prompt "Add error handling to the login function in src/auth.ts"

# 이전 세션 목록 표시 (List previous sessions)
bunx sprout --resume
# 특정 세션 재개 (Resume a specific session)
...

# 게놈 내의 모든 에이전트 목록 표시 (List all agents in the genome)
bunx sprout --genome list
# 게놈 변이 히스토리 보기 (View genome mutation history)
...

Sprout는 터미널의 대안으로 브라우저 기반 UI를 포함하고 있습니다.

TUI와 웹 인터페이스를 모두 사용하여 시작

bunx sprout --web

Headless 모드 (웹 전용, 터미널 UI 없음)

...

또한 세션 중간에 /web 슬래시 명령어를 사용하여 웹 서버를 시작할 수 있으며 ( /web stop 으로 중지 가능),

개발 워크플로우 (Development workflow):

# 터미널 1: 고정된 포트에서 Sprout를 headless 모드로 실행
bunx sprout --web-only --port 7777
# 터미널 2: Hot reload 기능이 있는 Vite 개발 서버 실행
...

프로덕션용 웹 UI를 빌드하려면: bun run web:build 명령어를 사용하세요.

대화형 모드(Interactive mode) 사용 시:

명령어	설명
/help	사용 가능한 명령어 표시
/model	LLM 모델 전환
/compact	수동으로 컨텍스트 압축 (Context compaction) 트리거
/clear	대화 기록 삭제
/status	세션 상태 표시
/web	웹 서버 시작 (브라우저 열기)
/web stop	웹 서버 중지
/quit	세션 종료

Sprout는 독립형 MCP (Model Context Protocol) 클라이언트 CLI를 포함하고 있습니다:

# 설정된 MCP 서버 목록 나열
bun run root/agents/utility/agents/mcp/tools/mcp-cli.ts list-servers
# 서버의 도구(Tools) 목록 나열
...

MCP 서버는 mcp.json에 설정됩니다.

Sprout에게 프로젝트별 컨텍스트를 제공하려면 프로젝트 루트( .git 옆)에 AGENTS.md 파일을 배치하세요. Sprout는 현재 디렉토리에서 상위 디렉토리로 탐색하며 이 파일을 자동으로 찾아냅니다.

또한 다음과 같은 작업이 가능합니다:

• 프로젝트 간 공통 가이드를 위해 ~/.config/sprout/AGENTS.md에 전역 AGENTS.md 배치
• 디렉토리별 오버라이드(Override)를 위해 하위 디렉토리에 AGENTS.override.md 사용
• 조립된 프로젝트 문서의 용량이 32 KiB 예산 내에 유지되도록 관리

기본 게놈(Genome) 경로 우선순위:

--genome-path <path> (가장 높음)
SPROUT_GENOME_PATH
$XDG_DATA_HOME/sprout-genome
~/.local/share/sprout-genome (Fallback/대체)

다음과 같이 명시적으로 오버라이드할 수 있습니다:

bunx sprout --genome-path /path/to/genome

sprout/
├── root/ # 에이전트 트리 (Markdown 명세)
│ ├── root.md # 루트 오케스트레이터 (Root orchestrator)
...

# 클론(Clone)할 때마다 한 번씩 프로젝트 git hooks 설치
bun run hooks:install
# 타입 체크 (Type checking)
...

Sprout는 55개 이상의 테스트 파일로 구성된 포괄적인 테스트 스위트와 함께 **Bun의 네이티브 테스트 러너 (native test runner)**를 사용합니다:

# 모든 유닛 테스트 (unit tests) 실행
bun run test:unit
# 워치 모드 (watch mode)로 실행
...

테스트 패턴 (Testing patterns):

• 유닛 테스트 (Unit tests)는 미리 결정된 응답을 사용하여 LLM Client를 모킹 (mock) 합니다.
• 통합 테스트 (Integration tests)는 VCR (Video Cassette Recorder) 패턴을 사용합니다 — HTTP 응답을 한 번 기록하고 CI에서 재생합니다.
• 모든 파일 I/O 테스트는 격리된 임시 디렉토리 (mkdtemp)를 사용합니다.
• 에이전트 (Agent) 테스트는 이벤트 방출 (event emission), 위임 흐름 (delegation flows), 타임아웃 처리 (timeout handling) 및 라이프사이클 (lifecycle)을 검증합니다.

# 체크 + 타입 체크 (typecheck) + 유닛 테스트 실행
bun run precommit
# pre-push 체크를 수동으로 실행 (.githooks/pre-push와 동일한 게이트)
...

예를 들어, 다음과 같이 요청한다고 가정해 봅시다: "회원가입 양식에 입력 유효성 검사를 추가해줘"

• **루트 에이전트 (Root agent)**가 목표를 수신하고 계획을 세웁니다: "현재 코드를 이해한 다음, 이를 수정해야 한다."
• 루트가 리더 (reader)에게 위임합니다: "회원가입 양식 컴포넌트를 찾아 그 내용을 반환하라."
• 리더는 glob + read_file 프리미티브 (primitives)를 사용하여 코드를 반환합니다.
• 루트가 에디터 (editor)에게 위임합니다: "src/components/SignupForm.tsx에 이메일 형식 유효성 검사와 비밀번호 강도 체크를 추가하라."
• 에디터는 read_file → edit_file → read_file (검증) 과정을 거쳐 성공을 반환합니다.
• 루트가 커맨드 러너 (command-runner)에게 위임합니다: "아무것도 망가지지 않았는지 확인하기 위해 테스트 스위트를 실행하라."
• 커맨드 러너는 exec("bun test")를 사용하여 결과를 반환합니다.
• 만약 테스트가 실패하면, 루트는 **실패를 감지 (detects the stumble)**하고 에러 컨텍스트와 함께 에디터에게 다시 위임하며 반복합니다.
• 이 과정 전반에 걸쳐 **학습 신호 (learn signals)**가 비동기적으로 방출됩니다. 만약 에디터가 특정 패턴에서 반복적으로 실패하면, 프롬프트를 개선하거나 메모리를 추가하기 위해 게놈 (genome)이 변이 (mutated)됩니다.

추적된 2,201개 세션 결과:

지표 (Metric)	값 (Value)
총 도구 사용 횟수 (Total tool uses)	77,220
...
컴포넌트 (Component)	기술 (Technology)
---	---
런타임 (Runtime)	Bun
...
0.1.0