Thymus

An immune system for your codebase

Architectural invariants for AI-assisted codebases. Dependency graphs, drift scoring, auto-inferred rules. Works in Claude Code, VS Code, Cursor, Windsurf, CI, AGENTS.md, and every git commit.

View on GitHub

Get Started

# Register the marketplace (one-time)
/plugin marketplace add dhaliwalg/thymus

# Install
/plugin install thymus@dhaliwalg/thymus

# Generate your baseline
/thymus:baseline

# Teach your first rule
/thymus:learn "services must not import from controllers"

Every file edit is now checked against your rules.

# Clone and build the extension
git clone https://github.com/dhaliwalg/thymus.git
cd thymus/integrations/vscode
npm install
npm run compile
npx @vscode/vsce package

# Install the .vsix in your editor
code --install-extension thymus-0.1.0.vsix      # VS Code
cursor --install-extension thymus-0.1.0.vsix    # Cursor
windsurf --install-extension thymus-0.1.0.vsix  # Windsurf

Activates automatically when .thymus/invariants.yml exists. Violations appear as squiggly underlines on save.

Your project needs a .thymus/ directory with rules. Set it up via Claude Code (/thymus:baseline) or run bin/thymus init from the CLI.

git clone https://github.com/dhaliwalg/thymus.git
export PATH="$PATH:$(pwd)/thymus/bin"

thymus scan                  # full project
thymus scan --diff           # staged files only
thymus check src/file.ts     # single file
thymus init                  # set up .thymus/ in a new project
thymus graph                 # dependency graph (HTML)
thymus drift                 # compliance score + trend
thymus infer                 # auto-detect boundary rules

# Output formats
thymus scan --format text    # human-readable (default in terminal)
thymus scan --format json    # structured JSON
thymus scan --format github  # GitHub annotations (::error / ::warning)
thymus scan --format sarif   # SARIF 2.1.0 for GitHub Code Scanning

Requires python3 and git.

# Symlink the hook (run from your project root)
ln -sf /path/to/thymus/integrations/pre-commit/thymus-pre-commit .git/hooks/pre-commit

# Or with the pre-commit framework — add to .pre-commit-config.yaml:
- repo: local
  hooks:
    - id: thymus
      name: thymus architectural lint
      entry: bin/thymus scan --diff --format text
      language: script
      pass_filenames: false

Blocks commits with error-severity violations. Warnings pass through. Set THYMUS_STRICT=1 to also block on warnings. Bypass with --no-verify.

# .github/workflows/thymus.yml
name: Architectural Lint
on: [pull_request]
jobs:
  thymus:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Clone Thymus
        run: git clone https://github.com/dhaliwalg/thymus.git /tmp/thymus
      # Option 1: GitHub annotations on the PR
      - name: Run Thymus
        run: /tmp/thymus/bin/thymus scan --diff --format github
      # Option 2: SARIF upload for Code Scanning dashboard
      - name: Run Thymus (SARIF)
        run: /tmp/thymus/bin/thymus scan --format sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

The Problem

AI tools write great code. But they don't remember your architecture between sessions. Over days, patterns drift — boundaries get crossed, conventions break, dependencies leak where they shouldn't. By the time you notice, the debt has compounded.

How It Works

1

/thymus:baseline

Scans your project, detects modules, boundaries, and patterns. Proposes invariants. You review and save.
2

/thymus:learn

Teach rules in plain English. "Controllers must not import from the database layer" becomes a structured YAML invariant. No regex, no config syntax to memorize.
3

/thymus:infer

Automatically detects boundary rules from your import graph. Analyzes real module dependencies and proposes invariants you can accept, reject, or edit.
4

Every edit, automatically

A PostToolUse hook checks each file change against your rules in milliseconds. Warns Claude immediately if something drifts.
5

/thymus:scan

Full-project scan on demand. Catches violations the hooks might miss.
6

/thymus:graph

Interactive module dependency graph. Visualize your architecture, see which modules talk to which, and highlight boundary violations in context.
7

/thymus:agents-md

Generates an AGENTS.md with your rules as natural language. AI coding agents (Claude Code, Copilot, Cursor) read it automatically and follow your architecture during code generation.
8

/thymus:health

Generates an HTML health report with compliance score, drift tracking, trend sparklines, and debt projections. Scores are saved to history so you can see how your architecture evolves over time.

Works Everywhere

Rules defined once, enforced regardless of which tool your team uses. Claude Code is where you author rules. Everything else is where they get enforced — no AI tooling required.

CLI

Scan from the terminal. Single files, full project, or staged changes.

VS Code / Cursor / Windsurf

Violations show as inline squiggly underlines on save.

Git Pre-Commit

Blocks commits with boundary violations. One symlink to install.

GitHub Actions

PR annotations via --format github, or SARIF upload for Code Scanning dashboards.

AGENTS.md

Auto-generated natural language rules that all AI coding agents read and follow — Copilot, Cursor, Windsurf, and more.

Claude Code

The full experience — real-time hooks, natural language rules, health reports.

JSON / SARIF API

Structured output in JSON, GitHub annotation, or SARIF 2.1.0 format for custom integrations.

Language Support

JavaScript / TypeScript

AST-aware state machine — handles comments, strings, template literals, regex

Python

Full AST via stdlib ast module

Go

Comment-aware — handles //, /* */, double-quoted and raw backtick strings

Rust

Comment-aware — handles nested /* */, raw strings with r#"..."#

Java

Comment-aware — handles text blocks ("""...""")

Dart

Comment-aware — handles triple-quoted and raw strings, Flutter framework detection

Kotlin

Comment-aware — handles nested /* */, triple-quoted strings, Spring Boot & Ktor detection

Swift

Comment-aware — handles nested /* */, multi-line strings, Vapor & iOS detection

C#

Comment-aware — handles verbatim strings, raw literals, ASP.NET detection

PHP

Comment-aware — handles heredoc/nowdoc, Laravel & Symfony detection

Ruby

Comment-aware — handles =begin/=end blocks, heredocs, Rails detection

What It Enforces

Boundaries — Database access only through the repository layer

db.query() found outside src/repos/ — violation

Patterns — No raw SQL outside the db module

SELECT * found in src/handlers/user.py — violation

Conventions — Tests colocated with source files

test_auth.py expected next to auth.py — missing

Dependencies — Axios only used in the API client

import axios found in src/components/ — violation

Rule Example

Rules are human-readable YAML. Edit them by hand or let /thymus:learn write them for you.

# .thymus/invariants.yml
- id: boundary-routes-no-db
  type: boundary
  severity: error
  description: "Route handlers must not import from the database layer"
  source_glob: "src/routes/**"
  forbidden_imports:
    - "src/db/**"

- id: pattern-no-raw-sql
  type: pattern
  severity: error
  description: "No raw SQL outside the db module"
  forbidden_pattern: "(SELECT|INSERT|UPDATE|DELETE)\\s+"
  scope_glob: "src/**"
  scope_glob_exclude:
    - "src/db/**"