지능형 에이전트 오케스트레이터. 단순히 병렬적인 에이전트가 아니라, 완전한 자체 개선 개발 루프입니다.
棟梁 (toryo)은 일본어로 '명장' 또는 '현장 감독관'을 의미합니다. toryo는 전체 건설 인력을 관리하고, 전문가를 적절한 작업에 배치하며, 구조물에 남기기 전에 모든 부분이 품질 기준을 충족하는지 확인하는 사람입니다.
Toryo는 여러 AI 코딩 에이전트(Claude Code, Aider, Gemini CLI, Codex, Ollama)를 스펙 기반 워크플로우, 신뢰 기반 위임, 품질 게이팅(quality ratcheting), 그리고 실시간 대시보드를 통해 연결합니다.
npx @jweigel/toryo init # 설정 파일 및 작업 스펙 생성
npx @jweigel/toryo run # 오케스트레이션 시작
즉시 사용해 보기: npx @jweigel/toryo demo
(AI 도구 필요 없음)
문서화 (Documentation) | 시작하기 (Getting Started) | 설정 (Configuration) | 버스 패턴 (Bus Pattern) | 기여 (Contributing)
AI 에이전트를 병렬로 실행하는 것은 쉽습니다. 이들을 지능적으로 함께 작동하게 만드는 것이 어렵습니다.
| 문제점 | Toryo의 해결 방법 |
|---|
| 에이전트가 낮은 품질의 결과물을 생성함 | 품질 게이팅(Quality ratcheting) — QA를 통과한 git-commit 결과만 커밋됩니다 (점수 ≥ 임계값). 나머지는 자동 롤백됩니다. |
| ... | |
| Toryo는 사이클을 실행합니다. 각 사이클은 4개의 단계로 구성되어 있습니다: | |
📋 계획 (Plan) → 🔍 연구 (Research) → ⚡ 실행 (Execute) → ✅ 검토 (Review)
계획 (Plan) — 에이전트가 작업 스펙을 읽고 간략하게 작성합니다.
연구 (Research) — 에이전트가 컨텍스트와 정보를 수집합니다.
실행 (Execute) — 에이전트가 코드를 작성하거나, 테스트를 하거나, 문서를 만듭니다.
검토 (Review) — 에이전트가 결과물에 점수(1-10)를 매기고 피드백을 제공합니다.
검토 후:
점수 ≥ 임계값 → git commit (유지)
점수 < 임계값 → git revert → Ralph Loop 재시도 → 유지 또는 폐기
인프라 실패 → 충돌로 기록하고, 점수 매기기를 건너뜁니다.
이것은 Karpathy의 autoresearch에서 가져온 **게이팅 패턴(ratcheting pattern)**입니다: 오직 전진적인 진보만 커밋됩니다. 나쁜 결과는 자동으로 롤백됩니다.
npx @jweigel/toryo init
생성되는 항목:
toryo.config.json
— 에이전트 정의, 품질 게이트, 위임 규칙
specs/
— 작업 스펙 (YAML 프론트매터 + 마크다운)
toryo.config.json 편집하기:
:
agents:
"researcher": {
...
specs/에 마크다운 파일 생성하기
:
---
name: 단위 테스트 작성 (Write Unit Tests)
difficulty: 0.5
...
npx @jweigel/toryo run # 무기한 실행
npx @jweigel/toryo run -n 10 # 10 사이클 실행
npx @jweigel/toryo run --dry-run # 실행 없이 미리보기
...
Toryo는 7가지 도구에 대한 최상급 어댑터와 다른 모든 것을 위한 범용 어댑터를 제공합니다:
| 어댑터 | 도구 | 작동 방식 |
|---|
claude-code | Claude Code | claude --print (비대화형) |
aider | Aider | aider --message |
gemini-cli | Gemini CLI | gemini --prompt |
ollama | Ollama | 직접 HTTP API (CLI 불필요) |
codex | Codex CLI | codex exec |
cursor | Cursor CLI | agent -p --force (CURSOR_API_KEY 필요) |
cline | Cline CLI | cline --yolo |
custom | 모든 CLI 도구 | 설정 가능한 명령어 + 인자 |
혼합하여 사용하세요 — 연구에는 Claude Code를, 로컬 코드 생성에는 Ollama를, 검토에는 Gemini를 사용합니다:
{
"agents": {
"researcher": { "adapter": "claude-code" },
...
에이전트는 감독(supervised) 자율성으로 시작하며 일관되게 높은 점수를 얻으면서 신뢰를 쌓습니다:
| 레벨 | 신뢰도 | 행동 |
|---|
| 🔴 감독 (Supervised) | < 0.6 | 엄격한 지침 준수, 정확한 형식 |
| ... | | |
| 신뢰도는 이동 평균 점수를 기반으로 계산됩니다. 일관되게 10점 만점에 8점 이상을 받는 에이전트는 자율 모드(autonomous mode)를 얻습니다. 임계값 이하로 떨어지는 에이전트는 감독 모드로 강등됩니다. | | |
Trust = min(avg_score / 10, 1.0)
작업이 들어오면 Toryo는 작업의 프로필(연구 중심? 코드 중심? 검토?)과 각 에이전트의 강점 및 현재 신뢰 수준을 기반으로 최적의 에이전트를 매칭합니다.
Karpathy의 자동 연구 패턴에서 영감을 받았습니다:
Score ≥ 6.0 → git commit ✓
Score < 6.0 → git revert → Ralph Loop 재시도
↓
...
모든 결과는 results.tsv에 기록됩니다.
(Karpathy 형식):
timestamp cycle task agent score status description
2026-03-19T10:15:00Z 42 write-tests coder 8.2 keep QA approved: PASS
2026-03-19T10:45:00Z 43 refactor coder 4.1 discard QA rejected: FAIL
...
toryo.config.json에서 임계값(thresholds)을 설정하세요.
:
{
"ratchet": {
"threshold": 6.0,
...
에이전트 상태, 결과 및 실시간 이벤트를 보여주는 웹 대시보드:
npx toryo dashboard
# http://localhost:3456 열림
주요 기능:
- 신뢰 점수(trust scores)와 자율성 수준(autonomy levels)이 표시되는 에이전트 상태 카드
- 정렬 가능한 컬럼과 색상 코드가 적용된 상태의 결과 테이블
- WebSocket을 통한 실시간 이벤트 피드
- 메트릭 요약 (사이클 수, 성공률, 평균 점수)
돌파구(breakthroughs), 실패 및 주기적인 상태에 대한 알림 받기:
{
"notifications": {
"provider": "ntfy",
...
지원되는 제공업체(Supported providers): ntfy, slack, discord, webhook
Toryo는 조합 가능한 TypeScript 모노레포입니다. 전체 오케스트레이터(orchestrator)를 사용하거나 개별 구성 요소를 사용할 수 있습니다:
@toryo/core — 엔진: orchestrator, delegation, ratchet, metrics, extraction
@toryo/adapters — 에이전트 어댑터: claude-code, aider, gemini-cli, ollama, custom
toryo — CLI: init, run, status, dashboard
각 하위 시스템은 독립적인 팩토리 함수(factory function)입니다:
import { createDelegation, createRatchet, createMetrics } from '@toryo/core';
// delegation 시스템만 사용
const delegation = createDelegation({ initialTrust: 0.5 });
...
대부분의 다중 에이전트 도구는 한 가지 일을 합니다 — 에이전트를 병렬로 실행하거나(Composio, AMUX) 사양(specs)을 정의합니다(Spec Kit). Toryo는 완전 루프: spec → delegate → execute → review → ratchet → improve입니다.
| 기능 | Toryo | Composio | AMUX | CrewAI | Spec Kit |
|---|
| 다중 에이전트 오케스트레이션 | ✅ | ✅ | ✅ | ✅ | ❌ |
| ... | | | | | |
| 필드 | 타입 | 기본값 | 설명 |
|---|
name | string | — | 프로젝트 이름 |
agents | Record | — | 에이전트 정의 (어댑터, 모델, 강점, 타임아웃) |
tasks | string | TaskSpec[] | — |
ratchet.threshold | number | 6.0 | 유지할 최소 QA 점수 |
ratchet.maxRetries | number | 1 | Ralph Loop 최대 재시도 횟수 |
ratchet.gitStrategy | string | "commit-revert" | "commit-revert", "branch-per-task", 또는 "none" |
delegation.initialTrust | number | 0.5 | 새로운 에이전트의 시작 신뢰도 |
delegation.scoreWindow | number | 50 | 점수 평균을 위한 이동 창 크기 |
outputDir | string | ".toryo" | 결과를 저장할 위치, 메트릭, 아티팩트 |
notifications.provider | string | "none" | "ntfy", "slack", "discord", "webhook", "none" |
MIT
Built on patterns from:
- Karpathy의 autoresearch — ratcheting, results.tsv, NEVER STOP
- Ralph Loop — verify-then-retry 패턴
- Intelligent AI Delegation — 신뢰도 점수화, 역량 매칭
Git을 사용하는 실행은 깨끗한 리포지토리 루트와 무시된 런타임 outputDir (기본값 .toryo/) 또는 리포지토리 외부의 출력 디렉토리가 필요합니다. 소스 변경 사항은 QA 전에 체크포인트됩니다. 거부된 시도는 검증된 체크포인트만 취소하고 새로운 revert 커밋을 생성하며, 이전에 승인된 작업이 포함된 태스크 브랜치를 하드 리셋하거나 삭제하지 않습니다. 체크포인트 실패 및 예상치 못한 변경 사항은 검사를 위해 실행을 중단합니다. 코딩 에이전트를 중요한 체크아웃에서 실행하기 전에 Git ratchet 안전성 및 복구 절차를 확인하십시오.
최종 단계는 정확히 하나의 JSON 객체(단일 전체 json 코드 펜스도 허용됨)를 반환해야 합니다. 레거시 형식인 Score: X/10 산문은 거부됩니다. 사용자 지정 리뷰어 프롬프트는 다음 형태를 사용해야 합니다:
{
"score": 8,
"verdict": "pass",
...
}
리뷰 프롬프트에 제공된 정확한 증거 ID를 사용하십시오. 점수는 0부터 10까지의 유한 숫자여야 합니다. 판정(Verdict)은 pass, fail, 또는 needs_revision 중 하나입니다.
점수는 설정된 임계값(threshold)과 일치해야 합니다. 누락되거나, 중복되거나, 추가되거나, 충돌하거나, 형식이 잘못된 필드는 닫힘 실패(fail closed) 처리됩니다.
모든 패치와 필수 확인 사항은 참조되어야 합니다. 필수 확인 사항이 실패하면 검토자가 통과 점수를 부여하더라도 수락되지 않습니다. 유효하지 않은 검토는 점수 0을 받고, 실행 가능한 유효성 오류가 포함된 일반적인 거부/재시도 흐름으로 진입합니다.
신뢰할 수 있는 설정에서 결정론적 확인 사항을 구성하세요:
ratchet:
threshold: 6
maxRetries: 1
...
확인 사항은 각 소스 체크포인트(source checkpoint) 이후와 검토 전에, 재시도를 포함하여 실행 가능하고 인자 배열을 사용하며 셸 없이 실행됩니다. 각 확인 사항에는 기본 60초 시간 초과 및 256 KiB 출력 제한이 있으며, 시간 초과, 누락된 실행 파일, 0이 아닌 종료 코드(nonzero exits), 출력 오버플로우는 게이트를 실패시킵니다.
확인 사항은 추론되지 않습니다. 생략된 목록은 모델 검토만 제공합니다. 자동 수락에 의존하기 전에 프로젝트별 확인 사항을 선택하세요. 확인 명령과 해당 명령이 호출하는 프로그램은 신뢰할 수 있는 로컬 코드이며 샌드박스 처리되지 않습니다. Windows에서는 셸 전용의 .cmd 실행에 의존하기보다는 실행 파일 진입점(예: node와 npm CLI 경로)을 사용하세요.
Git 검토 증거에는 정확한 베이스/체크포인트 커밋 ID와 diff가 SHA-256 증거 ID와 함께 포함됩니다. 1 MiB보다 큰 diff는 증거를 조용히 누락하는 대신 검토를 중단시킵니다.
Git 체크포인트(gitStrategy: none 또는 비(非)Git 작업)가 없는 경우, 캡처된 아티팩트는 워커 출력이며 커밋 ID는 null입니다. 이 모드는 소스 변경 사항을 검증하지 않습니다.
원시 워커/파일/명령어 텍스트는 신뢰할 수 없는 컨텍스트로 표시됩니다. 검토자는 체크아웃을 수정해서는 안 됩니다. Git ratchet은 변경된 체크포인트를 수락하기를 거부합니다.
각 시도는 outputDir 아래에 reviews/cycle-<number>-attempt-<number>-<uuid>.json으로 작성됩니다.
, 여기에는 캡처된 증거(captured evidence), 원본 리뷰어 응답(raw reviewer response), 구문 분석 결과(parsed result) 또는 유효성 검사 오류(validation error)가 포함됩니다. 반환되는 사이클 결과(cycle results) 역시 모든 리뷰를 유지합니다. 고유한 생성과 고유 접미사(unique suffix)는 사이클 번호가 반복될 때 기록을 보존합니다. 오케스트레이터(orchestrator)가 생성될 때 구성(configuration)이 복사됩니다. 호출자(caller)의 구성 변경 사항은 새로운 오케스트레이터에만 적용됩니다. 이러한 로컬 기록에는 소스 및 명령어 출력(source and command output)을 포함할 수 있으므로, 런타임 디렉토리(runtime directory)는 무시(ignored)하십시오. 비교 참조(Comparison references)와 구조화된 출력(structured output)은 감사 가능성(auditability)을 향상시키지만, 모델이 증거를 검사했음을 증명하거나 프롬프트 주입 방지(prompt-injection containment)를 제공하지는 않습니다. 회귀 테스트(regression tests)에는 공급자 호출(provider calls)이 필요하지 않습니다.