DEV Community

Tashfiqul Islam
Tashfiqul Islam

Posted on • Originally published at use-charter.dev

Charter: a deterministic readiness score for AI coding agents

#agents #ai #security #opensource

AI coding agents inherit the repository they land in.

That sounds obvious until you watch one fail for reasons that have nothing to do with the model.

Give an agent a clear AGENTS.md, pinned tools, runnable tests, safe defaults, and a CI path it can understand, and it usually behaves like a careful senior engineer. Drop it into a repo with missing context, an MCP server pinned to @latest, unclear conventions, and a secret sitting in plain sight, and it will still try to help. Confidently.

That confidence is the dangerous part.

I kept seeing the same pattern: an agent commits a key it found in a config file. Another hangs because an MCP server changed underneath it. Another rewrites half a module because nothing told it how the project is supposed to work.

Those are not model failures. They are repository failures.

And until now, they have mostly been invisible. There was no simple answer to:

How safe is this repo for an AI agent to work in?

So I built one.

What Charter does

Charter is an offline CLI that grades any repository from 0 to 100 based on how ready it is for AI coding agents.

It checks nine areas:

  • Context
  • Secrets
  • MCP safety
  • Agent configuration
  • Environment setup
  • CI
  • Testing
  • Autonomy
  • Governance

Under those areas are eighteen deterministic rules. Each rule has a severity, a clear check, and a concrete fix.

Run:

charter doctor
Enter fullscreen mode Exit fullscreen mode

And you get a score, a breakdown, and the exact gaps keeping the repo from being safer for agents.

Charter doctor output

The first number is usually humbling. That is kind of the point.

Why this is not an LLM judging your repo

The obvious version of this product would be: point a model at the repo and ask, “Is this agent-ready?”

I did not want that.

A score you cannot reproduce is not a gate. It is a vibe.

Charter’s score is a public formula over a fixed rule set. Same repo, same score, every time. No prompt drift. No API bill. No model deciding whether your other model has enough context.

It is closer to a linter than a reviewer.

That makes it boring in the best way. You can read the rules, predict the result, and trust the number enough to put it in CI.

The loop

The workflow is intentionally small.

1. Initialize the repo 

charter init
Enter fullscreen mode Exit fullscreen mode

This scaffolds the files an agent expects, including AGENTS.md and charter.yaml.

2. Get the baseline 

charter doctor
Enter fullscreen mode Exit fullscreen mode

Most repos that have never been prepared for agents land somewhere around 40–60.

That does not mean the repo is bad. It usually means the repo was built for humans who already know the context, not for agents that need the context written down.

3. Fix what is safe to fix 

charter fix
Enter fullscreen mode Exit fullscreen mode

Charter is diff-first. It shows what it wants to change before anything is written.

It also has hard boundaries: secrets and destructive commands are never auto-touched. Charter will point them out, but it will not put its hands on them.

It belongs in CI too

A local score is useful. A CI gate is better.

Charter emits SARIF 2.1.0, so findings can show up in GitHub Code Scanning. There is also an official GitHub Action with a score threshold:

- uses: use-charter/charter-action@v1
  with:
    threshold: 80
Enter fullscreen mode Exit fullscreen mode

That turns “this repo feels agent-ready” into something much easier to reason about:

This repo must stay above 80 before we merge.

The score can ratchet up over time instead of being a one-off cleanup project.

The contract

Charter makes a few hard promises:

  • No network calls
  • No LLM in the core scoring path
  • No file deletion
  • No silent mutation
  • Every finding maps back to a rule
  • Every rule includes a fix
  • The same binary works locally and in CI
  • Releases are signed, SLSA-built, and shipped with SBOMs

It is Apache-2.0 and free forever.

Try it

Install it with Homebrew:

brew install use-charter/tap/charter
charter doctor
Enter fullscreen mode Exit fullscreen mode

Or install it with Go:

go install go.use-charter.dev/charter/cmd/charter@latest
Enter fullscreen mode Exit fullscreen mode

You can also grab a signed binary from the releases page.

Docs and the full rule list are here:

https://use-charter.dev/

Source is on GitHub - please give it a star if you find it useful.

I would genuinely like to hear which rule you think is missing.

The first number is usually humbling. Fixing it is the point.

Top comments (0)