How to Set Up a New Project with Ponytail: A Zero-Configuration Guide

Ponytail requires zero configuration for most AI coding assistants—simply placing the AGENTS.md file from the DietrichGebert/ponytail repository in your project root allows compatible agents to automatically load the safety-first rule set.

Ponytail is a "lazy senior dev" plugin designed to inject minimal-code, safety-first coding standards into any AI assistant workflow. Setting up a new project requires no complex configuration for most users, as the repository ships with a plain-text instruction file that supported agents (Claude Code, Codex, GitHub Copilot CLI, and others) read automatically according to the source code in DietrichGebert/ponytail.

Understanding the Zero-Configuration Architecture

Ponytail operates on two integration tiers: an always-on ruleset for instruction-only hosts and an optional plugin system for hosts with native extension capabilities.

The Always-On Ruleset

The file AGENTS.md lives at the repository root and contains the complete Ponytail instruction set. For hosts that support instruction-only plugins—such as Cursor, Windsurf, Cline, CodeWhale, and Grok—simply copying this file into your project’s root directory or the host’s global configuration folder activates the ruleset immediately. No plugin.json manifest or additional dependencies are required for this tier.

Optional Plugin Integration

For hosts providing true plugin systems, Ponytail ships a minimal Node.js lifecycle hook located at hooks/ponytail-activate.js. This hook injects the ruleset at each turn and registers the /ponytail command namespace. The companion file hooks/ponytail-config.js handles configuration discovery, checking for the PONYTAIL_DEFAULT_MODE environment variable or a JSON configuration at ~/.config/ponytail/config.json.

Platform-Specific Setup Instructions

Claude Code

Add Ponytail via the marketplace and install the plugin:

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

Once installed, the hooks/ponytail-activate.js lifecycle hook runs automatically with every prompt. Change the intensity on the fly using /ponytail [lite|full|ultra|off].

Codex and GitHub Copilot CLI

For OpenAI Codex, use the CLI plugin commands:

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

For GitHub Copilot CLI:

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

OpenCode

Configure OpenCode by modifying opencode.json. Add the plugin to your configuration object:

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

Alternatively, reference a local checkout with "./.opencode/plugins/ponytail.mjs".

Gemini CLI and Antigravity CLI

Install via the extensions system:

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

For Antigravity CLI, which uses the same extension mechanism:

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

Pi Agent Harness

Install directly from the Git repository:

pi install git:github.com/DietrichGebert/ponytail

Qoder

Copy the rule files into your project structure:

# Copy rules

cp .qoder/rules/ponytail.md your-project/.qoder/rules/

# Reference hooks in settings

Add hooks/qoder-hooks.json to your .qoder/settings.json to activate the lifecycle integration.

Manual Setup for Cursor, Windsurf, and Generic Agents

Hosts without plugin systems read AGENTS.md directly. Copy the file from the repository root into your host’s global skills directory or your project root. The agents load these instructions automatically at session start.

Configuring Intensity Modes

Ponytail exposes four strictness levels controlled via the /ponytail command:

• lite: Minimal oversight for rapid prototyping
• full: Standard safety checks (default)
• ultra: Maximum strictness for critical code paths
• off: Disable rule injection temporarily

Set a persistent default by exporting the environment variable:

export PONYTAIL_DEFAULT_MODE=full

Or create the configuration file at ~/.config/ponytail/config.json:

{
  "default_mode": "ultra"
}

The hooks/ponytail-config.js module resolves these settings in order: explicit command override, environment variable, then configuration file.

Core Philosophy in Practice

Ponytail enforces a one-dependency rule, preferring standard library APIs over external packages. For example, the project documentation in examples/url-params.md demonstrates using native URLSearchParams instead of the query-string npm package:

// Ponytail-preferred approach—zero dependencies
const params = new URLSearchParams(location.search);
params.get('page');
params.getAll('tags');

const output = new URLSearchParams({ page: 2, sort: 'name' });
output.append('tags', 'js');
output.toString(); // "page=2&sort=name&tags=js"

This philosophy reduces supply chain attack surfaces and simplifies long-term maintenance.

Uninstalling Ponytail

To remove Ponytail completely, including persistent state such as mode flags and status-line entries, run the provided cleanup script:

node scripts/uninstall.js

This script targets the specific paths defined in hooks/ponytail-config.js and removes all traces of the plugin from your system.

Summary

• Zero-configuration setup is available by placing AGENTS.md in your project root for compatible agents.
• Native plugins exist for Claude Code, Codex, GitHub Copilot CLI, OpenCode, Gemini CLI, and others via hooks/ponytail-activate.js.
• Mode control operates via /ponytail commands, the PONYTAIL_DEFAULT_MODE environment variable, or ~/.config/ponytail/config.json.
• Standard-library-first coding standards are enforced, eliminating unnecessary dependencies.
• Complete removal is handled by scripts/uninstall.js.

Frequently Asked Questions

Does Ponytail require a configuration file to work?

No. According to the DietrichGebert/ponytail source code, the AGENTS.md file at the repository root provides a zero-configuration experience for most AI agents. Only advanced features like persistent default modes require the optional ~/.config/ponytail/config.json file.

How do I adjust the strictness of Ponytail's code review?

Use the /ponytail command followed by lite, full, ultra, or off to change intensity mid-session. For permanent changes, set the PONYTAIL_DEFAULT_MODE environment variable or modify ~/.config/ponytail/config.json as parsed by hooks/ponytail-config.js.

Which AI coding assistants automatically detect AGENTS.md?

Cursor, Windsurf, Cline, CodeWhale, Swival, Devin, OpenClaw, and Grok all read AGENTS.md from the project root without additional plugins. Claude Code, Codex, and GitHub Copilot CLI require explicit installation via their respective marketplace commands.

How do I completely remove Ponytail from my development environment?

Execute node scripts/uninstall.js from the repository root. This script cleans up mode flags, status-line entries, and any persistent state written by the plugin's lifecycle hooks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}