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

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

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:

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

• Codex:

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

• GitHub Copilot CLI:

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

• OpenCode: Add the following to your opencode.json:

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

3. Verify Hook Loading

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

!echo test

Check that the Ponytail status line appears (handled by 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:

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

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

export PONYTAIL_DEFAULT_MODE=full

Or create the config file at ~/.config/ponytail/config.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, an instruction-only fallback that agents read directly. Reference docs/agent-portability.md to verify whether your target platform requires the hooks/ integration or the AGENTS.md approach.

Host-Specific Hook Configurations

Certain hosts require additional hook configuration files. For example, Qoder uses hooks/qoder-hooks.json to register the lifecycle scripts. Check the 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 – 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 – Instruction-only ruleset for agents that cannot load runtime hooks.
• docs/agent-portability.md – Mapping document showing which hosts use hooks/ versus AGENTS.md.
• hooks/ponytail-statusline.sh – Shell script displaying the current Ponytail mode in the terminal.
• 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 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, Ponytail provides AGENTS.md, a markdown instruction file that these agents read directly. According to 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). Alternatively, execute /ponytail full and confirm the host acknowledges the mode change. If using an instruction-only agent, verify that 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.

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