# How to Install Ponytail for Instruction-Only AI Agents: The Complete Setup Guide

> Install Ponytail for instruction-only AI agents by copying a single file. This guide provides the complete setup for your AI agent, requiring no complex installations or code changes.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-08-29

---

**To install Ponytail for instruction-only AI agents, copy the [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file (or host-specific variants like [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md)) into your project root or host configuration directory—no npm packages, runtime hooks, or code execution required.**

Ponytail from the DietrichGebert/ponytail repository provides a "lazy senior dev" policy system for AI coding agents. For instruction-only hosts such as Cursor, Windsurf, Cline, GitHub Copilot CLI, Kiro, and Antigravity, the installation is purely file-based—the agent reads static rules at startup without requiring JavaScript hooks or Node.js dependencies.

## Understanding the Instruction-Only Architecture

Ponytail is packaged as **always-on instruction files** rather than executable code for agents that consume static prompts. According to the repository structure, three core components provide the rule set:

- **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)** – The canonical rule set containing the full Ponytail policy and `/ponytail` commands, located at [`/AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main//AGENTS.md) in the repository root.
- **[`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md)** – A dedicated copy for GitHub Copilot CLI fallback scenarios, stored at [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md).
- **[`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md)** – Comprehensive installation documentation mapping host-specific requirements.

Because these agents operate in **instruction-only mode**, they inject the content of these markdown files directly into their context window. There is no need to run `node`, install npm packages, or configure the runtime hooks found in [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js)—that file is reserved for lifecycle-capable hosts like Claude or Codex.

## Installing Ponytail for Specific AI Agents

Each instruction-only agent reads rules from specific locations. Copy the appropriate file to activate the `/ponytail` command suite and policy enforcement.

### Cursor, Windsurf, and Cline

These editors automatically scan for [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) in the project root or any parent directory.

```bash

# Clone the repository adjacent to your project

git clone https://github.com/DietrichGebert/ponytail.git

# Copy the rule file to your project root

cp ponytail/AGENTS.md /path/to/your/project/

# Relaunch the editor to rescan the filesystem

```

The agent will load the rules on the next conversation initialization.

### GitHub Copilot CLI

The Copilot CLI checks for [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md) or falls back to [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md).

```bash

# From the Ponytail repository root:

cp .github/copilot-instructions.md /your/project/

# Or use the canonical name:

cp AGENTS.md /your/project/

# Start a new Copilot CLI session to load rules

copilot chat

```

### Kiro (Global Steering)

Kiro reads steering instructions from `~/.kiro/steering/` with any `.md` filename.

```bash

# Create the steering directory if needed

mkdir -p ~/.kiro/steering

# Copy with a descriptive name

cp AGENTS.md ~/.kiro/steering/ponytail.md

# Restart Kiro to apply the global rules

```

### Antigravity (Gemini CLI)

Antigravity automatically resolves [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) from accessible repository paths.

```bash

# Export the repository location

export PONYTAIL_REPO=$HOME/ponytail

# The CLI automatically reads $PONYTAIL_REPO/AGENTS.md

# No file copying required if the repo is accessible

```

## Verifying Your Installation

To confirm the instruction-only rules are active, trigger the status command:

```bash
/ponytail

```

If the agent responds with the current mode (defaulting to `full`), the Ponytail policy is loaded and the command suite is available. The agent should recognize the `/ponytail` prefix for all subsequent commands defined in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md).

## Summary

- **Instruction-only agents** require only static rule files—no `npm install` or runtime hooks.
- **Copy [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)** to your project root for Cursor, Windsurf, Cline, and most adapters.
- **Use [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md)** specifically for GitHub Copilot CLI setups.
- **Place rules in `~/.kiro/steering/`** for global Kiro configuration.
- **Restart the agent** after copying files to ensure the new context window includes the rules.

## Frequently Asked Questions

### Do I need to install Node.js or npm packages for instruction-only Ponytail?

No. Instruction-only agents read the static markdown files directly. The [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) file and any npm dependencies are only required for hosts that support lifecycle hooks and tool execution, such as Claude Code or Codex CLI. For Cursor, Windsurf, Copilot CLI, and similar agents, the installation is purely file-based.

### What is the difference between [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) and [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md)?

They contain identical policy content, but [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md) follows the specific filename convention required by GitHub Copilot CLI when searching for project-specific instructions. [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) is the canonical name used by Cursor, Windsurf, Cline, and most other instruction-only hosts. You can use either file for Copilot CLI, but the `.github/` location provides better organization.

### Can I use Ponytail with multiple agents on the same project?

Yes. Place [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) in your project root to cover Cursor, Windsurf, and Cline simultaneously, while also copying [`.github/copilot-instructions.md`](https://github.com/DietrichGebert/ponytail/blob/main/.github/copilot-instructions.md) for Copilot CLI compatibility. Multiple agents can read the same policy files without conflict, as they only read the instructions at startup and do not modify them.

### How do I update Ponytail rules when the repository changes?

Pull the latest changes from `DietrichGebert/ponytail`, then recopy the relevant files to your project or global configuration directories. Since instruction-only agents load rules at session start, you must **restart the agent** after updating the files to see new policy changes or command definitions.