Tellonce

English · 中文

Stop re-explaining yourself to your AI coding agent. Tellonce remembers the corrections you make and — when you ask it to — enforces them, so the same mistake doesn't come back. In our evaluations, held-out preference violations drop from 100% to 2.0% on out-of-distribution coding-agent tasks (research below).

You told your agent to stop writing scratch files to /tmp. To reply in your language. To leave unrelated code alone. Three turns later it does it again. Tellonce watches each turn, records the preferences, pitfalls, and workflow rules it detects, and can hard-enforce the ones you care about.

It is safe by default: out of the box it only records and reminds. It never blocks you and never sends your conversation anywhere until you opt in.

✨ Highlights

• 🧠 Learns from your corrections. Every turn is scanned for preference / pitfall / friction signals and recorded automatically.
• 🛡️ Opt-in enforcement. Turn it on and replies that violate your saved rules are blocked, and the agent fixes them in the same turn.
• 🔒 Private by default. All records stay on your machine, and the optional LLM judge is off by default — when enabled it only ever sees a redacted snippet and runs through your own subscription. (Rule retrieval is fully local by default — the progressive backend just reads your saved rule files, no model call; opt into small-model matching with PT_RETRIEVE_BACKEND=cli.)
• ⚡ Runs on Claude Code, Codex, and GitHub Copilot CLI (one-command install on Copilot) — one shared memory across all three.
• 🎛️ Three modes, one switch: observe → enforce → full.

📄 The research behind it

Tellonce is the deployable artifact of TRACE (Test-time Rule Acquisition and Compiled Enforcement) — our research on compiling user corrections into runtime enforcement for coding agents (arXiv:2606.13174). From the paper's simulated user-in-the-loop evaluations:

• Remembering ≠ honoring. With a state-of-the-art memory layer (Mem0), 57.5% of applicable preference checks were still violated on tasks derived from anonymized real-user friction cases. Memory recalls the correction; nothing makes the agent act on it.
• Compiled enforcement closes the gap. On coding-agent tasks (ClawArena), TRACE reduces held-out preference violation from 100% to 2.0% on out-of-distribution tasks, and from 100% to 37.6% in-distribution.
• Without giving up task quality. On memory-intensive tasks (MemoryArena-derived), TRACE cuts violations while matching or exceeding the strongest memory baseline on task pass rate.

And in real daily use, the correction rate behaves the way you'd hope: the author's own library grew to ~280 rules in its first two months of intensive use — then new-rule creation fell by 97% under continued daily work (single-digit new rules per month since), because the existing library already covers what used to need correcting. 88% of rules were right on the first write and never needed a revision.

Experiment code: YujunZhou/TRACE_exp · Cite: BibTeX

🚀 Quick start (Claude Code)

The native way — run these two commands inside Claude Code:

/plugin marketplace add YujunZhou/tellonce
/plugin install tellonce@tellonce

The hooks auto-register; start a new session to activate. Tellonce begins in the safe observe mode (records + reminds, never blocks); turn on hard blocking in a shell with export PT_ENFORCE=1.

git clone https://github.com/YujunZhou/tellonce.git ~/.claude/skills/tellonce
python3 ~/.claude/skills/tellonce/lib/_install_merge_settings.py --settings ~/.claude/settings.json --hooks-dir ~/.claude/skills/tellonce/hooks --add

That registers Tellonce user-global in ~/.claude/settings.json (every project covered; state/memory still per-project). Per-project instead: cd <project> && bash ~/.claude/skills/tellonce/install.sh. Full guide — enforcement, uninstall — in INSTALL.md. Pick one method: if you register via settings.json AND /plugin install, the hooks fire twice — remove one (...--remove) before adding the other.

🚀 Quick start (Codex)

The native way — Codex CLI plugin marketplace (Codex CLI ≥ the March 2026 plugin release):

codex plugin marketplace add YujunZhou/tellonce
codex plugin add tellonce --marketplace tellonce
# verify: codex plugin list --marketplace tellonce  ->  installed, enabled

Tellonce begins in the safe audit_only mode (records, never blocks). (The install verb is codex plugin add, not install.) The Codex marketplace manifest is validated against the current Codex CLI (codex plugin marketplace add + the plugin validator pass); if /plugin install doesn't load the hooks on your Codex build, use the manual install below.

git clone https://github.com/YujunZhou/tellonce.git ~/.codex/skills/tellonce
cd /path/to/your/project
bash ~/.codex/skills/tellonce/codex/install.sh   # under codex/, NOT the repo-root install.sh
bash ~/.codex/skills/tellonce/codex/doctor.sh

See codex/docs/README.md for modes and the wrapper flow.

🚀 Quick start (GitHub Copilot CLI)

One-command bootstrap (recommended — pinned to the immutable tag v1.3.2, SHA256 published for pre-verification, see copilot/README.md):

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/YujunZhou/tellonce/v1.3.2/copilot/bootstrap.ps1 | iex"

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/YujunZhou/tellonce/v1.3.2/copilot/bootstrap.sh | bash

It downloads the Copilot-adapted plugin (the copilot/ sub-plugin — with SessionStart injection, the Copilot Stop-block contract and Windows run.ps1 shims), copies it into Copilot's plugin directory, installs the optional dependency, registers it, sets the safe observe mode, and records your Python path. Restart Copilot when it's done.

⚠ Do not copilot plugin install tellonce@tellonce from this repo's marketplace — that entry is the Claude Code variant (repo root) and does not fit Copilot's hook surface (no per-prompt injection, different block contract, .claude/ state paths). If you prefer a native plugin install of the sub-plugin, use copilot plugin install YujunZhou/tellonce:copilot, then run bash <plugin_root>/install.sh once (see copilot/README.md).

Supported platforms

All three share the same user-preference memory and design philosophy (Iron Law / Gate Function / scan → record → confirm). The underlying mechanism is adapted per runtime: Claude Code and Copilot use Stop hooks, while Codex has no Stop hook and runs through a wrapper instead. See codex/docs/CC_PARITY_MATRIX.md.

Modes

Switch at any time (Copilot variant):

python "<plugin>/lib/pt_mode.py" observe   # back to the safe default
python "<plugin>/lib/pt_mode.py" enforce   # turn on hard blocking
python "<plugin>/lib/pt_mode.py" full      # hard blocking + LLM judge
python "<plugin>/lib/pt_mode.py" status    # show the current mode

Privacy: all records stay local in every mode. Only full sends the last message and reply (redacted) to copilot -p for scoring, on your own subscription. Rule retrieval is fully local by default (the progressive backend just reads your saved rule files); PT_RETRIEVE_BACKEND=cli opts into your own subscription's small model. The full judge additionally needs PT_SHADOW_RULE_IDS set to the rule ids you want checked — pt_mode.py full prints a reminder.

How it works

1. Rule injection — on Claude Code and Codex your saved rules are injected on every prompt (UserPromptSubmit); on Copilot once per session at SessionStart (its only injection point).
2. Each turn ends (Stop) — the turn is scanned for new preference / pitfall / friction signals, which are recorded to an observation log.
3. In full — a small-model LLM judge checks each reply against the rules you list in PT_SHADOW_RULE_IDS and flags violations for the agent to fix. (The enforce deterministic layer ships with no built-in rules — it is an opt-in extension point, so it blocks no content by itself.)

Self-check & uninstall (Copilot variant)

python "<plugin>/lib/doctor.py"        # self-check: python / registration / mode / hooks
python "<plugin>/lib/dashboard.py"     # status at a glance: mode / rules / records
python "<plugin>/lib/uninstall.py"     # dry-run: show what would be removed
python "<plugin>/lib/uninstall.py --all"
copilot plugin uninstall tellonce

<plugin> is printed at the end of install; it is ~/.copilot/installed-plugins/tellonce/tellonce.

Project layout

README.md                 # this landing page (English)
README.zh.md              # Chinese companion
copilot/                  # GitHub Copilot CLI variant — the public release
codex/                    # Codex variant (wrapper-driven)
docs/claude-code.md       # Claude Code variant, in depth
hooks/ lib/ SKILL.md ...  # Claude Code variant (lives at the repo root)
seed_memory/              # empty by default; new users start with a blank slate
LICENSE

Citation

If you use Tellonce or build on TRACE in your research:

@article{zhou2026trace,
  title   = {Getting Better at Working With You: Compiling User Corrections
             into Runtime Enforcement for Coding Agents},
  author  = {Zhou, Yujun and Guo, Kehan and Zhuang, Haomin and Wang, Xiangqi
             and Huang, Yue and Liang, Zhenwen and Chen, Pin-Yu and Gao, Tian
             and Moniz, Nuno and Chawla, Nitesh V. and Zhang, Xiangliang},
  journal = {arXiv preprint arXiv:2606.13174},
  year    = {2026}
}

License

MIT — see LICENSE. An open-source research artifact for studying in-session LLM preference enforcement. Issues and PRs welcome.