Content
# Thesmos Governance
[](https://github.com/Holley-Studio/thesmos-governance/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/thesmos-governance)
[](https://www.npmjs.com/package/thesmos-governance)
[](https://marketplace.visualstudio.com/items?itemName=holleystudio.thesmos-governance-vscode)
[](LICENSE)
[](https://nodejs.org)
**1,137 rules. Zero config. Built for the AI-assisted engineering era.**
Thesmos is a source-available code governance toolkit that watches AI-generated code for security holes, broken patterns, and architectural mistakes — before they reach production.
Built by [Holley Studio](https://holley.studio) — Thesmos governs its own repository; every PR merged here passed its own gate. Check the [Actions tab](https://github.com/Holley-Studio/thesmos-governance/actions) for proof.
**[Get Pantheon Pro →](https://holleystudio.gumroad.com/l/thesmos-pantheon)** · 40 specialist agents · 1,075 rules · Free Essentials tier always available
---
## Why Thesmos
AI tools write code faster than humans can review it. Copilot, Cursor, and Claude can ship working features in minutes — but they also hallucinate Prisma clients outside module scope, concatenate user input directly into LLM prompts, and create N+1 query waterfalls without a second thought.
Thesmos closes that gap. 1,137 governance rules covering AI safety, security, performance, and correctness — active the moment you install.
---
## Four Ways to Use It
### 1. CLI
Scan your whole codebase and get a health grade:
```bash
npm install thesmos-governance
npx thesmos scan
```
Review only staged changes before committing:
```bash
npx thesmos review
```
Run `thesmos audit` for a detailed JSON + HTML report, or `thesmos init` to walk through setup interactively.
### 2. GitHub Action
Adds governance review to every pull request. BLOCKER findings block the merge. Inline comments appear on the exact line.
Copy this to `.github/workflows/thesmos-pr.yml`:
```yaml
name: Thesmos Governance
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
pull-requests: write
contents: read
jobs:
governance:
name: Governance Review
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Thesmos PR Review
uses: Holley-Studio/thesmos-governance/actions/pr-review@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on-severity: BLOCKER
post-inline-comments: 'true'
update-summary: 'true'
```
No secrets to configure. No build step. The action is fully self-contained.
### 3. VS Code Extension
Install from the `extensions/vscode/` directory for:
- Real-time findings as you write
- Health score in the status bar
- AI adapters panel — keeps Claude, Cursor, Copilot, and Gemini aware of your governance rules so they generate governed code from the first line
### 4. Claude Code Plugin
Install directly inside Claude Code — no separate `npm install` step:
```text
/plugin marketplace add Holley-Studio/thesmos-governance
/plugin install thesmos-governance
```
Ships the MCP server, the `scan` / `review` / `advise` skills, and the same PreToolUse/PostToolUse/Stop governance hooks the CLI's `claude:govern install` writes (Node `thesmos-guard` entry, fail-closed by default) — enabled per-project, off by default.
---
## Beyond the scanner
The rules engine is the front door — behind it ships a full governance platform:
| Surface | What it does |
|---|---|
| **Diff-aware PR gate** | The GitHub Action blocks only on findings from lines your PR changed — pre-existing debt reports, never blocks. Baseline, inline suppressions, and confidence tiers honored identically across every gate ([the gate contract](docs/gating.md)) |
| **Pantheon** | 68 specialist AI agents + 53 workflow skills orchestrated by Zeus — `thesmos pantheon:*` |
| **Autopilot** | Plan-file-driven autonomous execution on an isolated branch with journaling and one-command revert — `thesmos autopilot:*` |
| **Brain** | Institutional memory that observes findings, learns patterns, and proposes new rules for human approval — `thesmos brain:*` |
| **MCP server** | Governs AI agents *before* they write — `thesmos mcp:serve` |
| **Builder wizard** | Scaffolds governed agents, skills, RAG pipelines, and MCP tools — `thesmos build:*` |
| **Execution advisor** | Recommends the right model + agents for a plan, generates a paste-ready kickoff — `thesmos advise <plan>` |
| **Compliance packs** | GDPR, EU AI Act, HIPAA, DORA rule sets with audit-trail tooling — `thesmos compliance:report`, `agent:audit:*` |
| **Cost & scope guards** | Token budgets with hard stops, agent scope boundaries, 1M-context guard — `thesmos tokens:*`, `scope:*` |
---
## How detection works
Say this plainly, because it matters for how much you should trust a finding: Thesmos's 1,137 rules are **primarily line- and pattern-based** — regex and light structural heuristics applied to file content and diffs. This is not full AST parsing or cross-file data-flow analysis, and we don't market it as one. Pattern-based detection is fast, has zero runtime dependencies, and runs anywhere — but it can be fooled by aliasing, indirection, or code shaped differently than a pattern expects, the same tradeoff every scanner in this class makes.
That admission is exactly why no finding gates blindly:
- **Confidence tiers** — every rule is tagged `high` (near-certain proof, e.g. a committed secret or disabled TLS check), `medium` (a shape heuristic that can misfire, e.g. `exec()` with a template literal whose interpolants might be constants), or `low` (a keyword/presence signal that suggests rather than proves). Only `medium`-confidence and above can fail a build by default; `low`-confidence findings are reported with a visible tag but never flip the exit code.
- **Diff-aware gating** — only findings on a line your PR actually changed (or in a file it added) can block the merge. Everything else in a touched file is reported, never blocking.
- **Suppression system** — a single inline comment (`// thesmos-disable-next-line <rule> -- reason: <why> -- owner: @who`) removes a specific false positive for good. Suppressions require a reason and an owner, and `thesmos suppressions:audit` reports unused, expired, or blanket ones.
- **Baseline** — `.thesmos/baseline.json` is an accepted-debt ledger, so gates only ever fire on *new* problems, never the ones you inherited.
The full policy — including exactly which findings can block a merge and which can't — is documented in [docs/gating.md](docs/gating.md), the single source of truth every gate (`thesmos validate`, `thesmos ci`, and the GitHub Action) follows identically.
### Who audits the auditor
Every pull request merged into *this* repository passes the same `thesmos validate` gate a customer's PR would face — including this one. That's not a promise, it's a public record: [github.com/Holley-Studio/thesmos-governance/actions](https://github.com/Holley-Studio/thesmos-governance/actions).
This codebase is also AI-accelerated, human-directed development — Holley Studio builds Thesmos with Claude Code and other AI assistants throughout. We consider that a strength, not a disclosure to bury: every AI-assisted change that lands here passes through the exact gate we sell you.
---
## The 1,137 Rules
Rules are organized into 17 categories:
| Category | Rules | Examples |
|----------|-------|---------|
| AI / LLM | 27 | Prompt injection, token limit abuse, system prompt leakage |
| Security | 22 | CORS wildcards, prototype pollution, eval usage |
| Prisma | 30 | Missing FK indexes, connection pool exhaustion, N+1 queries |
| Zod | 30 | Schemas bypassed, `.any()` usage, missing API validation |
| tRPC | 25 | Missing auth middleware, unprotected mutations |
| React | 30 | Missing error boundaries, prop drilling, stale closures |
| Next.js | 22 | Client components leaking secrets, missing suspense boundaries |
| Performance | 23 | Waterfall fetches, large bundle imports, unthrottled effects |
| TypeScript | 18 | `any` escape hatches, missing return types |
| Node.js | 30 | Unhandled promise rejections, sync I/O on the main thread |
| Error Handling | 25 | Silent catch blocks, swallowed errors |
| State | 20 | Derived state stored in useState, mutated refs |
| Forms | 20 | Missing validation, uncontrolled inputs |
| Logging | 20 | Secrets in logs, missing request IDs |
| CSS | 20 | Magic numbers, specificity wars |
| Imports | 20 | Barrel file cycles, deep internal imports |
| Database | 23 | Missing transactions, unindexed foreign keys |
Every rule is covered by the regression suite — **3,105 passing tests across 85 test files** in the core engine (as of 2026-07-12), verified on every PR. The paired-fixture policy (a true-positive fixture that must fire and a false-positive fixture that must not, per [CONTRIBUTING.md](CONTRIBUTING.md)) covers most of the catalog; completing per-rule `detect()` fixtures for every BLOCKER rule is tracked openly in [issue #96](https://github.com/Holley-Studio/thesmos-governance/issues/96) and `.thesmos/known-gaps/detect-fixture-suite.md`.
---
## Severity Levels
| Level | Meaning |
|-------|---------|
| `BLOCKER` | Must fix before merge. Blocks CI. |
| `HIGH` | Security or correctness risk. Fix soon. |
| `MEDIUM` | Quality issue. Fix in this sprint. |
| `LOW` | Best-practice gap. Fix when nearby. |
| `TECH_DEBT` | Tracked, not blocking. |
---
## Configuration
No config file is required. To customize, create `.thesmos/config.json`:
```json
{
"exclude": ["**/*.test.ts", "scripts/"],
"rules": {
"AI_013": "off",
"PERF_018": "MEDIUM"
},
"failOn": "BLOCKER"
}
```
---
## Custom Agents (federated)
Thesmos governs what an agent does, not whether the agent may exist. You can create agents directly under `.claude/agents/`, install user agents under `~/.claude/agents/`, or use Claude Code plugins (including Pantheon). Those files stay **external** until you explicitly adopt them.
```bash
# Create a project agent yourself (allowed; not Thesmos-owned)
# → .claude/agents/my-security-reviewer.md
# Optional: adopt into Thesmos registry ownership
thesmos agent:adopt .claude/agents/my-security-reviewer.md
thesmos agent:release my-security-reviewer
# Registry install (canonical .thesmos/agents/ + adapters)
thesmos agent:create "My Security Reviewer"
thesmos agent:install path/to/my-agent.md
thesmos agent:install path/to/agents-dir/ --dry-run
# Discover everything Claude Code can see
thesmos agents:list --all
thesmos agents:conflicts
thesmos agents:doctor
```
**Ownership model:** Only paths listed in `.thesmos/managed-agents.json` are Thesmos-managed. Managed Claude fallbacks live under `.claude/agents/thesmos/`. Adapter sync never overwrites unowned files. Matching filenames alone never prove ownership.
**Precedence:** project agents → user agents → plugin agents (Claude Code order). Pantheon plugin names use `pantheon:<id>` when scoped.
**Governance:** External agents still pass through project scope and hooks for tool actions. Existence is open; execution is governed.
**ID derivation (registry path):** `id:` frontmatter → `name:` frontmatter → filename stem, normalized to lowercase kebab-case.
---
## Community Rule Packs
Drop any `.json` rule pack into `.thesmos/packs/` — they load at runtime without a rebuild. See `CONTRIBUTING.md` for the schema.
---
## Repository Structure
```
thesmos-governance/
├── website/ Marketing site (deployed to Vercel)
│ └── index.html
├── thesmos/ npm package — CLI + core engine
│ ├── bin/ CLI entry points (scan, review, audit, init, watch)
│ ├── catalog/ 1,137 rules organized by category
│ ├── index.ts Public API
│ ├── metrics.ts Health grade calculation
│ └── report.ts Report generation
├── actions/
│ └── pr-review/ GitHub Action (self-contained, no install step)
├── extensions/
│ └── vscode/ VS Code extension
├── .claude-plugin/ Claude Code plugin manifest + marketplace listing
├── skills/ Plugin skills (scan, review, advise)
├── hooks/ Plugin governance hooks (Node thesmos-guard; mirrors claude:govern install)
└── .github/workflows/ CI + release pipeline
```
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Rule contributions are especially welcome — the catalog is the heart of Thesmos.
Issues and feature requests: [GitHub Issues](https://github.com/Holley-Studio/thesmos-governance/issues)
---
## License
[Functional Source License 1.1, MIT Future License](LICENSE) (FSL-1.1-MIT) — source-available today; converts to MIT four years after each version's release. Free to use, including commercially, except for a Competing Use (offering Thesmos itself, or a substantially similar product, as a hosted or on-premises service to third parties). See [LICENSE](LICENSE) for the full terms.
---
*Built by [Holley Studio](https://github.com/Holley-Studio)*
