Skip to main content

once: your coding agent makes each mistake once

PyPI Python CI License: BSL 1.1 Works with Claude Code, Codex and Antigravity

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 run once.hook codex.

How it works

Capture, flag, suggest, replay, give back; every session feeds the next

  1. Capture. Each agent's hooks record prompts, commands and edits. Secrets are masked before anything is written.
  2. 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".
  3. 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.
  4. Replay. once lab replay reruns 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.
  5. 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.

A session timeline with a retry cluster boxed in red Conversations across Claude Code, Codex and Antigravity
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 with the sessions behind each one
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 share opens 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-check flags 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-run shows exactly what it would send.
  • Easy to leave. once purge deletes sessions. once uninstall removes 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

License

Business Source License 1.1.

  • 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)

Source distribution for once-cli 0.9.0
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)

Table of built distributions (wheels) for once-cli 0.9.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.9.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page