DietrichGebert/ponytail instruction manual

1. Purpose, Claude Code classification, and operating principle

Ponytail is an MIT-licensed instruction package for coding agents. Its purpose is to reduce unnecessary implementation while preserving correctness-critical work. For Claude Code, classify it primarily as a **Claude extension using context injection**, with **lifecycle-hook activation** and bundled skills/commands. It also has a separate MCP tool surface for hosts that cannot keep instructions always active. Setup effort is low for the Claude Code plugin, although automatic activation requires `node` on the non-interactive shell’s `PATH`.

The central decision ladder is: first decide whether the requested code needs to exist; then look for an existing project helper or pattern; then prefer the standard library, a native platform feature, or an already-installed dependency; use a one-line solution when appropriate; only after those options fail, write the minimum implementation that works. The agent must understand the task and trace the affected flow before applying this ladder. For bug fixes, it should find callers and repair the shared root cause rather than patching one reported symptom.

Minimalism has explicit limits. Ponytail must not remove trust-boundary validation, data-loss-preventing error handling, security measures, accessibility basics, hardware calibration controls, or anything the user explicitly requires. Non-trivial logic should leave one small runnable check; trivial one-liners need no test. A documented native-platform example is:

<!-- ponytail: browser has one -->
<input type="date">

2. Install and activate in Claude Code

Install from the Claude Code prompt box using two separate prompts:

/plugin marketplace add DietrichGebert/ponytail

/plugin install ponytail@ponytail

The same commands are documented for the Claude Code Desktop app’s Code tab. Alternatively, use the **+** button beside the prompt, choose **Plugins → Add plugin** to browse configured marketplaces, and manage marketplaces from **Customize** in the sidebar.

The Claude Code plugin includes instructions and lifecycle hooks. Its two small Node.js hooks activate the selected mode and keep the rules present. Therefore, `node` must be available on the `PATH` seen by non-interactive shells, which matters for Nix and nvm setups. If Node is unavailable, the skills still work, but always-on activation remains quiet. The rules are also injected into subagents created through the Agent tool.

Ponytail defaults to `full`. Set a different mode for new sessions with `PONYTAIL_DEFAULT_MODE` using `lite`, `full`, `ultra`, or `off`, or place a `defaultMode` field in `~/.config/ponytail/config.json`; on Windows the path is `%APPDATA%\ponytail\config.json`. No configuration file is required.

To limit subagent injection, set `PONYTAIL_SUBAGENT_MATCHER` to a case-insensitive, unanchored regular expression tested against `agent_type`. Documented patterns include `explore|general` and exact `^general$`; plugin types resemble `plugin:name`. Unset, invalid, or unavailable type information falls back to injection.

3. Modes and all six user commands

`/ponytail` controls intensity. With no argument it reports the current level; with an argument it changes or disables the mode:

/ponytail lite
/ponytail full
/ponytail ultra
/ponytail off

`lite` builds what was requested but names a lazier alternative in one line. `full`, the default, enforces the complete ladder and favors standard-library/native solutions and the shortest correct diff. `ultra` challenges speculative requirements most aggressively and prefers deletion before addition. The skill also documents “stop ponytail” or “normal mode” as ways to revert within its conversational behavior.

The remaining commands are:

• `/ponytail-review`: inspect the current diff for over-engineering and return a deletion list.
• `/ponytail-audit`: inspect the entire repository rather than only the diff.
• `/ponytail-debt`: collect deferred simplifications marked by `ponytail:` comments into a ledger.
• `/ponytail-gain`: show the benchmark impact scoreboard for code, cost, and speed.
• `/ponytail-help`: display a quick command reference.

These commands require a skill-capable host. On Codex they are skills invoked with `@`, for example `@ponytail-review`. Copilot CLI namespaces them by plugin name:

/ponytail:ponytail ultra
/ponytail:ponytail-review

A deliberate simplification with a known limit should receive a `ponytail:` comment naming both the ceiling and upgrade path, such as the documented pattern `# ponytail: global lock, per-account locks if throughput matters`.

4. Plugin installation on other supported agent hosts

The repository documents these host-specific installs:

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail
copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail
pi install git:github.com/DietrichGebert/ponytail
gemini extensions install https://github.com/DietrichGebert/ponytail
agy plugin install https://github.com/DietrichGebert/ponytail
hermes plugins install DietrichGebert/ponytail --enable
devin plugins install DietrichGebert/ponytail
clawhub install ponytail
grok plugin install DietrichGebert/ponytail --trust

For Codex, run `codex`, open `/hooks`, review and trust both hooks, and start a new thread; restart the desktop app after installation. Gemini loads the rules every session and registers commands. Antigravity turns commands into chat-invoked skills. Restart Hermes after installation; in shared gateways, restrict `/ponytail` to trusted users because its runtime mode is process-local. Devin exposes names such as `/ponytail:ponytail-review`. OpenClaw installs each skill separately when needed, for example `clawhub install ponytail-review`.

Grok plugins start disabled. Enable Ponytail through `/plugins`, or add:

[plugins]
enabled = ["ponytail"]

Then start a new session or reload plugins and verify with `grok inspect`.

Swival stages and activates the collection as follows:

swival skills add --global https://github.com/DietrichGebert/ponytail
swival skills add ponytail
swival skills add --global ponytail

The second command is project-local; the third is global. Explicitly invoke a Swival skill with a `$` prefix, such as `$ponytail-review`.

5. OpenCode, Qoder, and instruction-only portability

For OpenCode, add the published package to `opencode.json`:

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

To use a checkout instead:

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

The relative path resolves from the project’s `opencode.json`. An absolute `.mjs` path can share one checkout across projects. The plugin injects the active rules each turn and adds mode switching and commands; OpenCode can also read `AGENTS.md` without the plugin.

Qoder likewise reads root `AGENTS.md`. For project rules, copy `.qoder/rules/ponytail.md` into the project’s `.qoder/rules/`. Its manifest exposes the six skills. Full plugin-tier behavior requires adding the entries from `hooks/qoder-hooks.json` to `.qoder/settings.json` and replacing `PONYTAIL_DIR` with the checkout path; this adds prompt and subagent injection.

Instruction-only operation is available by copying the matching first-party rule file for Cursor, Windsurf, Cline, GitHub Copilot editor extensions, Aider, Kiro, Zed, CodeWhale, and related `AGENTS.md` readers. Kiro accepts `.kiro/steering/ponytail.md` globally in `~/.kiro/steering/` or per project. Copilot CLI can read project `AGENTS.md` or `.github/copilot-instructions.md`, or global `~/.copilot/copilot-instructions.md`. VS Code’s Codex extension can use root `AGENTS.md` or global `~/.codex/AGENTS.md`. Junie requires selecting `AGENTS.md` as its Guidelines Path. Amp, Jules, CodeWhale, and Swival also document `AGENTS.md`-based operation. These fallbacks supply guidance but not plugin hooks or mode switches.

6. MCP server for prompt- or tool-driven hosts

`ponytail-mcp` serves the same instruction text through the Model Context Protocol. It is a fallback for hosts whose available injection point is a prompt menu or tool call; it does not replace always-on adapters because MCP has no portable way to inject instructions every turn.

It exposes two read-only interfaces. Prompt `ponytail` returns the rules as a user message and accepts optional mode `lite`, `full`, or `ultra`; omitting the mode uses the configured default. Tool `ponytail_instructions` returns the same text plus structured content shaped as `{ mode, instructions }`. Both reuse the normal `PONYTAIL_DEFAULT_MODE` and Ponytail config-file resolution.

Install dependencies and run the stdio server exactly as documented:

cd ponytail-mcp
npm install
node index.js

A documented client entry is:

{ "mcpServers": { "ponytail": { "command": "node", "args": ["ponytail-mcp/index.js"] } } }

The path must make sense from the MCP host’s working directory; the repository does not document any alternative launch command. Run the MCP package’s tests from `ponytail-mcp` with:

npm test

Those tests cover mode resolution and instruction text. The server wiring maps the prompt and tool to the shared instruction-building function, keeping MCP output aligned with the lifecycle-hook and Pi instruction rules.

7. Removal, residual state, and compatibility boundaries

Use the documented host removal command:

/plugin remove ponytail

codex plugin remove ponytail
devin plugins remove ponytail
grok plugin uninstall ponytail
pi uninstall ponytail

For copy-based integrations such as Cursor, Windsurf, Cline, and Qoder, delete the copied rule file. Plugin removal leaves some possible state outside the plugin directory: the current mode flag, `~/.config/ponytail/config.json`, and—if the setup suggestion was accepted—a Ponytail `statusLine` entry in `~/.claude/settings.json`.

To remove that state, run this **before** uninstalling the host plugin, because the script is part of the plugin:

node scripts/uninstall.js

It may instead be run from a separate repository clone. The script removes a status-line setting only when it points to Ponytail’s own script; an independently configured status line is preserved.

Important boundaries: instruction-only adapters do not supply commands, hooks, or runtime mode switching. Automatic Claude Code and Codex activation depends on Node being visible to lifecycle hooks. MCP prompts are user-invoked rather than always active. The rules guide an agent but do not prove that every generated change is minimal, correct, secure, or production-ready. The repository specifically says safety checks are a floor, not proof of security. It also cautions that cost may rise on large completion-forced agentic tasks even when generated code becomes leaner.

8. Benchmarks: what is measured and how to reproduce it

The repository has single-shot and agentic benchmarks. The single-shot suite compares no skill, Caveman, and Ponytail across five tasks. Its `loc` metric always passes and records fenced-code line count; `correct` is a gate. Email, debounce, and CSV code execute, while React countdown and FastAPI rate-limit checks are structural. Prerequisites are Python 3, pandas, and Node.js 22.22.0 or newer.

From `benchmarks/`, reproduce the Claude run with an Anthropic key placed in `.env`:

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

For an Ollama-served local model:

ollama pull llama3.2
python benchmarks/benchmark-local.py --model llama3.2 --repeat 3

The documentation warns that the older 80–94% code reduction is inflated by conversational output. Its preferred agentic result reports a 54% mean LOC reduction over 12 feature tasks, with 22% fewer tokens, 20% lower cost, and 27% less time for the stated Haiku 4.5 run; these are repository-reported measurements, not guarantees.

The agentic harness uses real temporary repositories. First validate deterministic instruments without an API call:

python run.py --selftest

Its over-engineering judge and completeness judge have separate gates:

python judge.py --selftest
python judge.py --run runs/<stamp>
python complete.py --selftest-offline
python complete.py --selftest
python complete.py --run runs/<stamp>
python run.py --rescore runs/<stamp>

The two LLM judges use fixed rubrics; preserved workspaces allow offline rescoring.

9. Repository maintenance, validation, publication, and license

When changing the compact rule text, maintainers should verify that agent-specific copies remain synchronized and run the complete package tests:

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

The root test script runs Node tests, then tests in `pi-extension`, then tests in `ponytail-mcp`. The OpenClaw package under `.openclaw/skills/` is generated from `skills/`; after changing a skill, rebuild it with:

node scripts/build-openclaw-skills.js

The suite is documented to fail when generated OpenClaw skills are stale. To publish all six skills at the version in `package.json`, authenticate once and run:

clawhub login
node scripts/publish-openclaw-skills.js

Preview that publication without publishing by passing the documented option:

node scripts/publish-openclaw-skills.js --dry-run

The correctness benchmark starts Python for email and CSV checks, trying `python3` before `python`; CSV checks need locally installed pandas. The repository’s older isolated-generation benchmark can also be run from the repository context with the documented command `npx promptfoo eval -c benchmarks/promptfooconfig.yaml`, while the benchmark manual’s pinned `promptfoo@latest`, environment-file, and repetition form is the more fully specified reproduction procedure.

Ponytail is versioned as `4.9.0` in the supplied package and Codex plugin manifests and is licensed under the MIT License. The public project homepage is `https://github.com/DietrichGebert/ponytail`, with repository issues used for bug tracking.