TheaOS mcp

Protocol: a change maps to proof; Thea selects evidence and the build enforces the verdict (evidence). Agents: llms.txt; chats: CHAT.md.

Start: install/use · architecture · enterprise · agents · chat · adapters

Why this exists

An agent can report a change as done without running a single check. A check that never ran looks the same as a check that passed, and the change ships. Thea closes that gap:

• Every change maps to proof. atlas.yaml lists the checks each kind of file owes, and the gate runs them before the change is called finished.

• Refusal happens at commit, for any agent. A git hook runs the same check-only command whether Claude, Codex, Cursor or a person made the commit.

• A skipped check is never a pass. A missing tool is reported as SKIP, counted, and kept out of the pass count. Gates report PASS, FAIL or NOT RUN; missing tools never go green.

$ thea gate scripts/doctor.py
1. formatter: ruff format --check scripts/doctor.py
2. compiler_or_typechecker: python3 -c 'import ast,sys; [ast.parse(open(f, encoding="utf-8").read(), f) for f in sys.argv[1:]]' scripts/doctor.py
3. unit_tests: pytest

Related MCP server: spec-drift-mcp

Quickstart

# no checkout
uv tool install thea-software && thea doctor
# or, editable
git clone --depth 1 --branch v3.60.0 https://github.com/HLIntel/TheaSoftware ~/thea && uv tool install --editable ~/thea && thea doctor

In your repository:

cd path/to/your-repo && thea init   # checks, Claude Code + Codex wiring, first run
thea verify && thea report          # after a change: verdicts, then what is unverified

With an impact map, thea verify --changed runs planted groups with moved dependencies or no record. It speeds feedback; thea verify remains the final verdict.

Agents reach Thea over MCP: thea-mcp is read-only today. Enterprise execution gates and host approval hooks live in the companion runtime (TheaOS). No-shell chat: CHAT.md. Add Thea to another repository: CONSUMING.

Where it fits

• Any agent. One contract for Claude Code, Codex, Cursor, opencode and Hermes. The adapters are in models/README.md; the commit gate does not depend on which one is running.

• Any repository. thea init wires a repository in one step. Consumers add the reusable CI workflow from CONSUMING so the verdict on a laptop and in CI is the same command.

• Any language we route. Each language × check pair is either answered by a command or declared as having no tool, so an unanswered pair cannot hide.

Enterprise and companion runtimes

• Thea Software (public, MIT): The core verification protocol, command suite, language manifests, and read-only MCP server.

• TheaOS (enterprise): The proprietary companion runtime with native desktop workspace, multi-agent orchestration, and enterprise policy controls. Companion details.

$ thea port scripts/doctor.py --line
◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓3 │ ⚠1 │ → thea gate scripts/doctor.py
$ thea port scripts --line
◎ scripts │ ⠟153 │ ⌂scripts │ → thea brainstorm
$ thea port . --line
○ . │ ⠟181 ⠁4 ⠿4 │ → thea check

What it measurably buys

What the recorded instruments have caught in real runs. They prove routing and refusals, not end-to-end task success (limits).

Failures caught

• 31/31 planted breaks refused at commit, across 20 of 40 languages. 20 more have an example its toolchain has not run; 0 have none yet (enforce.py v3.60.0).

• 676 mistake kinds planted in the tests, each refused.

• 118 failure shapes recorded from real runs: 205 sightings, 47 recurred, 97 now guarded, 21 host-only (3 of them recurred).

• 1076 refusals in daily use (37 shapes, 654 re-fired). Verify: 39 passed and 187 failed, of 485 runs. 112 of 115 lands armed; 701 lessons shown (agents.py --field v3.59.0).

• 24/24 solo commits clean with or without the hook; a planted broken commit is refused.

• 6 agent controls block, never warn: narrow_tools, sandbox, budget, approval, effects, audit.

Cost

• 1,716 tokens read before routing; 190 more documents (619 KiB) load only when a route names one.

• 89% fewer tokens than pasting every tool list; 50% fewer than blind.

• 10 KiB install: 1 module, 2 dependency — 8 in total with its own dependencies.

Coverage

• 360 language × check pairs (40 × 9), all answered: 144 by a command, 216 by a declared no tool, 0 silent.

Agent contract

• Route: thea port <file>, or parse .agent/bootstrap.json; load only its names.

• Automate: add --json; records follow the output schema.

• Before shell: thea shell --json "<cmd>"; exit 3 means its verdict would be misread.

• Land: python scripts/branchstate.py --land; check thea landed <branch> before deletion.

• Judge and report: use the judgment rungs; file breaks with the thea skill.

Counts, computed

Generated on every build; check refuses drift. Machine-readable: .agent/facts.json.

• 388 tool entries — across 40 manifests and 5 kinds, validated against tools/tools.schema.json

• 349 agreement edges — each a file tied to the declaration it answers for

• 94 instruments — each stating what it proves, what it does not, and what closes the gap

• 7 change classes — and 13 task profiles, in atlas.yaml

• 151 harness Python files — every one held by lint · format · typecheck

• 3.60.0 contract version — VERSION, asserted in 8 other files

Find your way

• Every document: docs index · wiki

• Languages: atlas · routing · verification

• Agents: harness · .thea · runtimes

• Why a rule: thea why · thea failures · instruments

• Security: policy · OpenSSF · contributing

Project

Version tracks the contract, not content (versioning). Built by HLIntel LLC, public on purpose (about). Contributions pass thea verify. MIT License.

Updated: contract v3.60.0