Skip to content
TypeScript
10.7 KB
Raw Blame
theseus — 모델 × 에이전트 × 하네스 비교, 그리고 trade-off 판단

theseus

내 과제로 모델 × 에이전트 × 하네스를 비교하고 — trade‑off 는 당신이 판단한다.

CI Pages node

🌐 English · 한국어 · 日本語 · 中文


무엇을 하나

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/ (아키텍처 · 레지스트리 · 트랜스크립트 스키마 · 시각화 · 브랜드 · 인수기준).