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

To install Ponytail for instruction-only AI agents, copy the AGENTS.md file (or host-specific variants like .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 – The canonical rule set containing the full Ponytail policy and /ponytail commands, located at /AGENTS.md in the repository root.
• .github/copilot-instructions.md – A dedicated copy for GitHub Copilot CLI fallback scenarios, stored at .github/copilot-instructions.md.
• 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—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 in the project root or any parent directory.

# 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 or falls back to AGENTS.md.

# 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.

# 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 from accessible repository paths.

# 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:

/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.

Summary

• Instruction-only agents require only static rule files—no npm install or runtime hooks.
• Copy AGENTS.md to your project root for Cursor, Windsurf, Cline, and most adapters.
• Use .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 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 and .github/copilot-instructions.md?

They contain identical policy content, but .github/copilot-instructions.md follows the specific filename convention required by GitHub Copilot CLI when searching for project-specific instructions. 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 in your project root to cover Cursor, Windsurf, and Cline simultaneously, while also copying .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.

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