무엇을 하나
theseus 는 같은 과제 묶음을 모델(L0) × 에이전트(L1) × 하네스(L2) 조합마다 돌려, 각 조합의 정확도 · 비용 · 시간 · 툴콜 · 서브에이전트 호출 흐름을 나란히 보여준다. 그래서 흐름을 이해하고 당신에게 맞는 trade‑off 를 직접 고른다. 리더보드가 아니며, 기본적으로 단일 점수를 만들지 않는다. 대신 관점별 최적과 비용/정확도 파레토 경계를 표시한다.
flowchart LR
S(["<b>선택</b><br/>모델 × 에이전트 × 하네스"]):::pick
S --> SUB["<b>subset</b><br/>결정적 · seed"]:::step
SUB --> J["<b>잡 실행</b><br/>조합 × 과제 · fail-soft"]:::step
J --> RM["<b>결과 + 메트릭</b><br/>정확도 · 비용 · 시간 · 흐름"]:::step
RM --> V(["<b>시각화</b><br/>report · graph · TUI · view"]):::out
V -. "선택을 다듬어 다시 실행" .-> S
classDef pick fill:#cdd2d8,stroke:#0a0b0d,color:#0a0b0d;
classDef step fill:#15171b,stroke:#8b929b,color:#eef0f2;
classDef out fill:#1d2b33,stroke:#cdd2d8,color:#eef0f2;
매 실행 산출물: 구조화 데이터(results.jsonl + 선택 theseus.sqlite), 자기완결형(self‑contained)
report.html(외부 JS/CDN 0), 서브에이전트 흐름 그래프 graph.html.
이름 — 배, 그리고 판단
theseus 는 *테세우스의 배*다. 널빤지를 하나씩 갈아 끼워도 배는 여전히 그 배다. 당신의 워크플로가 배이고, 모델·에이전트·하네스가 갈아끼우는 널빤지다. theseus 는 어떤 널빤지가 항해를 실제로 바꾸는지 보여준다.
그리고 그 목적은 판단(judgment) 이다. 승자를 정해 주지 않고, 근거(정확도·비용·시간·흐름)를 건네 당신이 trade‑off 를 저울질해 스스로 판정하게 한다. 이 정신은 정의와 판단의 화신 디케(Δίκη, Díkē) 에서 왔다 — theseus 는 도구이고, 판단은 당신의 몫이다.
라이브 데모 갤러리
자기완결형 예시 리포트 + 흐름 그래프. main 에 푸시될 때마다 CI 가 재생성한다.
- 호스팅: https://olympusresearch.github.io/theseus/ (메인테이너가 Pages 를 켠 뒤 — 아래 참고)
- 로컬에서 열기 (네트워크 불필요):
npm run build:site # ./site 생성 (index.html + report.html + graph.html) open site/index.html # macOS · Linux: xdg-open · Windows: start - 내 실행 결과에서 바로:
# run 을 기록하고 그 리포트를 브라우저로 열기 theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view open # run 을 기록하고 모든 run 을 http://localhost:7777 에 서빙 theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view serve --port 7777 - 기록된 모든 트레이스 보기 (새 실행 없이 파이프라인 전체 이력):
theseus view --open # 기록된 모든 run 을 localhost 에 서빙하고 갤러리 열기
호스팅 페이지 켜기: 저장소 Settings → Pages → Source: GitHub Actions (
Pages워크플로가 나머지를 처리).
설치
pnpm install # 또는 npm install
pnpm build # → dist/cli.js
npm link # `theseus` 노출 (또는: node dist/cli.js …)
Node ≥ 20, ESM. better-sqlite3·ink·react 는 선택 의존성 — 네이티브 빌드/TUI 의존성이 없어도
theseus 는 우아하게 폴백한다(JSONL 이 1차 소스, TUI 는 표로 폴백).
빠른 시작 (오프라인·결정적)
theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
--harness none,omc,omo,ponytail --bench subagent --tasks 4 --runner mock -L kr
매트릭스
L0 모델
- claude 계열 —
opus4.8 / 4.7 / 4.6,sonnet4.6 / 4.5,haiku4.5,fable5 - gpt 계열 —
gpt5-codex(계정 기본),gpt5.5,gpt5.1-codex - open 계열 (OpenRouter) —
qwen3-coder,qwen3-coder-free(무료 예산),glm4.6,kimi-k2,deepseek-v3.2… 멀티모델 에이전트가openrouter/<vendor>/<model>로 전달.src/config.ts에 OpenRouter id 를 추가하면 늘어나며,:free모델은 $0 청구.
L1 에이전트
| 에이전트 | 바이너리 | 모델 계열 | 하네스 |
|---|---|---|---|
cc |
claude | claude | none, superpowers, omc, ecc, ponytail, mattpocock |
codex |
codex | gpt | none, superpowers, omx, lazycodex, omo, ponytail |
opencode |
opencode | claude + gpt | none, omo, ponytail, mattpocock |
openclaw |
openclaw | claude + gpt | none, ponytail |
hermes |
hermes | claude + gpt | none, ponytail |
opencode/openclaw/hermes 는 모델 불문 — 어떤 family 든 받아 theseus 가 provider/id 형식으로 넘긴다:
anthropic/…, openai/…, 또는 openrouter/<vendor>/<model>(예: 무료 Qwen). default 은 생략.
(cc 는 claude 전용, codex 는 gpt 전용.)
L2 하네스
| 하네스 | 유형 | 에이전트 |
|---|---|---|
none |
기준선 | 전체 |
superpowers |
공용 | cc, codex |
omc / ecc |
오케스트레이션 | cc |
omx / lazycodex |
오케스트레이션 | codex |
omo (oh‑my‑openagent) |
오케스트레이션 | opencode, codex |
ponytail |
미니멀리즘 룰팩 | 전체 |
mattpocock |
스킬팩 | cc, codex, opencode |
비호환 조합은 사유와 함께 제외된다(조용히 버리지 않음).
인터랙티브 세션
인자 없이 theseus 를 치면 세션이 열린다 — claude/codex 처럼. 목표를 자유롭게 입력하고,
기능마다 하나로 통일된 슬래시 명령으로 설정한 뒤 /run:
$ theseus
theseus [1m×1a×1h] ▸ cc 와 opencode 를 플레이키 버그로 비교
theseus [1m×1a×1h] ▸ /agents cc,opencode
theseus [2m×2a×1h] ▸ /models opus4.8,gpt5.5
theseus [2m×2a×1h] ▸ /run # → 결정 표 + report.html
theseus [2m×2a×1h] ▸ /view # → 기록된 모든 트레이스를 localhost 에 서빙
theseus [2m×2a×1h] ▸ /exit
| 명령 | 설명 |
|---|---|
자유 입력 · /goal <text> |
달성하려는 목표 — 자유 입력이 누적되고, run meta 에 기록되어 리포트에 표시 |
/models /agents /harness /bench |
L0×L1×L2 — 인자 없으면 목록, 있으면 선택 |
/runs /tasks /seed /runner /judge /score /lang |
스윕 파라미터 |
/run · /view [open] · /config /clear /help /exit |
실행 · 시각화 · 점검/리셋/도움말/종료 |
명시적으로는 theseus session(별칭: chat, repl). 같은 동작을 스크립트용 일회성 플래그로도 쓸 수 있다(아래).
명령어
theseus # 인터랙티브 세션(슬래시 명령)
theseus session | chat | repl # 동일(명시적)
theseus [compare] --model … --agent … --harness … # 기본 명령
theseus verify --model … --agent … --harness … # 조합별 서브에이전트 콜 포착 점검
theseus results [--run <id>] # 기록된 run 보기
theseus view [--open] [--port 7777] # 기록된 모든 트레이스를 서빙·시각화
theseus tui [--out runs] [--open] [--rich] # 인터랙티브 ink UI (표 폴백)
theseus install <cc|codex|opencode|openclaw|hermes|tb|<harness>|all>
theseus install --check # 상태표
theseus doctor # 실행 환경 자가진단
시각화 모드 — --view
| 모드 | 동작 |
|---|---|
inline (기본) |
자기완결형 report.html + graph.html 작성, 경로 출력 |
open |
위 + 브라우저로 리포트 열기 |
serve |
localhost 서버(--port, 기본 7777)에 모든 run 라이브 인덱스 |
term |
막대 차트(정확도/토큰/비용/서브에이전트) + ANSI 흐름 트리 를 터미널에 — 브라우저 불필요 |
주요 플래그
--bench(기본 terminal-bench-v2) · --tasks(20) · --runs(1) · --seed · --runner
(auto|mock|cc|codex|opencode|openclaw|hermes|tb) · --concurrency(4) · --timeout(600) · --out(runs)
· --goal · --judge(none|heuristic|cc) · --score · --balanced · --dry-run · --yes/-y · --view
· --port · --no-logo · --language/-L(기본 kr; en|ja|zh).
벤치
- terminal-bench-v2 — 외부 Terminal‑Bench(Docker; 위임 실행).
tb가 없으면 mock 폴백. - local — 내장 happy‑path 과제(파일 검증, Docker 불필요).
- subagent — 내장 고난도 과제(
subagent-101…106); 검증기가 입력 fixture 에서 답을 재계산 (하드코딩 golden 없음 → drift 없음). 각 과제에 에이전트 불문 위임 힌트 1문장 포함.
서브에이전트 흐름 포착 점검
theseus verify 는 위임 유도 과제로 각 유효 조합을 돌려, 서브에이전트 콜이 실제로 잡히는지 표로 보고한다.
트리형 조합(cc + 오케스트레이션, opencode + omo)은 fan‑out 이 필요하고, 단일 루프(codex·none·hermes)는
flat (expected) 로 표시된다. 기본은 오프라인 mock, real 러너는 --yes 필요.
불변식 (PRD §20)
정렬 기본키 subagentCount → totalTokens → wallTimeMs · 단일 점수 없음(관점별 + 파레토) ·
결정성(sha256 subset, Math.random 금지) · fail‑soft(조용한 드롭 없음, success ≠ resolved) ·
null = 미수집 · 러너 비재구현(mock 폴백 + 배너) · 자기완결형 HTML · 하네스 per‑run(전역 오염 없음) ·
recompute‑in‑verify · i18n.
개발
pnpm typecheck && pnpm lint && pnpm test && pnpm build
자세한 내용은 docs/ (아키텍처 · 레지스트리 · 트랜스크립트 스키마 · 시각화 · 브랜드 · 인수기준).