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

> Easily set up a new project with Ponytail. This zero-configuration guide shows how placing AGENTS.md in your root enables AI coding assistants to load safety-first rules automatically.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: getting-started
- Published: 2026-09-10

---

**Ponytail requires zero configuration for most AI coding assistants—simply placing the [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

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

```

Once installed, the [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/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:

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

```

For GitHub Copilot CLI:

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

```

### OpenCode

Configure OpenCode by modifying [`opencode.json`](https://github.com/DietrichGebert/ponytail/blob/main/opencode.json). Add the plugin to your configuration object:

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

```

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

### Gemini CLI and Antigravity CLI

Install via the extensions system:

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

```

For Antigravity CLI, which uses the same extension mechanism:

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

```

### Pi Agent Harness

Install directly from the Git repository:

```bash
pi install git:github.com/DietrichGebert/ponytail

```

### Qoder

Copy the rule files into your project structure:

```bash

# Copy rules

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

# Reference hooks in settings

```

Add [`hooks/qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/qoder-hooks.json) to your [`.qoder/settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/.qoder/settings.json) to activate the lifecycle integration.

### Manual Setup for Cursor, Windsurf, and Generic Agents

Hosts without plugin systems read [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash
export PONYTAIL_DEFAULT_MODE=full

```

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

```json
{
  "default_mode": "ultra"
}

```

The [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/examples/url-params.md) demonstrates using native `URLSearchParams` instead of the `query-string` npm package:

```javascript
// 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:

```bash
node scripts/uninstall.js

```

This script targets the specific paths defined in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) and removes all traces of the plugin from your system.

## Summary

- **Zero-configuration setup** is available by placing [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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.