Rules for agents to first ask whether to write code
Open-sourced by Dietrich Gebert, Ponytail is a ruleset injected into an AI agent, together with a few skills and commands. Its persona comes from the veteran engineer every company has: ponytail, oval glasses, and more time at the company than version control has existed. Give him fifty lines, and he glances at them, says nothing, and replaces them with one. Ponytail applies that judgment to your agent.
It addresses an AI agent tendency: over-building. Ask for a date picker, and the agent may install flatpickr, write a wrapper component, add a stylesheet, and discuss time zones as well. Ponytail's approach is to follow a six-rung decision ladder before writing any code, stopping at the first applicable rung.
The rule is to write only what the task needs, rather than minimize tokens. The code is small because it is necessary, not because its line count has been compressed. Official tests used headless Claude Code on a real FastAPI + React repo for 12 feature tasks (Haiku 4.5, n=4). Relative to a no-skill baseline, Ponytail was the only group to reduce LOC, tokens, cost, and time while keeping its safety score at 100%.
Does it need to exist
Standard library
Platform native
Installed dependencies
One line
Minimum viable
He says nothing. He writes one line. It works.
One-line installation for 14 agents
The Claude Code and Codex plugins run two tiny Node.js lifecycle hooks, so node must be on PATH. The two most common hosts are installed as follows:
# Enter these two lines in the Claude Code conversation
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
# Claude Desktop has no /plugin command: install through the UI
# Customize → + beside personal plugins → Create plugin and add marketplace
# → Add from repository → Paste the repo URL# Codex CLI
codex plugin marketplace add DietrichGebert/ponytail
# Open /plugins and install Ponytail, then review and trust both lifecycle hooks in /hooks
# GitHub Copilot CLI
copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytailOther hosts: one line or one file
Skill-capable hosts use their own package commands for installation. Instruction-only editors need only a copy of the corresponding rules file; the rules remain active throughout the session.
| Tool | Installation |
|---|---|
| Gemini CLI / Antigravity CLI | gemini extensions install <repo URL> (or agy plugin install) |
| OpenCode | Run from a checkout of this repo and add the plugin path to opencode.json |
| Pi agent harness | pi install git:github.com/DietrichGebert/ponytail |
| OpenClaw | clawhub install ponytail |
| Cursor / Windsurf / Cline / Kiro / Zed | Copy the corresponding rules file (.cursor/rules/, .windsurf/rules/, etc.) |
| CodeWhale / VS Code (Codex extension) | Reads AGENTS.md at the project root; no configuration |
Four intensity levels and five commands
Ponytail stays active in every session by default, with four intensity levels. /ponytail without arguments reports the current level; lite / full / ultra / off switch it. Commands require a skill-capable host (Claude Code, Codex, OpenCode, Gemini, pi). In Codex, they are skills triggered with @.
Level · 01
/ponytail lite
Light reminder
Minimal intervention. Provides a light reminder for obvious over-building without interrupting the flow.
Level · 02
/ponytail full
Default intensity
The default. Applies the full decision ladder on every turn. Use PONYTAIL_DEFAULT_MODE to change the global default.
Level · 03
/ponytail ultra
Strongest mode
The official explanation reserves it for when 'the codebase has wronged you.' It removes unnecessary construction most aggressively.
Level · 04
/ponytail off
Off
Temporarily disables the skill. The current mode is displayed at startup and when switching.
Command · 05
/ponytail-review
Diff review
Reviews the current diff for over-engineering and returns a deletion list.
Command · 06
/ponytail-audit
Whole-repo audit
Audits the whole repo for over-engineering, beyond the current diff.
Command · 07
/ponytail-debt
Technical debt ledger
Collects deferred shortcuts marked with ponytail: into a ledger so deferred items do not remain undone forever.
Command · 08
/ponytail-gain
Results scoreboard
Shows the measured benchmark impact: less code, lower cost, and faster execution.
Command · 09
/ponytail-help
Quick reference
A quick reference for the commands above.
Six-rung decision ladder
This is Ponytail's core mechanism. Before writing code, the agent follows the ladder and stops at the first applicable rung. If the standard library can do it, it does not install a package; if the platform has a native feature, it does not write its own:
| Rung | Question → Action |
|---|---|
| 1 | Does this need to exist? → Skip it if not (YAGNI) |
| 2 | Can the standard library do it? → Use it |
| 3 | Does the platform have a native feature? → Use it |
| 4 | Can an installed dependency do it? → Use it |
| 5 | Can one line solve it? → One line |
| 6 | Only now write the minimum working implementation |
The most effective usage in the official documentation
All eight tips below come from the official README and docs, without community hearsay or unverified numbers. Each card identifies its source section.
The full default and global env configuration
Use the PONYTAIL_DEFAULT_MODE environment variable (lite/full/ultra/off), or the defaultMode field in ~/.config/ponytail/config.json, to set the level for each new session. The default is full.
Source · Official README, Install
ultra for when the codebase has wronged you
Official wording: /ponytail ultra exists for when the codebase has wronged you personally. Use full for everyday work; ultra removes code most aggressively.
Source · Official README, Install
The review deletion list
Run /ponytail-review after writing a section of code. It reviews the current diff for over-engineering and returns removable items; /ponytail-audit expands this to the whole repo.
Source · Official README, Commands
ponytail: deferral markers and the debt ledger
When a shortcut is needed, mark it with a ponytail: comment. Later, run /ponytail-debt to collect those deferred items into a ledger so they do not remain undone forever.
Source · Official README, Commands
Skill-capable host requirements for commands
Commands require Claude Code, Codex, OpenCode, Gemini, or pi. Instruction-only adapters such as Cursor, Windsurf, Cline, Copilot, Kiro, and Antigravity load only the persistent ruleset, without commands or mode switches.
Source · Official README, Commands
PATH requirements for node
The Claude Code / Codex plugins run two lifecycle hooks and need node on PATH. Otherwise, the skill still works, but persistent activation is silently disabled rather than reporting an error. Nix/nvm users should check non-interactive shells.
Source · Official README, Install
Zero-configuration AGENTS.md use in CodeWhale
Copy AGENTS.md to your project root, or run codewhale from a checkout of this repo, and the rules take effect. The VS Code Codex extension also reads AGENTS.md.
Source · Official README, Install
Optional configuration files
The official FAQ says no config file is needed. Optional config.json or env variables only set the default level; there are no required settings.
Source · Official README, FAQ
A one-line date picker implementation
The example below comes from the README. For the same date picker request, an agent without the skill installs a package, writes a wrapper, and adds a stylesheet. With Ponytail, it stops at the 'platform native' rung: the browser already has <input type="date">. The example then shows /ponytail-review returning a deletion list for an existing diff.
$ You ›
Add a date picker so users can select an appointment date.
hl: rung 3 Platform native? → Match. The browser has a native date input
claude: Claude(ponytail)›
No flatpickr, wrapper component, or stylesheet is needed.
The browser already has one:
ok: <!-- ponytail: browser has one -->
ok: <input type="date">
$ You › /ponytail-review
claude: DELETE LIST —
hl: · dateUtils.ts:formatForPicker() wraps native toISOString(); delete it
hl: · DatePicker.css(entire file) the native control has its own styles; delete it
· validateDate() keep it; trust-boundary validation is outside the deletion list
ok: Net change:-86 lines · Safety safeguards:all retained ✓
You need a date picker. The browser already has one.
Wrapper removal and feature retention
Deletion targets wrappers while retaining features: redundant utility functions wrapping native APIs and unnecessary stylesheets are removed, while trust-boundary validation such as validateDate() stays. The difference between Ponytail and a simple 'write one line' prompt is that the latter lost a safety guardrail in the benchmark; Ponytail did not.
The line counts in the example are illustrative. Actual reduction depends on the task: it is largest with genuine over-build scenarios (date picker, color picker), and near zero when the code is already lean.
Boundaries and limits of simplification
Simplification rules for every session
After installation and a successful run of full, the following steps expand Ponytail from 'a reminder in one host' into 'consistent rules across the team and toolchain.'
Advanced usage
1. Team default level. Use PONYTAIL_DEFAULT_MODE or defaultMode in config.json to unify the intensity for every new session so the team does not have to switch manually each time.
2. Review integration. Run /ponytail-review before every PR for a deletion list, and periodically run /ponytail-audit across the repo to treat over-engineering as measurable work items.
3. ponytail technical debt management. Mark deferred shortcuts with ponytail:, regularly collect them into a ledger with /ponytail-debt, and address them later.
4. Consistent rules across tools. Use docs/agent-portability.md to match files to agents, and sync the same rules to instruction-only editors such as Cursor, Windsurf, Cline, and Kiro.
5. Reproduce measurements yourself. Use /ponytail-gain to view the results scoreboard, or follow benchmarks/ to reproduce measurements on your own repo and model, confirming results with your own measurements.
Three priority reading resources
① benchmarks/results/2026-06-18-agentic.md: full methodology, per-task tables, and limits. ② examples/: more real examples before and after simplification. ③ docs/agent-portability.md: a complete mapping of files to agents.
The code you never wrote scales infinitely. Zero bugs, zero CVEs, always 100% uptime.