Merge branch 'main' into salaamdev/main
# Conflicts: # README.md
This commit is contained in:
Emeriko
@@ -14,17 +14,23 @@
|
||||
<p align="center">
|
||||
<img src="https://img.shields.io/github/stars/DietrichGebert/ponytail?style=flat-square&color=111111&label=stars" alt="Stars">
|
||||
<img src="https://img.shields.io/github/v/release/DietrichGebert/ponytail?style=flat-square&color=111111&label=release" alt="Release">
|
||||
<img src="https://img.shields.io/badge/works%20with-14%20agents-111111?style=flat-square" alt="Works with 14 agents">
|
||||
<img src="https://img.shields.io/npm/v/@dietrichgebert/ponytail?style=flat-square&color=111111&label=npm" alt="npm">
|
||||
<img src="https://img.shields.io/badge/works%20with-15%20agents-111111?style=flat-square" alt="Works with 15 agents">
|
||||
<img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://trendshift.io/repositories/50668" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/50668/daily" alt="DietrichGebert/ponytail | Trendshift" width="250" height="55"/></a>
|
||||
<a href="https://trendshift.io/repositories/50668" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/50668/weekly" alt="DietrichGebert/ponytail | Trendshift" width="250" height="55"/></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<strong>~54% less code (up to 94%) · ~20% cheaper · ~27% faster · 100% safe</strong><br>
|
||||
<sub>Measured on real Claude Code sessions editing a real open-source repo (FastAPI + React), against the same agent with no skill. ~54% is the mean across 12 feature tasks (Haiku 4.5, n=4); it reaches 94% where an agent over-builds (a date picker) and is near zero where the code is already minimal. ponytail keeps every safety guard while a bare "write one-liners" prompt drops one. (The earlier single-shot benchmark reported 80-94% as a flat figure; against a fair agentic baseline that is the per-task ceiling, not the average.) <a href="benchmarks/results/2026-06-18-agentic.md">Full writeup</a> · <a href="benchmarks/">reproduce it</a>.</sub>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<sub><a href="README.es.md">Español</a></sub>
|
||||
<sub><a href="README.es.md">Español</a> · <a href="README.ko.md">한국어</a></sub>
|
||||
</p>
|
||||
|
||||
---
|
||||
@@ -83,13 +89,16 @@ Before writing code, the agent stops at the first rung that holds:
|
||||
|
||||
```
|
||||
1. Does this need to exist? → no: skip it (YAGNI)
|
||||
2. Stdlib does it? → use it
|
||||
3. Native platform feature? → use it
|
||||
4. Installed dependency? → use it
|
||||
5. One line? → one line
|
||||
6. Only then: the minimum that works
|
||||
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
|
||||
@@ -102,8 +111,11 @@ The Claude Code and Codex plugins run two tiny Node.js lifecycle hooks, so `node
|
||||
|
||||
```
|
||||
/plugin marketplace add DietrichGebert/ponytail
|
||||
```
|
||||
```
|
||||
/plugin install ponytail@ponytail
|
||||
```
|
||||
(You have to send two separate prompts for the install to work)
|
||||
|
||||
The desktop app has no `/plugin` command. Install it from the UI instead: Customize, the + by personal plugins, Create plugin and add marketplace, Add from repository, then enter the repo URL (thanks @NiklasDHahn, #98).
|
||||
|
||||
@@ -148,7 +160,13 @@ pi install git:github.com/DietrichGebert/ponytail
|
||||
|
||||
### OpenCode
|
||||
|
||||
Run OpenCode from a checkout of this repo (the plugin reuses its `hooks/` and `skills/`), and add to `opencode.json`:
|
||||
Add to `opencode.json`:
|
||||
|
||||
```json
|
||||
{ "plugin": ["@dietrichgebert/ponytail"] }
|
||||
```
|
||||
|
||||
Run from a checkout instead (the plugin reuses `hooks/` and `skills/`):
|
||||
|
||||
```json
|
||||
{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }
|
||||
@@ -158,8 +176,6 @@ Injects the ruleset every turn at the active level; adds the `/ponytail` command
|
||||
|
||||
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).
|
||||
|
||||
The plugin path loads the ruleset everywhere, but the `/ponytail` commands are separate files in `.opencode/command/` that OpenCode only discovers from your project or the global commands dir. To use them outside this checkout, link them once: `ln -sf /absolute/path/to/ponytail/.opencode/command/* ~/.config/opencode/command/`.
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
```bash
|
||||
@@ -185,11 +201,26 @@ It reuses this repo's `gemini-extension.json`. One difference: Antigravity conve
|
||||
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`, and `/ponytail-help`. In shared gateways, restrict `/ponytail` to trusted users with Hermes slash-command access controls; runtime mode is process-local.
|
||||
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
|
||||
|
||||
Reads `AGENTS.md` from the project root, zero setup. Copy [`AGENTS.md`](AGENTS.md) to your project, or run `codewhale` from a checkout of this repo. That's it.
|
||||
|
||||
### Swival
|
||||
|
||||
Stage the collection in your library first, then add the skills you want:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
### OpenClaw
|
||||
|
||||
```bash
|
||||
@@ -204,7 +235,7 @@ Active every session, with a handful of commands (see [Commands](#commands)). `/
|
||||
|
||||
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`.
|
||||
|
||||
Cursor, Windsurf, Cline, GitHub Copilot (editor), Aider, Kiro, Zed, CodeWhale: copy the matching rules file from this repo ([`.cursor/rules/`](.cursor/rules/), [`.windsurf/rules/`](.windsurf/rules/), [`.clinerules/`](.clinerules/), [`.github/copilot-instructions.md`](.github/copilot-instructions.md), [`AGENTS.md`](AGENTS.md), [`.kiro/steering/`](.kiro/steering/)).
|
||||
Cursor, Windsurf, Cline, GitHub Copilot (editor), Aider, Kiro, Zed, CodeWhale, Swival: copy the matching rules file from this repo ([`.cursor/rules/`](.cursor/rules/), [`.windsurf/rules/`](.windsurf/rules/), [`.clinerules/`](.clinerules/), [`.github/copilot-instructions.md`](.github/copilot-instructions.md), [`AGENTS.md`](AGENTS.md), [`.kiro/steering/`](.kiro/steering/)).
|
||||
|
||||
Kiro: copy `.kiro/steering/ponytail.md` to `~/.kiro/steering/` (global) or `.kiro/steering/` in your project.
|
||||
|
||||
@@ -214,6 +245,17 @@ VS Code with the Codex extension reads `AGENTS.md`, which this repo ships, so it
|
||||
|
||||
Which files map to which agent: [Agent portability](docs/agent-portability.md).
|
||||
|
||||
### Uninstall
|
||||
|
||||
| Host | Command |
|
||||
|------|---------|
|
||||
| Claude Code | `/plugin remove ponytail` |
|
||||
| Codex | `codex plugin remove ponytail` |
|
||||
| Pi agent | `pi uninstall ponytail` |
|
||||
| Cursor / Windsurf / Cline / etc. | Delete the copied rule file |
|
||||
|
||||
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
|
||||
|
||||
| Command | What it does |
|
||||
@@ -225,7 +267,7 @@ Which files map to which agent: [Agent portability](docs/agent-portability.md).
|
||||
| `/ponytail-gain` | Show the measured impact scoreboard (less code, less cost, more speed) from the benchmark. |
|
||||
| `/ponytail-help` | Quick reference for the commands above. |
|
||||
|
||||
Commands need a command/skill-capable host (Claude Code, Codex, OpenCode, Gemini, pi, Hermes Agent). 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.
|
||||
Commands need a skill-capable host (Claude Code, Codex, OpenCode, Gemini, pi, Swival, Hermes Agent). 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
|
||||
|
||||
@@ -236,7 +278,7 @@ 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.
|
||||
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.
|
||||
|
||||
@@ -257,3 +299,13 @@ You know exactly why.
|
||||
## License
|
||||
|
||||
[MIT](LICENSE). The shortest license that works.
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://www.star-history.com/dietrichgebert/ponytail#history">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=DietrichGebert/ponytail&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=DietrichGebert/ponytail&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=DietrichGebert/ponytail&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
Reference in New Issue
Block a user