thomas

# Thomas > Get Thomas on the wire. **The dynamic harness for your agent fleet.** v0.5 is the first agent harness to: ### 1. Give vision-blind coding models eyes DeepSeek codes well but can't see. Qwen3.6 sees images and video but codes poorly. Thomas combines them as one virtual model: any agent that hands it an image — Claude Code, Claude Desktop, OpenClaw, Codex, Hermes — gets a routed pipeline where the vision model describes the image and the coding model acts on the description. Two strategies ship in v0.5: - **Pre-describe** — vision model describes every image once; the coding model receives the descriptions in place of the images. Cheap, robust, no model-specific tool-call format required. - **On-demand `view_image`** — the coding model is given a tool it can call to ask focused questions about a referenced image; a bounded agentic loop services each call against the vision model. More interactive — the coder can zoom in on a region or re-ask. Configured once per route in `~/.thomas/routes.json`. Works across every agent on your machine because Thomas wraps the wire, not the agent. ### 2. Show cost per task — not per model, not per agent Every other tool rolls cost up by model or by agent. Useful for finance; useless for figuring out what last night's autonomous run actually bought you. Thomas tracks every model call back to the **task** that triggered it. The Tasks view shows you, run by run, the three pricing buckets — cached-in / fresh-in / out tokens — live $-cost, and the full action graph that produced them. Filter by agent, sort by spend, find the run that cost too much, replay it to see what it was doing. --- Your agent fleet is only as reliable as its harness. 2025 was the year of agents. 2026 is the year of harnesses — the scaffolding around a model (tools, context, guardrails, the loop, the verify step) that decides whether it is reliable. Claude Code is a harness for one model. Your *fleet* of agents — Claude Code, Codex, OpenClaw, Hermes, all running in parallel while you sleep — has no harness around it. Thomas is that harness. It is generated on the fly: `thomas wire` detects what you run and wraps it — no rewrites, no framework. Thomas wraps the **wire**, not the agent, so it works even on agents it does not own. ### Three verbs | Verb | What the harness does | Edition | |---|---|---| | **See** | Capture, decode, replay every action; score outcomes with the T metric | **Free, forever** | | **Control** | Enforce on your own agents — approval gates, blocking, policy, budgets | Personal · Solo | | **Govern** | Enforce across a team's agents — BYOA, RBAC, audit, compliance | Team · Enterprise | **See is free and complete** — capture, decode, view, replay, and score every agent action forever, locally, without paying a cent. **Control and Govern are paid** (see [Pricing](#pricing) below): the same binary, gated by a cloud license token. ## Thomas (T) — your outcome-per-token score Thomas computes a single dimensionless KPI from everything it captures: ``` Σ human-equivalent value of outcomes (USD) T = ────────────────────────────────────────── total AI cost (USD) ``` A `T = 47` means: every $1 of AI spend produced $47 of human-equivalent labor. Higher is better. The companion `T_verified` (v1.1) restricts the numerator to outcomes whose tool_result indicated success — so 19 failed attempts on a vulnerability search don't get scored as 19 wins. Token spend on failures still hits the cost basis. Run `thomas thomas` to see yours. Full spec at [openthomas.com/thomas](https://openthomas.com/thomas) (v1.1, MIT). The spec is frozen for 12 months so the number means the same thing across operators and time. ## Quick start ```bash npm install -g @openthomas/thomas thomas wire # detect agents, install taps, start daemon # …run your agent as usual… thomas thomas # see your T (outcome / AI cost) thomas # open the dashboard at http://localhost:9877 ``` `thomas wire` is byte-exact reversible: `thomas unwire` restores every file it touched. No accounts, no telemetry, no cloud — your traces stay on your machine. Read [`PRIVACY.md`](./PRIVACY.md) for the precise list of every file Thomas writes and the only place it sends data (forwarding your own agent's traffic to the model provider your agent already calls — and nowhere else). ## How Thomas fits the founder journey Anthropic's [Founder's Playbook][playbook] names four stages every AI-native startup moves through. AI compresses each — and introduces new failure modes the playbook explicitly warns about. Thomas is the harness that lets the orchestrator see, control, and govern what their fleet does, at every stage. | Stage | Where you are | See — free — gives | Natural upgrade | |---|---|---|---| | **Idea** | Ten hypotheses, ten Claude bills running in parallel | Cost X-ray per agent, per project, per day | **Personal**: budget caps so rabbit holes can't drain credits | | **MVP** | Agentic coding, unattended runs. *"Code that works is not code that is secure."* — playbook | Full action trace, risk flags (destructive shell, secret leak, retry storm), mock replay | **Personal**: approval gates, budget caps, model routing | | **Launch** | Real users on the line. The playbook prescribes *"the observability layer that makes SLAs actually enforceable."* | Audit trail per run, shareable post-mortem reports | **Personal**: live blocking + alerts. **Solo**: multi-project workspaces, CI replay, eval suites built from real production traces | | **Scale** | First hires, multiple machines, enterprise procurement asking for proof you are *"a dependable infrastructure partner."* | (free keeps recording) | **Team**: RBAC, SSO, shared policies, fleet management, audit log for compliance | **Same job, new instruments.** The playbook closes with *"Same job, new rules"* — the founder's work hasn't changed, only the path. Thomas is one of the instruments that makes the new path navigable. [playbook]: https://www.anthropic.com/news/founders-playbook ## Pricing Thomas Free is **See** — the legible harness, complete on its own. Paid editions turn the harness from read-only to enforcing. They divide by **who the harness answers to**: *self-harness* (you enforce on your own agents) and *governed-harness* (an authority enforces across a group's agents, including ones each member brings — **BYOA**). | | Free | Personal | Solo | Team | Enterprise | |---|---|---|---|---|---| | Verb | See | Control | Control | Govern | Govern | | Capture, decode, timeline, replay | ✅ | ✅ | ✅ | ✅ | ✅ | | T metric + cost X-ray + risk flags | ✅ | ✅ | ✅ | ✅ | ✅ | | Approval gates, blocking, policy | — | ✅ | ✅ | ✅ | ✅ | | Budget caps, model routing, sync | — | ✅ | ✅ | ✅ | ✅ | | Multi-project, CI replay, evals | — | — | ✅ | ✅ | ✅ | | BYOA — govern agents you don't own | — | — | — | ✅ | ✅ | | RBAC, SSO, fleet view, audit log | — | — | — | ✅ | ✅ | | Compliance pack, on-prem, custom SLA | — | — | — | — | ✅ | | Price | $0 | $19/mo | $99/mo+ | $499/mo+ | Custom | **Thomas Family** — the governed harness for the household (a parent governing a child's AI) — is sequenced separately; no date yet. Every edition is the **same binary**, gated by a cloud-issued license token — no plugins, no separate CLI. The free package never calls cloud, never phones home, stays complete forever. The protection is structural: the cloud rejects un-licensed requests, and replicating the cloud service is the actual product moat. Run `thomas upgrade` for the in-product comparison, or visit `http://localhost:9877/#/pricing` while the daemon is running. Today (v0.5): free only — the See edition. **Personal** and the other paid editions land in later releases. ## What you'll see ``` $ thomas thomas Your Thomas · last 24h · spec v1.1 25.0 $13.8K solo founder with reasonable hygiene T verified outcomes $553.71 of AI spend → $13,821 of verified human-equivalent labour 1,093 actions · 129 verified outcomes · 322.9M tokens tokens by pricing bucket: 287.4M cached-in (cache hit) · 31.2M fresh-in (non-cache-hit) · 4.3M out action_rate: 3.39 a/Mtok outcome_rate: 11.8% Outcomes: 47 commits · 44 files edited · 27 files created · 9 CI passed ``` ``` $ thomas list ID STARTED AGENT STATUS DUR ACT COST CACHED/FRESH/OUT ──────────── ─────────────────── ─────────── ────── ────── ─── ─────── ──────────────── ru_aBc1xYz9 2026-05-16 14:23:11 claude-code done 1.4s 1 $0.0024 0/120/45 ru_fOj6Ce1H 2026-05-16 14:22:18 hermes done 7.8s 1 $0.97 565K/6K/396 ``` ``` $ thomas tail 14:42:49 claude-code mcp_call → filesystem tools/list 14:42:49 claude-code mcp_call ← filesystem tools/list 14:43:21 claude-code model_call claude-opus-4-7 200 6/8 $0.0007 ! 14:44:02 hermes model_call Xiangxin-2XL-Chat 200 1/1547 $1.367 ``` ## What it captures - **Model calls** — Anthropic, OpenAI, Gemini, OpenRouter, vLLM, and any OpenAI-compatible endpoint. Streaming and non-streaming. Full prompt / response / tool_use blocks. - **MCP messages** — JSON-RPC over stdio. Per-frame capture (request / response / notification) with method, params, result, error. - **Tool calls** — tool_use blocks (bash, file edit, web fetch, …) inline with the model response that produced them. - **Cost / tokens / latency** — including cache_read / cache_write attribution. See exactly when a prompt cache charged you. - **Risk signals** — destructive shell (`rm -rf`, `curl | sh`), possible secret leak (keys, tokens, bearer creds), cost spikes, retry storms. Read-only labels in the trace. You decide what to do. ## Why not Langfuse / Helicone / LangSmith? Those tools watch **model calls**. Thomas watches **agent runtimes** — the full execution graph including tool calls, MCP, file ops, and inter-agent traffic. If you've ever asked *what did my agent actually do?*, that's the gap. ## Supported agents | Agent | Auto-wire | Notes | |---|---|---| | Claude Code | ✅ | via `~/.claude/settings.json` env block + MCP wrap | | OpenClaw | ✅ | restarts the launchd daemon on wire | | Hermes | ✅ | paste `/model <name> --global` to apply live | | OpenCode | ✅ | | | Codex | ✅ | rewrites `[model_providers.openai]` in `~/.codex/config.toml` (Responses API) | | Cursor | ⓘ manual | | | Gemini CLI | ⓘ manual | | Custom agent? Point its base URL at `http://localhost:9877/wire/<your-name>/<provider>` and Thomas will record everything. ## Architecture Thomas runs as a single always-on Node.js daemon, installed via launchd on macOS or systemd on Linux. Four layers: **capture** (HTTP reverse proxy + MCP stdio tap) → **decode** (Anthropic SSE, OpenAI chat, MCP JSON-RPC per-protocol decoders) → **store** (local SQLite) → **present** (Hono REST + SSE + React UI on `localhost:9877`). All data stays on disk under `~/.thomas/`. Source: [`github.com/openthomas-com/thomas`](https://github.com/openthomas-com/thomas). ## Status v0.5 — the fleet-harness cut. v0.4 was the first public NPM release (legible-harness pipeline: capture · decode · score). v0.5 adds the control surface: per-route failover chains with error/budget/token switch rules, per-route capabilities (vision pre-describe, web_search emulation), and a `thomas-tools` MCP that gives the routed model search/fetch when its upstream can't. Solo-built and used daily by the author; tested against real Claude Code / Claude Desktop / OpenClaw / Codex / Hermes traffic. Bug reports and PRs welcome. ## License & trust Thomas is MIT licensed. All code that runs on your machine — including the implementations of paid commands — is open source. The free tier **never calls cloud, never phones home, never sends telemetry**. See [`PRIVACY.md`](./PRIVACY.md) for the load-bearing privacy contract, which lists every file Thomas writes and the only place it sends data (your own agent's traffic, to the model provider your agent already calls). Paid tiers ship in the same MIT-licensed binary. They activate when a cloud license token is placed at `~/.thomas/license.json`; without one, the cloud rejects requests. We are open-source on the client and proprietary on the cloud — the same model as Sentry, PostHog, Cal.com, Tailscale, and Stripe CLI.