Thea Software

Name: Thea
Rating: 69.4 (1 reviews)
Author: HLIntel

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 Software: contract, change to proof, fast-loop evidence, one core verdict. Desktop: workspace, agents and tools, verify, receipts.

$ 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

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 │ ⠟154 │ ⌂scripts │ → thea brainstorm
$ thea port . --line
○ . │ ⠟182 ⠁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).
692 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; 192 more documents (621 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
152 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

Thea

PLUG IN

README