@openthomas/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 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 (v1.1, MIT). The spec is frozen for 12 months so the number means the same thing across operators and time.

Quick start

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 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 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.

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.

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 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.