Ponytail Cursor Setup with Hooks or Rules

The hooks path installs Ponytail entries into Cursor's hook configuration and keeps using scripts in your local checkout. The default is user scope, which can affect multiple projects. The project option writes into the current project's configuration instead. A rule at .cursor/rules/ponytail.mdc is a separate, rules-only alternative.

The upstream hooks implementation checks for an existing workspace Ponytail rule and avoids injecting the same guidance again. Do not combine paths to make the instruction “stronger.” Review which path actually provides the guidance, and preserve other Cursor hooks and project rules.

Sources: Ponytail Cursor setup, the upstream hooks contract, and Cursor's hooks and rules documentation. Host support for a mechanism does not establish that every Cursor surface triggers it.

Check that Git and Node are available, review the upstream script, and record the existing ~/.cursor/hooks.json configuration. Choose a stable local directory for the checkout. From its parent directory, the upstream installation path is:

git clone https://github.com/DietrichGebert/ponytail
node ponytail/scripts/cursor-hooks.js install

The clone command retrieves the repository's default branch at the time you run it. This guide's documented reference is version 5.3.2 at commit 09c434a; compare the downloaded version and its instructions before executing a newer script.

The default installer writes user-level hook entries. Keep the checkout at that path after installation, because the hook entries refer to its scripts. If you move it, reinstall from its new location. Open a new Cursor chat after installation.

For project scope, run the installer from the intended project directory, supplying the actual checkout path and --project. The target project is determined by the current working directory. Do not assume running that option inside the Ponytail checkout configures some other open project.

Our isolated macOS check installed project hooks, confirmed that unrelated hooks and settings were preserved, reinstalled without duplicate entries, and removed the Ponytail entries. A separate rules-only check confirmed the fixed file's contents, its always-apply setting, and restoration. We did not start a Cursor agent conversation or confirm that a rule or hook delivered its instructions to a model.

The installed Cursor desktop version was 2.3.35, whose runtime compatibility was not established by that configuration check. Also, --project changes the hooks configuration target; the upstream runtime can still keep state under the user's home directory. Project scope is not complete runtime isolation. The verification steps below remain necessary in a compatible live host.

If you prefer a project instruction file, follow the upstream rules setup for .cursor/rules/ponytail.mdc. Read the source rule and Cursor's loading behavior before adding it. Keep the rule's intended metadata and scope rather than pasting its text into an unrelated file and assuming it will load identically.

When the file already exists, compare and merge instead of overwriting. If you have other project rules, keep their requirements for architecture, error handling, tests, and accessibility. A compact coding preference is not a substitute for those contracts.

A rules-only path does not supply hooks mode state or the full review and audit skill collection. Use the agent's ordinary task instructions for a focused review, and do not copy Claude Code's slash commands into this setup as if they were available Cursor plugin commands.

1. Inspect the changed configuration and confirm that unrelated hook entries remain. Confirm the script path still exists.
2. Open a fresh chat in the intended project. A conversation opened before installation may not have run the required lifecycle.
3. For hooks, send a supported level message such as /ponytail lite. The upstream handles this as ordinary chat text, rather than a registered Cursor slash command.
4. For a rules-only setup, inspect the rule-loading information offered by Cursor. Do not expect a hooks mode message to control it.
5. Try a small task with a reusable existing helper. Read the patch and run the relevant checks before deciding whether the behavior is appropriate.

Record the Cursor version, operating system, scope, Ponytail checkout reference, and observed result. A test of one editor version is not verification of every desktop or cloud surface.

The fixed-version upstream contract does not provide Ponytail injection into Cursor subagents. Cursor cloud agents do not trigger the documented sessionStart path. Some context behavior depends on the Cursor client version. Do not infer that a successful local chat check proves the same behavior in a cloud agent or delegated session.

Hooks level messages support lite, full, ultra, and off, with the documented limitations. This does not establish support for the entire Claude Code review/audit command collection. Session level, persistent defaults, and static project rules are distinct controls; see levels and configuration before relying on them.

To update hooks, keep the checkout, review the intended upstream revision, then run its installer again. The upstream describes the installation as merging Ponytail's own entries rather than adding duplicates. Start a fresh chat and repeat verification after updating or moving the checkout.

From the checkout's parent directory, remove user hooks with:

node ponytail/scripts/cursor-hooks.js uninstall

If your current directory is the checkout itself, the relative path is node scripts/cursor-hooks.js uninstall. For project hooks, return to the same project directory, use the actual checkout script path, and include --project. Omitting that option targets the user configuration and will not remove the intended project entries.

For a newly added rules file, remove that file. For a merged rule, restore only the Ponytail changes or your saved version. Inspect the remaining configuration, restart the relevant session, and check that other rules and hooks still work. See the upstream installation and removal contract for scope details.