Godlint

The executable engineering constitution for repositories maintained by humans and coding agents.

Quickstart · Rules · Documentation · Contribute

AI coding agents increase output. They do not automatically preserve your architecture, security boundaries or engineering standards.

Godlint turns those decisions into deterministic policy that every contributor runs locally and in CI. Define a rule once; enforce it across Rust, TypeScript, JavaScript and Python with the same result for humans and agents.

Human or agent writes code
        ↓
Godlint checks repository policy
        ↓
Clear finding → fix → deterministic CI

Why Godlint

• Guardrails for agents. Catch architectural drift before generated code reaches review.
• One policy across languages. Share boundaries and thresholds across a polyglot repository.
• Deterministic enforcement. No LLM decides whether CI passes.
• Accountable exceptions. Suppressions carry a reason, owner and expiry.
• Local by default. Source code does not leave your machine.

Godlint complements Clippy, ESLint, Ruff and Pyright. They understand one language deeply; Godlint enforces the repository-level decisions that must hold across all of them.

Quickstart

Create godlint.yaml:

version: 1
suites: [recommended@1]

Run:

npx @godlint/cli check
# or: uvx godlint check
# or: cargo install godlint-cli && godlint check

That is enough to enforce the recommended policy locally and in CI.

What it enforces

Godlint ships 25 rules for:

• architecture and module boundaries;
• restricted imports, calls and dependencies;
• centralized configuration and safer execution;
• complexity, nesting, function and file size;
• production logging and error handling;
• accountable, expiring suppressions.

See the rule reference for every rule and its limits.

GitHub

Annotate findings directly on pull requests:

- uses: tomerwave/godlint@v1
  with:
    version: 0.1.9

The action needs no token or write permissions. Godlint also emits terminal, GitHub, JSON and SARIF output. See Using Godlint in CI.

Install

Use the package manager already in your project:

Ecosystem	Command
npm	npm install --save-dev @godlint/cli
pnpm	pnpm add -D @godlint/cli
Yarn	yarn add -D @godlint/cli
Bun	bun add -d @godlint/cli
uv	uv add --dev godlint
pip	pip install godlint
Cargo	cargo install godlint-cli
Homebrew	brew install tomerwave/tap/godlint

Prebuilt binaries for Linux, macOS and Windows are available from the latest release.

Contribute

Godlint is pre-alpha. This is the best time to shape it.

• Use it: try recommended@1 on a real repository and report false positives.
• Propose a rule: bring valid and invalid examples across the relevant languages.
• Improve it: code, fixtures, documentation and design feedback are welcome.

Start with CONTRIBUTING.md or open a rule proposal. Report security issues through SECURITY.md, not a public issue.

Status

Godlint is pre-alpha. Rule identifiers, configuration and suite contents may change before 1.0. The project is deterministic and useful today; the roadmap records what comes next.

License

MIT