Canny CLI
Hooks for Claude Code and Codex CLI keep a ledger of agent actions and refuse a "done" claim until a check has passed.
- 132 ★ on the repository
- Last commit
Extended access
Why this level
- Hooks sit on every agent tool call and can deny or rewrite a command.
- With a TypeSafe key, edit fragments and the agent's last message go to an external API.
Install
- Works in
Manual install
git clone https://github.com/qkal/canny.git ~/.canny/srcThe clone lives in `~/.canny/src`; there is nothing to build because the compiled CLI is committed.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks sit on every agent tool call and can deny or rewrite a command.
- With a TypeSafe key, edit fragments and the agent's last message go to an external API.
This is third-party code. Review the repository files before installing.
What it does
Canny is a supervision layer for AI coding agents. It hooks into Claude Code and Codex CLI and writes a ledger of session facts: which files changed, which commands ran and what exit code they returned. When an agent tries to finish and no check (test, build, lint, type-check) has passed since the last code edit, Canny refuses and names the files and the last command. Pattern checks add more: a hook denies writing secrets (AWS, GitHub, Stripe, OpenAI, Anthropic keys, private keys), asks before tests are deleted or `.skip` is added, rewrites `npm test | tail` to run under `set -o pipefail` and stops the fourth repeat of a failing command. Code makes these decisions offline. The optional Jev model from TypeSafe, enabled by `TYPESAFE_API_KEY`, adds notes and can only relax a rule.
Who it is for. Developers who give Claude Code or Codex long tasks and want to see tests actually run, not only the word "done".
Good fit when
- An agent writes "done" without running tests and you only learn that after the session.
- A file with an API key written by an agent must not reach a commit.
- An agent deletes failing tests or adds `.skip` instead of fixing the code.
- After a session you review the ledger: `canny replay` re-derives verdicts from recorded facts.
Not a fit when
- The agent is neither Claude Code nor Codex CLI: the hooks target the event format of those two.
- The machine has no Node.js 22 or newer.
- The task has no code or tests: the done-gate fires only after code edits.
Example request
Add a function to math.js and do not finish until the project checks pass.Limitations
Canny is not on npm: clone the repository into `~/.canny/src` and run `node ~/.canny/src/dist/cli.js init`. Git and Node.js 22 or newer are required. The ledger stores command lines, exit codes and paths of edited files, so a secret in a command argument lands there. With `TYPESAFE_API_KEY` set, edit fragments of up to 4,000 characters and the agent's last message go to the TypeSafe API and are cached in `~/.canny/jev/`. The `verify`, `ignore`, `rules` and `allow` fields in `.canny.json` apply only after `canny trust`, yet an agent with shell access can run that command itself. Typical shell file writes are recognised, but `find -exec rm` and `python -c` are invisible to Canny.
How to disable. Run `node ~/.canny/src/dist/cli.js remove` from the project root (or with `--global`). Delete the `~/.canny` directory with the ledgers separately.
FAQ
How do I install Canny?
Paste the prompt from the README install section into Claude Code or Codex inside the target project. The agent clones the repository into `~/.canny/src` and runs `init`. By hand: `git clone https://github.com/qkal/canny.git ~/.canny/src`, then `node ~/.canny/src/dist/cli.js init`.
What does Canny block and what does it only suggest?
Finishing without a passing check, writing secrets and the fourth repeat of one failing command are blocked. Deleting tests triggers a confirmation prompt in Claude Code and a denial in Codex. Jev answers stay notes for the agent.
Is a TypeSafe key required?
No. Without `TYPESAFE_API_KEY` the ledger, the done-gate and the pattern checks work the same and nothing leaves the machine.
How do I know the hooks are live?
Run `echo canny-check`, then `node ~/.canny/src/dist/cli.js status`. If the output lists a session with at least one event, the hooks work.
Which agents are supported?
Claude Code and Codex CLI. `init` writes hooks for the agents it finds, and the `--claude` and `--codex` flags pick one.
Discussion
No questions or reviews yet.
Related
CLI toolsReviews the git diff and the conversation with the agent: catches bugs and gaps between your request and the agent's result. CLI, skill, GitHub Action
OpenQodex reviews your change before a push: scanners with no model first, then a separate Claude Code or Codex process triages findings on your login
A Playwright and TypeScript project template with rules and 17 skills so Claude Code, Codex and Cursor write tests to a standard
Four Claude Code skills: 1C testing through Codex and 1c-testpilot, code review, export and load through ibcmd
Corrections you give your agent turn into rule files in the repository and run with taskless check locally and in CI.
Vercel CLI for testing coding agents on your framework: runs Claude Code, Codex and others and measures the success rate
README in short
The README opens with a live run: Claude Code wrote a file through a heredoc, ran nothing and declared the work finished. On a repeat of the same prompt Canny refused to let it stop. Then come the three hooks, a table of checks, the exact order of the done-gate, `.canny.json` settings and differences between Claude Code and Codex.