Thomas

Use any model with any AI agent — safely.

Thomas is the plug-and-play model hub that connects your agents to your models, with security guardrails, quotas, fallback, and cost controls.

---

What it does

Thomas is the universal adapter between AI agents and model providers. Install it once, and any agent on your machine — Claude Code, Codex, OpenClaw, Hermes Agent — can talk to any provider — Anthropic, OpenAI, OpenRouter, Kimi, DeepSeek, Groq, or your own OpenAI-compatible endpoint — without editing each agent's own configuration.

Roadmap order: connect → control → optimize → protect.

Stage	Capability	Status
connect	Discover installed agents; route any agent to any provider; cross-protocol translation (Anthropic ↔ OpenAI) including streaming	✅ v0.1.0
control	Per-agent quotas, allowed-models policies, audit log	🚧 planned
optimize	Multi-provider fallback on failure; cost-aware routing; latency-aware routing	🚧 planned
protect	Prompt-injection / PII / secret detection; tool-call guardrails	💼 commercial (planned)

The open core is licensed under AGPL-3.0. Security and governance features will ship as a commercial add-on.

Audience: individual users, developers, solo and small teams. Not aimed at enterprise procurement.

Why thomas

Approach	Problem
Manually edit each agent's config (~/.claude/settings.json, ~/.codex/auth.json, …)	Brittle. Five agents = five drift surfaces.
Use a profile-switcher that rewrites those configs	When you uninstall the switcher, the agent stays pointed at whatever it last wrote.
Use a router that requires ANTHROPIC_BASE_URL exported into your shell	When the router stops, your agent breaks.
thomas	Installs a transparent shim earlier in PATH. Original config is never touched. Uninstall thomas → shim disappears → every agent reverts.

Install

npm i -g @trustunknown/thomas
thomas doctor

Requires Node 20+.

Quick start

# 1. See what agents and credentials you already have on the host
thomas doctor

# 2. Wire an agent through thomas (installs a transparent PATH shim)
thomas connect claude-code

# 3. Add a provider key (only if thomas didn't import one for you)
thomas providers add openrouter sk-or-v1-...

# 4. Switch which model that agent uses (without touching its own config)
thomas route claude-code openrouter/anthropic/claude-sonnet-4.5

# 5. See current state
thomas list

# 6. Optional: supervise the proxy with launchd / systemd so it survives reboot
thomas daemon install

# Revert at any time
thomas disconnect claude-code

After thomas connect, add ~/.thomas/bin to your PATH (the command prints the exact line).

Currently supported

Agents (CLIs that thomas knows how to detect, import credentials from, and shim):

• Claude Code
• Codex CLI
• OpenClaw
• Hermes Agent

Providers (built-in routing targets):

• anthropic (Anthropic API)
• openai (OpenAI API)
• openrouter
• kimi (Moonshot AI)
• deepseek
• groq

Plus any OpenAI-compatible or Anthropic-compatible endpoint via thomas providers register.

Cross-protocol translation

Both directions of /v1/messages ↔ /v1/chat/completions are translated, including streaming SSE — so a Claude Code (Anthropic-shape) agent can talk to OpenRouter / Groq / Kimi (OpenAI-shape), and a Codex (OpenAI-shape) agent can talk to Anthropic. System prompts, tool definitions, tool calls, tool results, image inputs, stop reasons, and SSE events are all mapped.

Use the skill

This repo ships a SKILL.md in the root. AI agents that find this repo on GitHub can read it directly to drive thomas on a user's behalf.

To install the skill into your local Claude Code skill directory:

thomas skill install claude-code

After this, your Claude Code session can answer "switch claude code to kimi" / "show me which agents are connected" autonomously.

Status

v0.1.0 — public alpha. The connect/route stage of the roadmap is complete and tested. Quotas, fallback, cost-aware routing, and security guardrails are not yet implemented.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means:

• ✅ You can use, modify, and distribute this software
• ✅ You can use it for commercial purposes
• ⚠️ You must disclose source code when you distribute the software
• ⚠️ Network use is distribution — if you run a modified version on a server and let others interact with it, you must make the source code available to them
• ⚠️ Modifications must be released under the same license

See the LICENSE file for the full license text.

Why AGPL-3.0?

AGPL-3.0 ensures that improvements to this software benefit the entire community. If you modify thomas and deploy it as a service, you must share your improvements with your users. Commercial security and governance features will ship under a separate license.