When an AI agent misses the mark, there is always a human expectation it failed
to meet. canon lets the human write those expectations down and make AI agents
iterate until all of them are satisfied.
That is how this project was built: no human-written implementation code, just
Codex working against canon until the repository satisfied its own canon.
Copy the
Canon section from this repository's AGENTS.md
into your project's AGENTS.md.
Requires Git, Docker, curl, and Codex (Desktop or CLI).
This is the recommended install path for most users. canon itself was built
by AI agents and has not been reviewed line by line by a human. The Docker
wrapper is the small human-reviewed trust boundary: it runs the published
Docker image in an unprivileged container, drops Linux capabilities, disables
new privileges, uses a read-only container filesystem, keeps Codex credentials
read-only on the host, and only gives the container the repository access needed
for canon commands.
Before installing, review the Docker wrapper on GitHub. Install it only if you are comfortable trusting that wrapper as the host-side boundary.
After reviewing the wrapper, install it as the canon executable in a directory
on your PATH. For example, to install it in ~/.local/bin:
mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/progbeat/canon/master/.canon/docker/scripts/canon -o "$HOME/.local/bin/canon"
chmod +x "$HOME/.local/bin/canon"If ~/.local/bin is not already on PATH, add it to your shell configuration:
export PATH="$HOME/.local/bin:$PATH"After that, command -v canon should print a path under $HOME/.local/bin.
Requires Git, Rust/Cargo, and the Codex CLI.
cargo install --git https://github.com/progbeat/canonUse Cargo when developing canon or when you intentionally want a host-native
binary. Prebuilt release binaries are not published yet.
To install the skills from this repository, ask Codex:
Install the agent skills from `https://github.com/progbeat/canon/tree/master/skills`.
-
Ask Codex to implement a feature.
-
If something is off, add the unmet expectation to
.canon/check.yml, then ask Codex to fix the project against the updated canon. -
Iterate.
Canon changes are the human's responsibility. Before committing them, it is
recommended to use $canon-guidelines for review.
canon initCreate .canon/check.yml from canon's embedded default template.
canon pre-commit installInstall the local pre-commit hook.
canon pre-commit uninstallRemove the local pre-commit hook.
canon checkEvaluate configured expectations against the staged project state, using cached results to avoid unnecessary evaluator work.
canon check a7F K9mExplicitly evaluate selected expectations by unique ID prefix or full ID. These selectors are expectation IDs, not 1-based expectation numbers.
canon ask "Can you find any practically exploitable security vulnerability?"Ask one uncached ad-hoc question. Add one or more -s/--scope paths to debug
the same question under a narrower evaluator scope.
canon gateRun the pre-commit gate manually.
MIT