Table of Contents

  1. Why it exists

  2. What it can actually do

  3. Before you start

  4. Installation

  5. Setup step by step

  6. Prompts to use it

  7. Commands table

  8. Daily workflow

  9. Tips

  10. Troubleshooting

  11. Quick reference

🧠 Why it exists

You ask your AI agent for a date picker. It installs flatpickr, writes a wrapper component, adds a stylesheet, and opens a discussion about timezones. Fifty lines later you have something the browser already had for free: <input type="date">.

This is not a rare edge case. AI agents over-engineer by default. They are optimized to produce code, not to avoid it. Every unnecessary abstraction they write is a bug you get to maintain, a dependency you have to audit, and a CVE you get to patch.

Ponytail puts a senior engineer inside the loop — one who has seen every pattern, trusts the platform, and writes one line when one line is enough. The rule is simple: the best code is the code you never wrote.

It is not negligent laziness. Trust boundaries, data loss handling, security, and accessibility are never skipped. Everything else gets questioned first.

⚡ What it can actually do

You say

What happens

"Build me a date picker"

Agent checks browser native support first, uses <input type="date"> if it fits

"Add email validation"

Agent checks stdlib or a single regex before installing a library

"Build a rate limiter"

Agent checks if an installed dep already covers it

"Write a debounce function"

Agent uses the one-liner before writing a class

"Review my diff"

/ponytail-review hands back a delete list with over-engineered items flagged

"Audit my whole repo"

/ponytail-audit scans the entire codebase, not just the diff

"What tech debt did you defer?"

/ponytail-debt harvests all ponytail: comments into a ledger

"Turn off ponytail"

/ponytail off disables it for the session

✅ Before you start

  • You have one of the 13 supported agents installed (see Installation)

  • For Claude Code and Codex: node is on your PATH (required for lifecycle hooks)

  • For Nix or nvm users: verify node is on the non-interactive shell's PATH, not just the interactive shell

  • No config file needed — ponytail ships zero required configuration

💻 Installation

Claude Code

bash

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Codex (CLI)

bash

codex plugin marketplace add DietrichGebert/ponytail
codex

Then open /plugins, select the Ponytail marketplace entry, and install Ponytail. Open /hooks, review and trust its two lifecycle hooks, and start a new thread.

Codex desktop app: restart the app after installing and it picks up the plugin automatically.

GitHub Copilot CLI

bash

copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail

In an interactive Copilot CLI session, use the slash equivalents:

bash

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Pi Agent Harness

bash

pi install git:github.com/DietrichGebert/ponytail

OpenCode

Run OpenCode from a checkout of this repo and add to opencode.json:

json

{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }

Gemini CLI

bash

gemini extensions install https://github.com/DietrichGebert/ponytail

Cursor, Windsurf, Cline, GitHub Copilot (editor), Aider, Kiro

Copy the matching rules file from the repo:

Agent

File to copy

Cursor

.cursor/rules/

Windsurf

.windsurf/rules/

Cline

.clinerules/

GitHub Copilot (editor)

.github/copilot-instructions.md

Aider

AGENTS.md

Kiro

.kiro/steering/ponytail.md

Kiro global install: copy .kiro/steering/ponytail.md to ~/.kiro/steering/

Copilot global install: copy the rules into ~/.copilot/copilot-instructions.md to run ponytail in every project

❝

⚠️ The copy-file adapters (Cursor, Windsurf, Cline, Copilot, Kiro, Antigravity) load the always-on ruleset but do NOT add plugin mode switches or commands. Commands require a skill-capable host: Claude Code, Codex, OpenCode, Gemini CLI, or pi.

Antigravity and VS Code with Codex Extension

Both agents read AGENTS.md automatically from the repo root. No extra setup needed when running from the repo directory.

For global Codex: ~/.codex/AGENTS.md For always-on Antigravity: .agents/rules/

🛠 Setup step by step

  1. Choose your agent from the list above

  2. Run the install command for your agent (or copy the rules file)

  3. For Claude Code and Codex: confirm node is on your PATH

  4. Start a new session or thread (required for hooks to activate)

  5. Look for startup text confirming the current mode — this confirms ponytail is active

  6. Run /ponytail with no argument to report the current intensity level

💬 Prompts to use it

Set intensity level

/ponytail lite
/ponytail full
/ponytail ultra
❝

⚠️ /ponytail ultra is for when the codebase has genuinely wronged you. Use deliberately.

Review current changes

/ponytail-review

Use this after writing a feature. Ponytail reviews the diff and returns a delete list — items that were over-engineered relative to what the task needed.

Audit the whole repo

/ponytail-audit

Full codebase scan, not just the diff. Surfaces accumulated over-engineering across the project.

Harvest deferred shortcuts

/ponytail-debt

Every shortcut ponytail takes is marked with a ponytail: comment in the code, naming what was deferred and what the upgrade path is. This command collects all of those comments into a single ledger so "later" does not become "never".

Disable for a session

/ponytail off

Check current mode

/ponytail

In Codex (use @ prefix)

@ponytail-review
@ponytail-audit

📋 Commands table

Command

What it does

/ponytail [lite|full|ultra|off]

Set intensity level or turn off. No argument reports current level.

/ponytail-review

Review current diff for over-engineering. Returns a delete list.

/ponytail-audit

Audit the full repo for over-engineering, not just the diff.

/ponytail-debt

Harvest all ponytail: deferred shortcuts into a ledger.

/ponytail-help

Quick reference for all commands above.

❝

⚠️ Commands require a skill-capable host: Claude Code, Codex, OpenCode, Gemini CLI, or pi. Cursor, Windsurf, Cline, Copilot (editor), Kiro, and Antigravity load the always-on ruleset only — no commands available.

📅 Daily workflow

Morning — starting a new feature:

  1. Open your agent session (ponytail activates on session start)

  2. Run /ponytail to confirm current mode

  3. Describe the feature to your agent as normal

  4. Watch the agent pause at each implementation decision and prefer native, stdlib, or existing deps first

During — building:

  1. Let the agent work

  2. Every shortcut taken appears as a ponytail: comment inline — do not remove these

  3. If the agent starts reaching for a new dependency, ask it to check what is already installed first

After — review:

  1. Run /ponytail-review on the finished diff

  2. Delete or simplify anything flagged

  3. Commit

Weekly — debt check:

  1. Run /ponytail-debt

  2. Review the ledger of deferred shortcuts

  3. Decide what to promote from shortcut to production-grade implementation

  4. Close what does not need promoting

💡 Tips

  • /ponytail ultra is not for daily use. It exists for cleanup sessions on legacy codebases where an unconstrained agent previously ran free. Use it intentionally, not as a default.

  • Do not remove ponytail: comments during development. They are your upgrade ledger. Remove them only after you have made a deliberate decision about each one via /ponytail-debt.

  • Nix and nvm users: ponytail's lifecycle hooks require node on the non-interactive shell PATH. If hooks are silently inactive, check your shell profile vs rc file setup. The skills still work — only the always-on activation goes quiet.

  • The benchmark is reproducible. Run npx promptfoo eval -c benchmarks/promptfooconfig.yaml to verify the numbers yourself. The method and raw data are open in benchmarks/.

  • Match mode to task. Use lite for greenfield work, full for features in existing codebases, ultra for refactoring or cleanup sessions.

  • For Cursor and Windsurf users: you get always-on rules but no command mode. If you want /ponytail-review, move your sessions to Claude Code or Gemini CLI for those passes.

🔧 Troubleshooting

Hooks are silent on startup (Claude Code or Codex)

Cause: node is not on the non-interactive shell's PATH. Fix: Add node to your shell profile (not just .bashrc or .zshrc if those only run for interactive shells). For nvm users: add the nvm init block to your non-interactive profile, or symlink node to /usr/local/bin.

Commands not recognized in Cursor or Windsurf

Cause: These agents load the rules file only. They do not support plugin command mode. Fix: This is expected behavior. Use /ponytail-review from Claude Code or Gemini CLI instead, or use the always-on rules for passive enforcement during normal prompting.

Agent ignores ponytail rules mid-session

Cause: Long sessions can dilute context. The rules file gets pushed out of the active window. Fix: Start a new session. For Claude Code and Codex, the lifecycle hooks re-inject the ruleset each turn — if they are active, this should not happen. Confirm hooks are trusted in /hooks.

npx promptfoo eval benchmark fails on CSV task

Cause: pandas is not installed locally. Fix:

bash

pip install pandas

The benchmark spawns Python for email and CSV checks. python3 is tried before python. Make sure one is on your PATH.

OpenCode not picking up ponytail rules

Cause: Not running OpenCode from the repo root, or opencode.json is missing the plugin entry. Fix: Confirm you are running from a checkout of the ponytail repo, and that opencode.json contains:

json

{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }

Note: OpenCode also auto-loads AGENTS.md, so the base rules apply even without the plugin.

⚡ Quick reference

# Claude Code
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

# Codex CLI
codex plugin marketplace add DietrichGebert/ponytail

# GitHub Copilot CLI
copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail

# Pi
pi install git:github.com/DietrichGebert/ponytail

# Gemini CLI
gemini extensions install https://github.com/DietrichGebert/ponytail

# OpenCode (add to opencode.json)
{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }

# Session commands (Claude Code, Codex, OpenCode, Gemini, pi)
/ponytail              → check current mode
/ponytail lite         → light enforcement
/ponytail full         → standard enforcement
/ponytail ultra        → maximum enforcement (for cleanup sessions)
/ponytail off          → disable for session
/ponytail-review       → review current diff, get delete list
/ponytail-audit        → full repo scan for over-engineering
/ponytail-debt         → harvest ponytail: comments into a ledger
/ponytail-help         → command reference

# Codex uses @ prefix
@ponytail-review
@ponytail-audit

By The AI Leverage - Learn and master AI daily

Keep Reading