agentcharter

---

🎯 The Problem & The Solution

Your team now runs five different AI coding agents, each with its own config file and its own idea of "the rules." You write "don't force-push to main" in a CLAUDE.md, a .cursorrules, and a copilot-instructions.md… and the agent ignores it anyway, because prose is a suggestion, not a control.

Agent Charter is a policy-as-code framework: you author a rule, hook, or skill once, and it compiles to the real enforcement surface of every agent — git hooks, CI gates, Claude PreToolUse, and AGENTS.md rules — validated and version-locked.

🔭 How It Works

You author a policy once. The compiler emits the strongest control each agent supports and reports the exact coverage — enforced, enforced-at-commit, or advisory — so you always know where a guarantee holds. Read the full architecture overview.

✨ Key Features

• ✍️ Author once, enforce everywhere — one policy → git-hook + CI gate + Claude PreToolUse + AGENTS.md, across 13 agents including Claude Code, Copilot, Cursor, Codex, Gemini, Aider and Windsurf. The CI gate is opt-in (agentcharter install-ci) and the coverage report only credits it once it is wired up.
• 🛡️ Real guardrails, one command away — agentcharter add protect-main-branch pulls from the catalog: block-destructive-commands, scan-secrets, block-no-verify, plus advisory rules (code-safety, git-safety, token-efficiency). Installed content is yours to edit.
• ⚙️ Deterministic, not vibes — gates are declarative and run through a stdlib-only vendored runner; guard scripts are plain bash. No LLM calls, no network, and every policy carries an eval suite replayed against its own mechanism on each build.
• ✅ Trust, but verify — a validation engine, an artifact registry, a hash-pinned agentcharter.lock, and an eval suite (with adversarial cases) for every policy.
• 📊 Coverage you can prove — compile emits a per-agent report: enforced / enforced-at-commit / advisory — the foundation for compliance attestation.
• 📦 Speaks the open packaging standard — agentcharter plugin build emits Agent Plugins 1.0.0 packages, so any conformant client can read a policy. None of them can enforce it — that part is ours. What the badge does and does not mean.
• 🧩 One CLI — init, add, recompile, validate, eval, compile, registry, plugin, verify, new, refresh, install-hooks, install-ci, install-skills, policies, disable, enable, check-matrix, compliance. agentcharter --help prints the list from the code, so that one cannot drift.

🎯 What it covers today

Agent Charter is a craft and enforcement framework first, and a security framework second — and that is worth saying plainly, because the two get marketed as the same thing.

The mechanism is genuinely deterministic: gates block commits, and the coverage report tells you exactly where. But most of the baseline catalog — yagni, token-efficiency, context-hygiene, agent-discipline, memory-discipline — are coding-discipline and token-economy rules, not security controls. The security-shaped ones are a minority: scan-secrets, protect-main-branch, block-destructive-commands, block-no-verify.

Against the OWASP Top 10 for Agentic Applications (ASI01–ASI10), that comes to 3 partial of 10, and 0 fully covered. You do not have to take our word for it:

agentcharter compliance report --framework owasp_asi

It prints the same table we would, including every uncovered row. Closing that gap is the roadmap's priority; overstating it in the meantime would cost more than the gap does.

🚀 Quick Start (3 commands)

Requires: Python 3.11+ and git. Installed git hooks need bash at runtime. Early access: not yet on PyPI — install from source while v0.0.1 stabilises.

# 1. Install
pip install git+https://github.com/open-coder-ai/agentcharter

# 2. Scaffold your repo — wiring and authoring skills, no opinions
cd /path/to/your/project
agentcharter init .

# 3. Adopt a policy, compiled and ready
agentcharter add protect-main-branch
agentcharter install-hooks .

init deliberately installs no policies. The framework ships mechanism; policies are content you choose, and once installed they are yours to edit — nothing overwrites them. That is what makes customisation possible at all.

agentcharter not found? Your Python scripts dir may not be on PATH. Use python -m agentcharter … — it works regardless of PATH.

Now watch it enforce.

git checkout main                     # or master — whichever your default branch is
echo "oops" > hotfix.txt && git add hotfix.txt
git commit -m "quick fix straight to main"
# ❌ Direct commits/pushes to a protected branch (main|master) are blocked.
#    Create a feature branch and open a pull request.
#      - main

git checkout -b feature/x
git commit -m "on a feature branch"   # ✅ allowed

That branch list is resolved from the gate, not hard-coded: point agentcharter.defaults.protected_branches at [main, master, release/*] and the message says so.

That block came from a deterministic git hook, compiled from the same policy that also produced your agents' native controls. New here? Follow the Getting Started guide.

📋 Basic Usage Example

Author your own guard and compile it to every agent:

# Scaffold a new policy (manifest + gate + evals)
agentcharter new policy block-console-log

# Validate every artifact against the spec
agentcharter validate .

# Compile it to each agent's enforcement surface + a coverage report
agentcharter compile block-console-log

A policy is just a small, reviewable manifest:

# .agents/policies/block-console-log/manifest.yaml
id: block-console-log
name: "No console.log in committed code"
artifact: hook
enforcement: block
effects: [read_only]
description: >
  Block staged JS/TS changes that add console.log — keep debug noise out of main.

📚 Documentation

Full developer documentation lives in docs/:

🗺️ Roadmap

We're building in the open. Next up:

• agentcharter add <id> — install a policy or skill from any catalog, public or private.
• CI backstop — agentcharter install-ci plus a commit-range gate mode, so a hook skipped with --no-verify is still caught on a pull request.
• Publish — PyPI package and signed standalone binaries.
• Upgrades — agentcharter upgrade, three-way merge against a pinned agentcharter.lock.
• Supply-chain & MCP packs — block hallucinated ("slopsquatted") dependencies and un-approved MCP tools.
• Cost & autonomy governance — token/spend circuit-breakers and human-in-the-loop approval tiers.
• Compliance attestation — agentcharter attest mapping controls to NIST AI RMF, ISO 42001 & the EU AI Act.

See the open issues and good first issues to jump in.

🤝 Contributing

We'd love your help — code and non-code contributions alike. Docs fixes, bug reports, and new policy ideas are all first-class. Start with the Contributing Guide and look for good first issue.

⭐ Star History

If Agent Charter saves you from one bad --force push, drop a star — it's the single biggest signal that helps other teams find the project and keeps development moving.

📄 License

Apache-2.0 — see LICENSE. Built by and for teams shipping with AI agents.