TypeScript
Contributing to theseus
Thanks for helping compare the planks. A few ground rules keep the ship afloat.
Setup
npm install # Node ≥ 20; better-sqlite3/ink/react are optional deps
npm run typecheck && npm run lint && npm test && npm run build
Everything runs offline: the deterministic mock runner exercises the full pipeline
(theseus --runner mock …), so no API keys or paid calls are needed for development.
Invariants (do not break)
These are asserted by tests and documented in the PRD (docs/):
- Sort key
subagentCount → totalTokens → wallTimeMs— the canonical, reproducible row order. - No single score by default — perspective winners + Pareto frontier;
--scoreis opt-in. - Determinism — task subsets via sha256; no
Math.randomin selection paths. - Fail-soft — no silent drops;
success ≠ resolved; excluded combos carry a reason. null= not collected — never zero-fill unknown values.- Self-contained HTML —
report.html/graph.htmlmust have zero<script>,src=,<link>, or CDN references (tests enforce this; interactivity is CSS-only). - Harnesses apply per-run — never mutate global state (
~/.claude,~/.codex). - i18n — user-visible strings go through
src/i18n.ts(en/kr/ja/zh).
Workflow
- Branch from
main; keep PRs focused. npm run typecheck && npm run lint && npm testmust pass (CI runs them on Node 20 and 22).- New behavior needs a test — offline (mock runner), no network.
- User-visible strings: add all four languages in
src/i18n.ts. - Update
NOTES.mdwith an AS-IS → TO-BE entry for non-trivial changes.
Reporting bugs
Open an issue with: the command you ran, expected vs actual, and — when relevant — the run
directory's meta.json/results.jsonl (they contain no secrets; scrub task content if private).