File: README.md Copy Chapter

Ponytail

You know him. Long ponytail. Oval glasses. Has been at the company longer than the version control. You show him fifty lines; he looks at them, says nothing, and replaces them with one.

Ponytail puts him inside your AI agent.

Before / after Copy Chapter

You ask for a date picker. Your agent installs flatpickr, writes a wrapper component, adds a stylesheet, and starts a discussion about timezones.

With ponytail:

More survivors in examples/.

Numbers Copy Chapter

The honest measurement is a real agent doing real work: a headless Claude Code session editing tiangolo's full-stack-fastapi-template (a real FastAPI + React repo), scored on the git diff it leaves behind. Twelve feature tickets, the same agent with and without the skill, n=4, Haiku 4.5.

ponytail is the only arm that cuts every metric, and the only one that stays fully safe while doing it. The cut is biggest where there is a real over-build trap (date picker 404 to 23 lines, color picker 287 to 23, because it reaches for a native `` instead of a component) and near zero on code that is already minimal. Full method, per-task tables, and limitations: benchmarks/results/2026-06-18-agentic.md.

Older single-shot numbers (isolated generation)

Five everyday tasks, three models, three arms (no skill, caveman, ponytail), ten runs, median reported. One prompt, one completion, counting lines of the answer:

This showed 80-94% less code. #126 fairly pointed out that the bare-model baseline pads its answer with prose and options, so that gap is partly a conversational-baseline artifact. The agentic numbers above are the corrected, defensible version. Reproduce the single-shot run with npx promptfoo eval -c benchmarks/promptfooconfig.yaml.

The rule was never "fewest tokens." It is: write only what the task needs, and never cut validation, error handling, security, or accessibility. The code ends up small because it is necessary, not golfed. Lower cost and latency are a side effect on the models that follow the ladder; a terse reasoning model that spends thinking tokens deliberating the rungs can go the other way (on GPT-5.5 it does).

How it works Copy Chapter

Before writing code, the agent stops at the first rung that holds:

1. Does this need to exist?   → no: skip it (YAGNI)
2. Already in this codebase?  → reuse it, don't rewrite
3. Stdlib does it?            → use it
4. Native platform feature?   → use it
5. Installed dependency?      → use it
6. One line?                  → one line
7. Only then: the minimum that works

The ladder runs after it understands the problem, not instead of it: it reads the code the change touches and traces the real flow before picking a rung. Lazy about the solution, never about reading.

Lazy, not negligent: trust-boundary validation, data-loss handling, security, and accessibility are never on the chopping block.

Install Copy Chapter

The most effort ponytail will ever ask of you:

The Claude Code and Codex plugins run two tiny Node.js lifecycle hooks, so node needs to be on your PATH (note for Nix/nvm users: it must be on the non-interactive shell's PATH). If it isn't, the skills still work, the always-on activation just stays quiet instead of erroring on every prompt.

Claude Code Copy Section

/plugin marketplace add DietrichGebert/ponytail

/plugin install ponytail@ponytail

(You have to send two separate prompts for the install to work)

Same steps in the Claude Code Desktop app's Code tab: type the two /plugin commands above into the prompt box, or click the + button next to it, choose Plugins → Add plugin to browse your configured marketplaces, and manage marketplaces from Customize in the sidebar.

Codex Copy Section

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

Run codex and open /hooks, review and trust its two lifecycle hooks, and start a new thread.

This same install also covers the Codex desktop app: restart the app after installing and it picks up the plugin.

GitHub Copilot CLI Copy Section

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

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

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

Copilot CLI namespaces plugin commands by plugin name. For example:

/ponytail:ponytail ultra
/ponytail:ponytail-review

Pi agent harness Copy Section

pi install git:github.com/DietrichGebert/ponytail

OpenCode Copy Section

Add to opencode.json:

{ "plugin": ["@dietrichgebert/ponytail"] }

Run from a checkout instead (the plugin reuses hooks/ and skills/):

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

Injects the ruleset every turn at the active level; adds the /ponytail commands (see Commands). OpenCode also auto-loads this repo's AGENTS.md, so the rules hold even without the plugin. The plugin adds the lite/full/ultra/off levels.

The ./ path resolves against your project's opencode.json; to share one checkout across projects, point it at the absolute path of the .mjs instead (it finds its hooks/ and skills/ relative to its own file).

Gemini CLI Copy Section

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

Loads the ruleset as always-on context every session and registers the /ponytail commands; the skills/ ship too, activated when a task needs them.
The Gemini adapter intentionally does not ship a root hooks/hooks.json: Gemini auto-loads that path, while Ponytail's lifecycle hooks use Claude/Codex event names.

Qoder Copy Section

Qoder auto-loads AGENTS.md from the repo root as always-on context, so running ponytail from a checkout works with zero setup. For per-project rules, copy .qoder/rules/ponytail.md into your project's .qoder/rules/. The six ponytail skills (/ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain, /ponytail-help) are available via Qoder's Skill system; the plugin manifest at .qoder-plugin/plugin.json points at the skills/ directory.

For full plugin-tier support (automatic mode activation + ruleset injection on every prompt), add the hooks from hooks/qoder-hooks.json to your .qoder/settings.json. Replace PONYTAIL_DIR with the path to your ponytail checkout. Qoder's UserPromptSubmit hook activates the default mode on first prompt and injects the ruleset every turn; PreToolUse with task|Task matcher injects the ruleset into subagents. Level switches (/ponytail lite|full|ultra|off) work automatically.

Antigravity CLI Copy Section

Google is renaming Gemini CLI to Antigravity CLI (the agy binary); the same extension installs there:

agy plugin install https://github.com/DietrichGebert/ponytail

It reuses this repo's gemini-extension.json. One difference: Antigravity converts the /ponytail commands into skills, so you type them into the chat (e.g. /ponytail-review as a message) instead of picking them from a slash menu. Until the migration completes (around June 18, 2026), gemini extensions install still works too. To run it as an always-on rule instead, drop the ruleset into .agents/rules/.

Hermes Agent Copy Section

hermes plugins install DietrichGebert/ponytail --enable

Restart Hermes after installing. The plugin injects the active Ponytail mode before each LLM turn, registers the bundled skills as ponytail:<skill>, and adds /ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain, and /ponytail-help. In shared gateways, restrict /ponytail to trusted users with Hermes slash-command access controls; runtime mode is process-local.

CodeWhale Copy Section

Reads AGENTS.md from the project root, zero setup. Copy AGENTS.md to your project, or run codewhale from a checkout of this repo. That's it.

Swival Copy Section

Stage the collection in your library first, then add the skills you want:

swival skills add --global https://github.com/DietrichGebert/ponytail  # stage into ~/.config/swival/library
swival skills add ponytail                                             # install the collection into this project
swival skills add --global ponytail                                    # or activate it in every project

Swival also reads AGENTS.md from the project root and ~/.config/swival/AGENTS.md globally, the instruction-only fallback.

On the command line, use a $ prefix to explicitly activate a skill. For example: $ponytail-review.

Devin CLI Copy Section

devin plugins install DietrichGebert/ponytail

Installs ponytail as a Devin plugin; skills are available as /ponytail:ponytail, /ponytail:ponytail-review, and so on.

OpenClaw Copy Section

clawhub install ponytail

Installs ponytail as an OpenClaw skill from ClawHub; the review, audit, debt, gain, and help skills install the same way (clawhub install ponytail-review, and so on). OpenClaw applies it on coding tasks and also exposes it as a /ponytail command. Without ClawHub, copy .openclaw/skills/ponytail into ~/.openclaw/skills/.

Grok Build Copy Section

grok plugin install DietrichGebert/ponytail --trust

Enable the plugin (off by default): /plugins → Plugins → Space on ponytail, or in ~/.grok/config.toml:

[plugins]
enabled = ["ponytail"]

Start a new session (or reload plugins). Skills show as /ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain, /ponytail-help. Verify with grok inspect. Grok can auto-invoke ponytail for coding tasks from its skill description; use /ponytail (or /ponytail lite, /ponytail full, /ponytail ultra) when activation needs to be explicit. Grok lifecycle hooks are not used because their SessionStart output cannot inject instructions.

AGENTS.md still works instruction-only from a checkout without the plugin.

That was it. He'd be proud. He won't say it.

Active every session, with a handful of commands (see Commands). /ponytail ultra exists for when the codebase has wronged you personally. Startup and mode-change text shows the current mode.

Set the level for every new session with the PONYTAIL_DEFAULT_MODE env var (lite/full/ultra/off), or a defaultMode field in ~/.config/ponytail/config.json (%APPDATA%\ponytail\config.json on Windows). The default is full.

While active, the ruleset is also injected into every subagent spawned via the Agent tool. To scope that to specific agent types (say, keep it off read-only search agents), set the PONYTAIL_SUBAGENT_MATCHER env var to a regex tested against the subagent's agent_type. It is unanchored and case-insensitive: explore|general matches either, ^general$ is exact, and plugin agent types look like plugin:name. Unset means inject into every subagent (the default); an invalid regex, or a subagent whose type the platform doesn't report, also falls back to injecting.

Cursor, Windsurf, Cline, GitHub Copilot Chat (the VS Code, JetBrains, and Visual Studio editor extension, not the standalone Copilot CLI covered under Install), Aider, Kiro, Zed, CodeWhale, Swival, Qoder: copy the matching rules file from this repo (.cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md, AGENTS.md, .kiro/steering/, .qoder/rules/).

Kiro: copy .kiro/steering/ponytail.md to ~/.kiro/steering/ (global) or .kiro/steering/ in your project.

GitHub Copilot CLI fallback (instruction-only mode): it reads AGENTS.md and .github/copilot-instructions.md in a project, or copy the rules into ~/.copilot/copilot-instructions.md to run ponytail in every project. This path keeps always-on guidance, but does not add plugin mode switches or hooks.

VS Code with the Codex extension reads AGENTS.md, which this repo ships, so it works from the repo root with no setup (~/.codex/AGENTS.md makes Codex global).

JetBrains Junie can read AGENTS.md once you point it there in Settings → Tools → Junie → Project Settings → Guidelines Path (it is not automatic yet). This repo ships AGENTS.md; .junie/guidelines.md is Junie's legacy path.

Amp (Sourcegraph) reads AGENTS.md from the working directory and parent directories up to $HOME, which this repo ships, so it works with no setup (~/.config/amp/AGENTS.md works globally).

Jules (Google) reads AGENTS.md from the repository root, which this repo ships, so it picks up the ruleset with no setup.

Which files map to which agent: Agent portability.

Uninstall Copy Section

These remove the plugin's own files. They leave behind a small amount of state ponytail writes outside the plugin folder: the mode flag, ~/.config/ponytail/config.json, and (if you accepted the setup nudge) a statusLine entry in ~/.claude/settings.json. Run node scripts/uninstall.js to clean those up too. Run it before the host remove command above — the script is itself a plugin file, so removing the plugin first deletes it (or run it from a separate clone of this repo). It only removes the statusLine entry if it points at ponytail's own script, so a statusline you set up yourself is left untouched.

Commands Copy Chapter

Commands need a skill-capable host (Claude Code, Codex, Devin CLI, OpenCode, Gemini, pi, Swival, Hermes Agent, Qoder, Grok Build). In Codex they're skills, invoke with @ (@ponytail-review). The instruction-only adapters (Cursor, Windsurf, Cline, Copilot, Kiro, Antigravity) load the always-on ruleset without the commands.

Development Copy Chapter

When changing the compact rule text, keep the agent copies aligned:

node scripts/check-rule-copies.js
npm test

The OpenClaw skill package (.openclaw/skills/) is generated from skills/; rerun node scripts/build-openclaw-skills.js after changing a skill, the test suite fails if it is stale. To publish the skills to ClawHub, run clawhub login once, then node scripts/publish-openclaw-skills.js (it publishes all six at the package.json version; pass --dry-run to preview).

The correctness benchmark spawns Python for email and CSV checks; python3 is tried before python. CSV checks need pandas installed locally.

FAQ Copy Chapter

Can I use it with caveman?
Yes, and you should. Caveman shrinks what the agent says; ponytail shrinks what it builds. Different halves, no overlap: caveman leaves code byte-for-byte exact, ponytail stays out of the prose. Terse talk about minimal code.

Does it need a config file?
No. An optional ~/.config/ponytail/config.json or PONYTAIL_DEFAULT_MODE env var can set the default level, but nothing is required.

What if I really need the 120-line cache class?
You don't. Insist anyway and he'll build it. Slowly. Correctly. While looking at you.

Does it scale?
The code you never wrote scales infinitely. Zero bugs, zero CVEs, 100% uptime since forever.

Why "ponytail"?
You know exactly why.

Sponsors Copy Chapter

License Copy Chapter

MIT. The shortest license that works.

Star History Copy Chapter

File: benchmarks/README.md Copy Chapter

Benchmark

Three arms (no skill, caveman, ponytail), three models, five everyday tasks, 10 runs per cell, median reported. Code LOC is counted from fenced code blocks; tokens, cost, and latency come straight from the API.

Reproduce Copy Chapter

Claude (Haiku / Sonnet / Opus) Copy Section

Requires an Anthropic API key and Node.js ≥ 22.22.0 (promptfoo's engine constraint,
check with node --version and upgrade if needed):

cp ../.env.example .env      # add your ANTHROPIC_API_KEY
npx promptfoo@latest eval -c promptfooconfig.yaml --env-file ../.env --repeat 10
npx promptfoo@latest view

--env-file ../.env is required because promptfoo reads .env from the current
directory (benchmarks/), not the repo root where the file lives.

Local models via Ollama Copy Section

No API key or promptfoo required. Runs against any model served by Ollama:

ollama pull llama3.2          # or any other model
python benchmarks/benchmark-local.py --model llama3.2 --repeat 3

See benchmarks/results/2026-06-15-llama3.2-local.md for what to expect: the skill works
well on instruction-following models (Claude-class) but transfers poorly to small local
models where the multi-step decision ladder isn't reliably followed.

Tasks: email validator, JS debounce, CSV sum, React countdown, FastAPI rate-limit (see promptfooconfig.yaml). Single-shot completions, default temperature.

Median results (10 runs, 2026-06-13; cost re-verified at 30 runs, 2026-06-17) Copy Chapter

Code (lines)

Cost (USD, 5 tasks; 30 runs, 2026-06-17)

Latency (seconds, 5 tasks)

Versus baseline, ponytail writes 80-94% less code, costs 42-75% less, and runs 3-6x faster, on every Claude model. Cost re-verified at 30 reps, with OpenAI and Gemini arms, in results/2026-06-17-cost-verification.md.

Read this number honestly (updated 2026-06-18). The gap above is single-shot, against a bare
model that answers with several options plus commentary, so it counts prose, not just code, and
overstates the win. #126 was right about
that. The agentic benchmark re-runs the comparison as a real Claude Code session on a
real public repo: ponytail cuts 60-94% on features with an over-build trap (custom component
vs native input), is a wash on already-minimal code, never writes more, and stays 100% safe
while the bare "one-liner" prompt drops a guard. That is the honest, defensible number. See
results/2026-06-18-agentic.md.

Independent benchmarks Copy Chapter

Run by other people, not by us, on their own harnesses and machines. Linked for
transparency: the numbers are theirs, may shift between runs, and are corroboration
rather than official figures. Only plugin-installed runs are listed, since pasting
SKILL.md into a prompt is a rough approximation of full and skews the result.

Both land on the same split as the honesty note above: ponytail reliably writes less
code, and whether that saves money depends on the workload (big win on
over-build and blocked tasks, can cost more on large completion-forced agentic runs).

Metrics Copy Chapter

correctness.js extracts fenced code blocks and runs per-task checks (spawns Python/Node for email, debounce, CSV; structural regex for React and FastAPI). A broken one-liner that scores great on LOC will fail on correctness.

Note: The React countdown and FastAPI rate-limit checks are keyword/structural only (no runtime execution), so they verify plausible structure rather than full correctness. The email, debounce, and CSV checks execute the code.

Prerequisites Copy Section

Running the benchmark requires Python 3, pandas, and Node.js ≥ 22.22.0 (promptfoo's engine constraint; see Reproduce).

Notes Copy Chapter

• Caveman is a prose-compression skill (it leaves code "normal"), so it lands between baseline and ponytail on code size and wins mainly on prose tokens.
• Cost reflects single-shot calls (one prompt, one completion), not real multi-turn agent sessions. In a session the ruleset re-injects and the ladder deliberates every turn across many turns, so per-session cost can come out higher or lower than these numbers. Prompt caching offsets some of the re-injection, but a measured agentic A/B (#121) found ponytail can also raise tool calls and cost on completion-forced tasks. Treat these as generation numbers, not a session-cost promise.
• These are everyday tasks. For production-grade specs, where an unconstrained agent bloats much harder, see the writeups in results/.

File: docs/agent-portability.md Copy Chapter

Agent Portability

Ponytail is an agent-portable skill distribution. The skills in skills/ hold
the core behavior; host-specific files are adapters that make that behavior easy
to load in a given agent.

Supported Adapters Copy Chapter

Adapter Rule Copy Chapter

Keep adapters thin. When a host supports skills or hooks, point it at the
existing skills/ and hooks/ files. When a host only supports project
instructions, keep its copied rule text aligned with AGENTS.md.

Portable Behavior Copy Chapter

• skills/ponytail/SKILL.md: lazy senior dev mode
• skills/ponytail-review/SKILL.md: over-engineering review
• skills/ponytail-audit/SKILL.md: whole-repo over-engineering audit
• skills/ponytail-debt/SKILL.md: harvest ponytail: shortcuts into a tracked ledger
• skills/ponytail-gain/SKILL.md: measured-impact scoreboard from the benchmark
• skills/ponytail-help/SKILL.md: quick reference
• AGENTS.md: compact always-on instruction set for agents without skill support