Install · How it works · See it · Guide · Changelog
Coding agents forget. The same build error three times, the same wrong test command, the same file missed, session after session, even after you've corrected them.
once watches your agent's sessions and turns each mistake into a rule for the repository. It checks the rule by replaying the session with and without it, and hands it back to the agent next time. It works with Claude Code, Codex and Antigravity, and everything stays on your machine.
Install
uv tool install once-cli # or: pipx install once-cli (the command is `once`)
once demo # the whole loop on a toy repo, in seconds; touches nothing of yours
Then, in a git repo you use with an agent:
once init # shows what it will change, then connects every agent it finds
That's the setup. Keep working as usual. Python 3.10 or newer, macOS or Linux.
Codex: it runs new hooks only after you trust them. Start
codex, type/hooks, and trust the ones that runonce.hook codex.
How it works
- Capture. Each agent's hooks record prompts, commands and edits. Secrets are masked before anything is written.
- Flag. once marks the steps that wasted time: the same error repeated, a command that keeps failing, a file read over and over, a file the agent should have changed. It also picks up corrections you type in the chat: "no, use tox, not pytest".
- Suggest. Each one becomes a one-line rule for the repo, optionally limited to some paths. Nothing is active until you say yes, in the chat, in the terminal, or in the dashboard.
- Replay.
once lab replayreruns the session that went wrong, three times without the rule and three times with it, in throwaway copies of the repo. A rule that doesn't change the outcome is marked as such. - Give back. Rules reach the agent at session start, and when it touches matching files. A rule can also be
enforced:
- a reminder after an edit that breaks it;
- an error the agent must fix;
- a refusal before the edit lands.
See it
once ui opens a local dashboard. Nothing is hosted.
| Sessions. Every step of every session. Wasted steps are boxed in red. Tag them, or turn one into a rule in a click. | Conversations. What you and each agent said, in one searchable place, with flags and corrections pinned where they happened. |
| Pull requests. The PRs your agents worked on, the sessions behind each one, and how each was linked. Also: whether sessions given rules ship more often than sessions without. | |
Day to day, without commands
- Correct your agent as you normally would. once keeps the correction as a suggested rule.
- Answer it when, at the start of the next session, the agent asks whether to keep a suggestion.
- Glance at the status line in Claude Code:
once ● 2 of 5 rules in use · 1 to review · 2 flagged. - Read the weekly digest, by file, notification, Slack or email.
When you want more: once last shows the last session, once teach "..." adds a rule, once why says which rules
apply and why, and once review goes through suggestions.
Works with
| Claude Code | Codex | Antigravity | |
|---|---|---|---|
| Sessions recorded | ✓ | ✓ | ✓ |
| Rules at session start | ✓ | ✓ | ✓ (each turn) |
| Rules for matching files | native rule files | before commands | glob rule files |
| Enforcement | ✓ | ✓ | ✓ |
| Conversations and PR links | ✓ | ✓ | ✓ |
| Tools the agent can call (MCP) | ✓ | ✓ | ✓ |
For teams
-
once shareopens a pull request that adds your rules to.once/rules/. Everyone using once in the repo gets them when it merges. -
The collector is one small server that gives a team one view: each agent and developer, where agents struggle, and which rules are broken where. It receives counts and outcomes only.
-
once pr-checkflags files a pull request probably missed, from the repo's own history. As a GitHub Action:- uses: actions/checkout@v4 with: { fetch-depth: 0 } - uses: Tanay0510/once@v0.9.0
Privacy
- Local by default. Sessions, rules and the dashboard stay on your machine. The dashboard listens only on
127.0.0.1. - Secrets masked before anything reaches disk.
- The collector is opt-in. It never receives prompts, replies, code, commands or error text.
once collector push --dry-runshows exactly what it would send. - Easy to leave.
once purgedeletes sessions.once uninstallremoves every hook and restores your settings exactly.
once never gets in your agent's way: if anything inside it fails, the agent carries on and the error goes to a log.
Status
Beta. Seen working live:
- Claude Code and Antigravity: recording, rules, enforcement and the MCP tools.
- Codex: recording and conversations.
Still being proven: Codex enforcement, the learning loop at scale, and a measured improvement on held-out tasks. The changelog keeps an honest list.
Learn more
- The guide: every feature and setting.
- Changelog and details: release history and known gaps.
- AGENTS.md: how the code is laid out, for people and agents working on it.
License
- Free to use, including at work and on commercial code: with your own agents, on your own or your employer's repositories, and for your team.
- Not allowed: using it in a product or service you sell that competes with once.
- Each version becomes Apache-2.0 four years after it is published.
For other terms, contact the author.
Metadata
Release files for once-cli 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| once_cli-0.9.0.tar.gz | 2.0 MB | With provenance | Details for once_cli-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| once_cli-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for once_cli-0.9.0-py3-none-any.whl |
Total release size: 2.4 MB
Release files / once_cli-0.9.0.tar.gz
| Download URL | once_cli-0.9.0.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
665813b49226549ece845840218edaa278553c3e9e791200a1ee3f4ca87c2425
|
|
BLAKE2b-256 checksum How to use checksums |
90f437ac5842625047dc7273b0b383a64f61c2277307d60a81fa46bc1db5c749
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / once_cli-0.9.0-py3-none-any.whl
| Download URL | once_cli-0.9.0-py3-none-any.whl |
|---|---|
| Size | 331.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
033578a6b41fb242767c67ec2d317b51b49771c25e3f59b6028f3e84c13ef7bf
|
|
BLAKE2b-256 checksum How to use checksums |
7ed73835cd5cc32f54cf561cc7471b72bd5ba3d3cf3e45bd61534a2f5ce5959f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for once-cli 0.9.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for once_cli-0.9.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.