# How to Migrate From Other AI-Coding Frameworks to Ponytail: A Complete Guide

> Easily migrate from other AI coding frameworks to Ponytail. Our complete guide simplifies the process, getting you started with Ponytail's powerful hook-based plugin and mode activation.

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

---

**Migrating to Ponytail requires removing your old framework’s plugin and installing Ponytail’s hook-based plugin for your specific host, then activating the desired mode with a slash command.**

Ponytail is a **"lazy senior dev"** plugin designed for AI-coding environments like Claude Code, Codex, and GitHub Copilot CLI. If you want to migrate from other frameworks to Ponytail, the process is straightforward because Ponytail uses reusable **hooks** and **skills** that work consistently across all supported hosts, eliminating the need to rewrite logic when switching platforms.

## Why Ponytail Migration Is Architecture-Simple

Ponytail’s core design philosophy eliminates migration friction. The same source files power every supported host, so you only swap installer commands rather than reconfiguring your entire workflow.

### The Hook-and-Skill Design

According to the **DietrichGebert/ponytail** source code, the framework relies on two reusable components:

- **`hooks/`** – Lifecycle scripts that inject the ruleset and register slash commands. In [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js), the runtime hook registers `/ponytail` commands and sets the current mode when the host starts a session.
- **`skills/`** – Implementation modules that execute specific commands. When you run `/ponytail-review`, the host forwards the call to `skills/ponytail-review.mjs`, which contains the actual review logic used across every platform.

This architecture means **no code duplication** occurs during migration. The **one-line-only ladder** (YAGNI → reuse → stdlib → one line) lives entirely inside these skill implementations, so your coding standards remain identical regardless of which AI host you use.

### Universal Configuration

Ponytail stores settings in **platform-agnostic** locations. You can configure the **mode switch**—which controls the aggressiveness of code trimming—via the `PONYTAIL_DEFAULT_MODE` environment variable or in `~/.config/ponytail/config.json`. These settings persist when you migrate between Claude Code, Codex, Gemini CLI, Pi agent, OpenCode, or other supported environments.

## Step-by-Step Migration Guide

Follow these seven steps to complete your Ponytail migration without touching your existing project files.

### 1. Remove the Previous Framework’s Plugin

Uninstall the old framework’s plugin using your current host’s removal command. For example, if migrating from a legacy Codex plugin:

```bash
codex plugin remove old-framework

```

Delete any leftover rule files the previous framework created, such as `.cursor/rules/old-framework.mdc` or similar project-specific configurations.

### 2. Install Ponytail for Your Target Host

Install Ponytail using your host’s specific marketplace commands:

- **Claude Code:**
  ```bash
  /plugin marketplace add DietrichGebert/ponytail
  /plugin install ponytail@ponytail
  ```

- **Codex:**
  ```bash
  codex plugin marketplace add DietrichGebert/ponytail
  codex plugin add ponytail@ponytail
  ```

- **GitHub Copilot CLI:**
  ```bash
  copilot plugin marketplace add DietrichGebert/ponytail
  copilot plugin install ponytail@ponytail
  ```

- **OpenCode:**
  Add the following to your [`opencode.json`](https://github.com/DietrichGebert/ponytail/blob/main/opencode.json):
  ```json
  {
    "plugin": ["@dietrichgebert/ponytail"]
  }
  ```

### 3. Verify Hook Loading

Run a harmless command to confirm Ponytail’s hooks are active:

```bash
!echo test

```

Check that the **Ponytail status line** appears (handled by [`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh) or `hooks/ponytail-statusline.ps1` on Windows), or verify that the ruleset has been injected into the session context.

### 4. Set the Operating Mode

Activate your desired mode immediately after installation:

```bash
/ponytail full

```

Available modes include `lite`, `full`, `ultra`, and `off`. Most projects benefit from `full` mode, which applies the complete **lazy senior dev** ladder.

### 5. Run a Sanity Check

Test the migration by running a Ponytail skill on a small diff:

```bash
/ponytail-review

```

Confirm that the output trims over-engineered code according to the YAGNI principles defined in the skill implementation.

### 6. Persist Your Configuration (Optional)

To maintain settings across sessions, add the environment variable to your shell profile:

```bash
export PONYTAIL_DEFAULT_MODE=full

```

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

```json
{
  "defaultMode": "lite"
}

```

### 7. Clean Up Legacy Files

Remove any remaining configuration files from the previous framework in your project directories to prevent rule conflicts.

## Post-Migration Configuration Details

After completing the migration, you may need to configure host-specific behaviors using Ponytail’s portability documentation.

### Handling Agent-Only Environments

Some agents like **Cursor**, **Windsurf**, and **Cline** cannot load plugins directly. For these environments, Ponytail provides **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)**, an instruction-only fallback that agents read directly. Reference [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) to verify whether your target platform requires the `hooks/` integration or the [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) approach.

### Host-Specific Hook Configurations

Certain hosts require additional hook configuration files. For example, **Qoder** uses [`hooks/qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/qoder-hooks.json) to register the lifecycle scripts. Check the [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md) file in the repository to confirm the exact integration method for your specific host.

## Key Source Files in the Ponytail Repository

Understanding these files helps troubleshoot migration issues:

- **[`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js)** – The main runtime hook that injects rulesets and registers slash commands across all plugin-capable hosts.
- **`skills/ponytail.mjs`** – Handles core mode-switch command processing (`/ponytail [mode]`).
- **`skills/ponytail-review.mjs`** – Implements the code review skill available after migration.
- **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)** – Instruction-only ruleset for agents that cannot load runtime hooks.
- **[`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md)** – Mapping document showing which hosts use `hooks/` versus [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md).
- **[`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh)** – Shell script displaying the current Ponytail mode in the terminal.
- **[`opencode.json`](https://github.com/DietrichGebert/ponytail/blob/main/opencode.json)** – Example configuration for OpenCode integration.

## Summary

- **Ponytail migration** involves removing your old framework’s plugin and installing Ponytail’s universal hooks for your specific AI-coding host.
- The **hook-and-skill architecture** ensures the same `skills/ponytail-review.mjs` and mode logic work across Claude Code, Codex, Copilot CLI, and other environments.
- Activate the framework using `/ponytail full` (or `lite`, `ultra`, `off`) and persist settings via `PONYTAIL_DEFAULT_MODE` or `~/.config/ponytail/config.json`.
- Agents without plugin support (Cursor, Windsurf, Cline) use **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)** instead of the runtime hooks.
- No project code changes are required; migration only affects the AI host’s configuration and lifecycle hooks.

## Frequently Asked Questions

### Do I need to rewrite my project code when migrating to Ponytail?

No. Ponytail operates as a **host-side plugin** that intercepts AI-generated code before it reaches your files. Your existing project code remains untouched. The framework only changes how the AI assistant generates new code or reviews diffs, applying the "lazy senior dev" ruleset through hooks and skills rather than modifying your codebase.

### Can I use Ponytail with agents that don't support plugins?

Yes. For agents like **Cursor**, **Windsurf**, and **Cline** that cannot load [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js), Ponytail provides **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)**, a markdown instruction file that these agents read directly. According to [`docs/agent-portability.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/agent-portability.md), this fallback delivers the same coding standards without requiring a runtime component, though you lose the dynamic mode-switching capabilities available in plugin-supported hosts.

### How do I verify that Ponytail is active after migration?

Run the command `!echo test` in your AI-coding interface and look for the **Ponytail status line** indicating the current mode (handled by [`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh)). Alternatively, execute `/ponytail full` and confirm the host acknowledges the mode change. If using an instruction-only agent, verify that [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) appears in the context window or system prompt.

### What happens if I switch between different AI coding hosts?

Because Ponytail stores configuration in `~/.config/ponytail/config.json` and respects the `PONYTAIL_DEFAULT_MODE` environment variable, your settings persist across host migrations. The **skills** (`skills/ponytail.mjs`, `skills/ponytail-review.mjs`) and **hooks** remain identical across Claude Code, Codex, Gemini CLI, and OpenCode, ensuring consistent behavior. You only need to repeat the installation step for the new host using the specific marketplace commands listed in the repository's [`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md).