open source · MIT license

Enforce module boundaries in Python.
Catch violations in CI.

Define allowed dependencies between modules in a governance.toml. Run it locally, in CI, or let an LLM tell you what to fix.

View on GitHub

terminal

30-second setup

Three commands. That's it.

Generate

Scans your source code, detects modules, and maps every real import.

governance-ast --generate --source-root src/

Configure

Review the generated governance.toml. Adjust boundaries to match your intended architecture.

[[modules]]
name = "api"
cannot_depend_on = ["billing", "migrations"]

Enforce

Run locally or in CI. Violations fail the build. No more silent boundary erosion.

governance-ast

what it catches

Five rules, zero ambiguity

🔗

enforce_cannot_depend_on

Module imports from a forbidden dependency.

🔄

no_cycles

Circular dependency detected. A imports B, B imports A.

📐

enforce_layers

Lower architectural layer imports from a higher one.

📢

max_public_surface

Too many symbols exposed to other modules. Keep your API tight.

🧲

min_cohesion

Module imports more from outside than from itself. It might belong elsewhere.

CI integration

Catches violations in your PR

Add one GitHub Action. Get violation reports as PR comments with LLM-powered fix suggestions.

❌ Governance — 1 violation, 1 new module

🔴 🔗 core: Forbidden dependency: 'core' imports 'db' (cannot_depend_on: ['db'])

core/service.py:2

📦 New module exporters (exporters/) — not in governance.toml

Reply /governance fix to apply.

🤖 AI: The core→db import creates tight coupling. Extract shared types into a common module, or remove "db" from core's cannot_depend_on.

Reply /governance fix on the PR and the bot auto-updates your governance.toml with correct cannot_depend_on and commits to your branch.

Adopting on an existing codebase? Save a baseline and only fail on new violations:

governance-ast --save-baseline .governance-baseline.json
governance-ast --baseline .governance-baseline.json

- uses: actions/checkout@v4
- name: Governance
  uses: useparadigm/code-governance@main
  with:
    config: governance.toml
    diff: origin/main
    advise: true
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

LLM advice

Don't just find violations — understand them

Pass --advise and get architectural recommendations powered by OpenAI or Anthropic.

$ governance-ast --advise

🤖 Architectural advice:

The api → billing dependency suggests checkout logic is reaching into the billing module directly. Consider:

1. Extract charge_customer() into a shared interface in core
2. Or explicitly remove "billing" from api's cannot_depend_on — this is a legitimate dependency if api owns the checkout flow

The payments ↔ notifications cycle is more concerning. Break it with an event bus or move send_receipt into the payments module.

○ OpenAI (gpt-4o)

○ Anthropic (claude-sonnet)

honest comparison

vs tach & import-linter

tach and import-linter are the established tools. Here's an honest comparison.

	code-governance	tach	import-linter
Setup	--generate creates config from source	50-100 lines TOML with regex	Manual contract definition
Monorepo support	✓ scans source directly	✓ scans source	Must be importable
Diff mode	✓ only check changed files	✗	✗
Baseline	✓ accept existing, fail on new	✗	✗
CI comments	✓ PR comments + fix suggestions	Exit code only	Exit code only
Auto-fix	✓ /governance fix	✗	✗
LLM advice	✓ architectural recommendations	✗	✗
Error guidance	LLM explains why + suggests fix	"cycle detected" — no context	Import chain shown, no fix
Module metrics	✓ cohesion, surface, symbol count	✗	✗
HTML report	✓ dependency matrix viewer	✗	separate browser UI
Public interface enforcement	✗	✓ visibility controls	✗
Transitive imports	✓ transitive chains	direct only	✓ transitive chains
Speed (Django, 902 files)	~1.2s	sub-second (Rust)	~0.1s
Package needs installing	No — scans source directly	No — scans source	Yes — must be importable

Choose tach if you need public interface enforcement or visibility controls. Choose code-governance for transitive chain detection, CI integration, auto-fix, LLM advice, and zero-config setup.

Enforce module boundaries in Python.Catch violations in CI.

Codebases rot from the inside