Ponytail for Claude Code: Install, Setup & What It Changes
Ponytail is a free, MIT-licensed prompt that pushes Claude Code toward the smallest change that works: check whether the code needs to exist at all, reuse what the repo already has, reach for the standard library, and only then write. Here is how to install it, what each level does, and what the maintainer's own benchmark actually measured.
Ponytail at a glance
- It is one prompt plus packaging: skills/ponytail/SKILL.md is the whole rule set, and the Claude Code plugin is what loads it into every session automatically.
- Install is two separate prompts, in this order: /plugin marketplace add DietrichGebert/ponytail, then /plugin install ponytail@ponytail.
- Three levels — lite, full (the default) and ultra — switched with /ponytail lite, /ponytail ultra or turned off with /ponytail off.
- It ships more than the writing rule: /ponytail-review reviews a diff, /ponytail-audit ranks a whole repo, /ponytail-debt collects the shortcuts you deferred.
DietrichGebert/ponytail — README
SourceGitHubchecked 2026-11-12
skills/ponytail/SKILL.md — the prompt itself
SourceGitHubchecked 2026-11-12
INSTALL.md — per-agent install steps
SourceGitHubchecked 2026-11-12
skills/ponytail-help/SKILL.md — levels, band, defaults
SourceGitHubchecked 2026-11-12
benchmarks/results/2026-10-07-agentic.md
SourceGitHubchecked 2026-11-12
dsh-ponytail — DeepSeek Harness port (unofficial)
Sourcedeepseekharnessplugins.comchecked 2026-11-12
Every command, level name, config key and number on this page was read from the upstream repository on 2026-11-12. Slash commands are left untranslated on purpose — a translated command does not run.
Repository facts from the GitHub API on 2026-11-12: 189,276 stars, 10,531 forks, created 2026-06-12, latest release v5.3.3 published 2026-10-29. Stars move daily; treat that number as a snapshot, not a constant.
Install and use Ponytail step by step
- 1
Know what you are installing
Ponytail is a rule set for coding agents, published by Dietrich Gebert under the MIT license at github.com/DietrichGebert/ponytail. Its core is a single prompt file, skills/ponytail/SKILL.md; everything else in the repo exists to load that prompt into a particular agent. The Claude Code plugin is the always-on route: once installed it is active every session and adds a statusline badge and a set of /ponytail-* commands.
The README is explicit that the ladder runs after the agent understands the problem, not instead of it: lazy about the solution, never about reading the code.
- 2
Check the prerequisites
You need a Claude Code build that has the /plugin command, and Node.js on PATH. The Claude Code plugin runs two small Node.js lifecycle hooks; without node the skills still work, but every hook call prints a harmless "node: command not found" error. Nix and nvm users: node must be on the non-interactive shell's PATH, not just your interactive one.
Commands
node --versionIf /plugin is not recognised, your Claude Code is out of date. Update it and restart before going further.
- 3
Add the marketplace — first prompt
Send this inside Claude Code. It registers the repository as a plugin marketplace named ponytail; nothing is installed yet.
Commands
/plugin marketplace add DietrichGebert/ponytailThe repository ships its own .claude-plugin/marketplace.json, which is why a plain owner/repo reference is enough — no URL and no local path needed.
- 4
Install the plugin — second prompt
Send this as a separate prompt. The format is plugin@marketplace, so ponytail@ponytail means the plugin named ponytail from the marketplace named ponytail. INSTALL.md states plainly that you have to send two separate prompts for the install to work — combining them into one message is the most common way this install fails.
Commands
/plugin install ponytail@ponytailIn the Claude Code desktop app's Code tab you can type the same two commands into the prompt box, or use the + button → Plugins → Add plugin to browse your configured marketplaces.
- 5
Confirm it is actually on
Run /ponytail with no argument. If Ponytail is off it switches on at the default level; if it is already on it reports the current level. The startup and mode-change text also shows the active mode, and the statusline badge carries it for the rest of the session.
Commands
/ponytailA quick functional check: ask for something deliberately over-built, like a date picker, and see whether the agent first looks for an existing Input component and the browser's native picker before writing anything.
- 6
Pick a level
lite builds exactly what was asked and names the smaller option in one line so you can choose. full is the default: the ladder, a small test where the logic needs one, and a reply that names what was skipped. ultra also pushes back on the request itself before building. The level sticks until you change it or the session ends.
Commands
/ponytail lite/ponytail full/ponytail ultra/ponytail offTwo other ways out: say "stop ponytail" or "normal mode" in plain language, or run /ponytail off.
- 7
Review a diff with the same rules
/ponytail-review is not a linter. It reads the code your change touches, not only the diff, and reports in this order: correct, safe, holds under load, tested, fast, lean. Every finding has to state what the code does, what goes wrong, how to fix it, and what happens if you skip it. Name a target in plain words to narrow or widen the review.
Commands
/ponytail-review/ponytail-review staged/ponytail-review branchWith no target it reviews uncommitted changes, or the last commit if there are none.
- 8
Audit the whole repo and collect the debt
/ponytail-audit runs the same checks across the repository: it maps entry points and data flow first, assumes a load level and says which one, then ranks findings so you know what to fix first. /ponytail-debt harvests the shortcut: comments the agent deliberately left behind into a ledger, so a deferred fix does not quietly become a permanent one.
Commands
/ponytail-audit/ponytail-debtThe shortcut comment format is fixed: shortcut: <the limit>, <when to upgrade>. That is what makes the debt harvestable at all.
- 9
Set a default and keep it updated
Two ways to change the level every new session starts in: the PONYTAIL_DEFAULT_MODE environment variable, or a defaultMode field in ~/.config/ponytail/config.json. Resolution order is env var, then config file, then full. To update, enable auto-update once from /plugin → Marketplaces → ponytail, or refresh manually and reload.
Commands
export PONYTAIL_DEFAULT_MODE=ultra/plugin marketplace update ponytail/reload-pluginsTo remove it, run the plugin's own node scripts/uninstall.js before /plugin remove ponytail — the script is a plugin file, so removing the plugin first deletes it.
The ladder: what Ponytail actually changes
The whole behaviour change is a decision ladder. Before writing code the agent stops at the first rung that fully works:
- 1Does it need to exist at all? Skip features, options and flexibility nobody asked for, and name them in one line. A vague "build me X" gets the smallest version that does the core job.
- 2Is it already in this codebase — a helper, a component, a service, an existing pattern? Use it the way the surrounding code does.
- 3Does the standard library or a platform feature do it? Use it, unless the project has its own house component that beats the native widget.
- 4Is it in an installed dependency? Use it. Never add a dependency for a few lines.
- 5Can it be one line a reader gets at a glance? One line.
- 6Otherwise: the minimum code that works — and one small test or assert-based self-check if it has a branch, a loop, a parser, money or security.
What it explicitly never cuts
The rule is "write only what the task needs", not "write as little as possible". The prompt names five things that stay regardless of level:
- Validation at trust boundaries.
- Error handling that prevents data loss.
- Security.
- Accessibility.
- Anything the user explicitly asked for, plus the calibration real hardware needs.
The second half of the change is the reply. Every answer ends with one or two lines naming what was skipped or not checked, and any risk you should know about. That is what makes the smaller diff reviewable instead of suspicious.
Every command, and what it does
Ponytail adds eight commands. The last four are the ones people miss when they install it expecting only a writing style.
/ponytail [lite | full | ultra | off]Set the intensity or turn it off. No argument switches Ponytail on at the default level if it is off, and otherwise reports the current level./ponytail band [on | off]Claude Code only: hide or show the band above the prompt. No argument toggles it; the level is unaffected./ponytail band importClaude Code only: add your past Claude Code sessions to the local board, with their cost, agent time and tokens./ponytail-reviewReview the current diff like the senior dev who gets paged when it breaks: bugs, security, real load, risky code without a test, slow paths, and what to cut. Accepts a plain-word target such as uncommitted, staged, branch or a PR link./ponytail-auditThe same check across the whole repo, ranked most important first./ponytail-debtHarvest the shortcut: comments you deferred into a ledger, so "later" does not become "never"./ponytail-gainShow the measured impact scoreboard from the maintainer's benchmark./ponytail-helpA one-shot reference card for levels, skills and commands. It does not change mode or persist anything.
Other agents, and the DeepSeek Harness port
The prompt is portable, and the repository ships adapters for a long list of hosts. The three that matter most:
- 1Codex: codex plugin marketplace add DietrichGebert/ponytail, then codex plugin add ponytail@ponytail, then open /hooks in Codex, trust its two lifecycle hooks and start a new thread. In Codex the commands are namespaced skills, invoked as $ponytail:ponytail-review.
- 2Cursor: git clone the repo, then node ponytail/scripts/cursor-hooks.js install. That merges two native hooks into ~/.cursor/hooks.json and leaves your existing hooks alone. Levels are switched by typing /ponytail lite as a plain message; subagents never receive the ruleset because Cursor's subagentStart cannot inject context.
- 3Anything else: npx skills add DietrichGebert/ponytail copies the six skills into the agent's skills folder, and copying AGENTS.md into the project gives the always-on ruleset without any plugin machinery.
- 4DeepSeek Harness users have an unofficial port, dsh-ponytail, whose skills are adapted from this same repository under MIT. It is a third-party adaptation, not something Dietrich Gebert publishes, so treat its behaviour as the porter's responsibility.
The published numbers, and how to read them
The README leads with large reductions. All of them come from one file in the repository, benchmarks/results/2026-10-07-agentic.md, and they describe one setup: headless Claude Code, Opus 5.5, default effort, Claude Code CLI 2.1.288, 39 tasks, 5 runs per task and arm, 585 sessions. No independent replication is claimed here.
- 1Lines of code: -53% against no skill, with a 95% bootstrap interval of -63% to -41%. Output tokens -45%, cost -26%, time -41%.
- 2Correctness did not move: on the 18 tasks with hidden checks, 87 of 90 passed with Ponytail 5 versus 86 of 90 with no skill. On the six security tasks, all three arms passed 30 of 30 runs.
- 3Tests went up, not down: a test where the logic needs one appeared in 98% of cells versus 68% without the skill, and the agent's own tests caught 66% of injected bugs versus 46%.
- 4Replies were preferred in a blind comparison, 110 to 67 against the previous version, judged on whether the reply tells a reviewer what they must know.
- 5The task mix matters: 12 feature tickets in a real FastAPI + React repo, 18 surgical tasks with hidden checks, 6 "build me a small app" requests and 3 "show me an example" requests. Bash was disabled for every arm, so this measures what the agent writes, not what it can debug.
Read those numbers as the maintainer's own measurement of his own tool, on his own task set. It is a well-documented benchmark — per-task tables, intervals, an isolation note about an earlier harness bug — but it is not a third-party audit, and it does not promise your repository will see the same percentages.
Honest limits before you install
Ponytail is a prompt. Nothing enforces it, and several things about it are worth knowing before it lands in a team repo.
- 1It is a third-party project, not an Anthropic product. It is MIT licensed and maintained by one person; the README warns that it never ships .exe or .dll files, and that a copy which does is not his.
- 2It is guidance, not a gate. The model can still over-build, and on a task whose smallest solution is already obvious the difference is close to zero — the ladder only pays off where the agent would otherwise invent structure.
- 3The band and the board are Claude Code only, need Claude Code 2.1.290 or later, and do not appear in the VS Code chat panel, cloud sessions or claude -p. Session data stays local in ~/.config/ponytail/band/ unless you configure the optional webhook.
- 4Some hosts lose features. Without lifecycle hooks the level does not persist between sessions (Gemini CLI, Qwen, Antigravity, Goose); Cursor subagents never get the ruleset; the instruction-only adapters have no commands at all.
- 5It leaves state outside the plugin folder: a mode flag, ~/.config/ponytail/config.json, a statusline script copy and possibly a statusLine entry in ~/.claude/settings.json. Removing the plugin alone leaves the badge showing the last mode.
None of that makes it a bad install — it makes it a tool you should try on a real task in your own repo before rolling it out to a team, and read the diff on the first few runs while you calibrate how much it is cutting.