charter

AI-agent readiness, scored.

Charter grades any repository 0–100 on how safely an AI coding agent can work in it —
then hands you the exact fix for every gap. Offline, deterministic, no LLM in the loop.

Documentation · Rule catalog · GitHub Action · Changelog

Why Charter

An AI coding agent is only as safe and effective as the repository it operates in. Missing
context files, unpinned MCP servers, leaked secrets, and absent CI gates quietly degrade
every agent that touches your code — and you find out in the diff, not before.

Charter makes that readiness measurable: one deterministic score, 18 rules across
9 categories, 0 network calls. Run it locally, gate it in CI, fix what it flags.

[!NOTE]
Charter is a static analyzer, not an agent. It reads your files and prints a number.
No code is sent anywhere, nothing is mutated without a diff you approve.

Quickstart

# install (macOS / Linux)
brew install use-charter/tap/charter

# score the current repo
charter doctor

That's the whole loop. charter doctor scans the tree, evaluates 18 rules, and prints a
banded score with a per-category breakdown and every finding inline. Exit code is the gate:
0 pass · 1 below threshold · 2 error.

[!TIP]
New repo? Run charter init first to scaffold the context files agents expect
(AGENTS.md, charter.yaml, .gitignore), then charter doctor for an honest baseline.

Install

Signed binaries ship for macOS, Linux, and Windows on both amd64 and arm64. Pick your
platform below, or use Go on any of them.

macOS

brew install use-charter/tap/charter

Works on Apple Silicon and Intel. Upgrade later with brew upgrade charter.

Linux

# Homebrew (Linuxbrew)
brew install use-charter/tap/charter

No Homebrew? Grab the archive for your architecture from the latest release
— charter_<version>_linux_amd64.tar.gz (or _arm64) — then:

tar -xzf charter_*_linux_*.tar.gz
sudo install charter /usr/local/bin/charter

Windows

Download charter_<version>_windows_amd64.zip (or _arm64) from the
latest release, unzip it, and add
charter.exe to your PATH:

# from the folder where you unzipped charter.exe
$dest = "$env:LOCALAPPDATA\Programs\charter"
New-Item -ItemType Directory -Force $dest | Out-Null
Move-Item charter.exe $dest -Force
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$dest", "User")   # reopen the terminal

Any platform — Go

go install go.use-charter.dev/charter/cmd/charter@latest   # requires Go 1.26+

From source

git clone https://github.com/use-charter/charter && cd charter
go build -o charter ./cmd/charter

Verify the download

Every release is cosign-signed with SLSA Level 3 provenance and ships checksums.txt, a
Sigstore bundle (checksums.txt.sigstore.json), and a per-archive SBOM. Confirm what you
installed at any time:

charter version --verify   # prints version, build provenance, and cosign verification status

Commands

A small, sharp surface. The same seven commands behave identically in your shell and in CI.

What it checks

18 rules across 9 categories. Severity sets the score weight; every rule carries an AE-* ID
and a fix. Full reference at use-charter.dev/rules.

Scoring

score = max(0, 100 − B×20 − H×10 − M×4 − L×1)
final = min(score, applicable_cap)

B/H/M/L are Blocker/High/Medium/Low finding counts. Informational findings are
excluded. Hard caps keep the dangerous cases honest:

• a raw secret in agent-visible content → ≤ 49
• any active Blocker → ≤ 59

The formula is public and stable within a major version. Same inputs, same score — always.

Gate it in CI

# .github/workflows/charter.yml
- uses: use-charter/charter-action@v1
  with:
    threshold: "80"   # fail PRs that score below this
    verify: true      # cosign + sha256 the binary before running

The action downloads the signed binary, runs charter doctor --format sarif, and uploads to
GitHub Code Scanning — findings land inline on the PR, no new dashboard to learn. See
action/README.md.

The contract

Charter makes ten commitments, and shows its work on every one:

• ✅ No network calls — ever
• ✅ No LLM calls in the core
• ✅ No file deletion
• ✅ No silent mutation — diff-first fixes only
• ✅ Every finding has a rule ID and fix guidance
• ✅ Every release is signed (SLSA L3 + cosign)
• ✅ The score formula is public and stable within a major version
• ✅ Cross-vendor across every major coding agent
• ✅ Secrets are never printed
• ✅ The CLI is free, forever (Apache-2.0)

Performance

charter doctor scans a 50,000-file repository in ≤ 2 s using ≤ 256 MiB RSS —
asserted in CI by moon run :perf.

Tech stack

Layer	Built with
Core CLI
Build & tooling
Web & docs
Infra & CI/CD
Supply chain

Documentation

Contributing

mise install               # toolchain (Go, Bun, Moon, hk)
./scripts/install-hooks.sh # pre-commit / pre-push hooks
moon run :check            # full quality gate

Conventional Commits, SemVer, DCO sign-off on every commit. Irreversible decisions are
recorded as ADRs in docs/internal/decisions/. See
CONTRIBUTING.md.

Star history

License

Apache License 2.0. DCO-first contributions.