How to Uninstall Ponytail from Codex: A Complete Two-Step Guide

To completely uninstall Ponytail from Codex, first run codex plugin remove ponytail to remove the plugin files, then execute node scripts/uninstall.js to delete residual configuration files from your home directory.

Ponytail is delivered to Codex as a plugin that registers lifecycle hooks (UserPromptSubmit and Task) and slash commands like /ponytail. While the standard Codex plugin manager handles the package removal, Ponytail writes user-specific configuration files outside its own directory, requiring a two-step process for a pristine uninstall.

Why Uninstalling Ponytail Requires Two Steps

Codex’s plugin system only deletes files that belong to the plugin package itself. However, according to the DietrichGebert/ponytail source code, the plugin creates state files in your home directory to persist settings across sessions. These include a mode-flag file, a JSON configuration, and a statusLine entry in Claude’s settings.

Because these files reside outside the plugin directory, the codex plugin remove command cannot touch them. Leaving them behind could affect future installations or leave stale configuration in your environment.

Step 1: Remove the Ponytail Plugin from Codex

First, tell Codex to stop loading the hooks and commands by removing the plugin registration.

codex plugin remove ponytail

This command is documented in the Uninstall table of the repository’s README.md. It removes the plugin entry from plugin.json and deletes the files under hooks/ and skills/ from Codex’s plugin directory.

Step 2: Clean Up Residual Configuration Files

After removing the plugin, you must delete three specific items that Ponytail created in your home directory:

• ~/.claude/.ponytail-active – A mode-flag file indicating active state
• ~/.config/ponytail/config.json – The main JSON configuration file
• statusLine entry in ~/.claude/settings.json – The injected status line configuration

Using the Provided Uninstall Script

Ponytail provides a Node.js cleanup script that safely removes these leftovers. Run it before you delete the plugin directory (or from a separate clone of the repository) to avoid erasing the script itself:

node scripts/uninstall.js

The script in scripts/uninstall.js checks for each file’s existence, removes them if present, and carefully parses ~/.claude/settings.json to strip only the Ponytail-owned statusLine segment while preserving any user-added commands.

Manual Cleanup (Alternative)

If you prefer to locate and delete the files manually, use the configuration helpers in hooks/ponytail-config.js to resolve the exact paths on your system:

// Find where Ponytail stores its config
const { getConfigPath, getClaudeDir } = require('./hooks/ponytail-config');
console.log('Config file:', getConfigPath());
console.log('Claude dir:', getClaudeDir());

Then remove the files manually:

rm ~/.claude/.ponytail-active
rm ~/.config/ponytail/config.json

# Edit ~/.claude/settings.json to remove the statusLine entry

What the Uninstall Script Does Under the Hood

The scripts/uninstall.js file imports path resolvers from hooks/ponytail-config.js, which exports getConfigPath() and getClaudeDir() to handle cross-platform path resolution. The script performs the following operations:

1. Validates file existence before attempting deletion to prevent errors
2. Parses JSON safely from ~/.claude/settings.json using standard Node.js file system methods
3. Surgically edits the settings file to remove only the Ponytail-specific statusLine property while maintaining JSON validity
4. Logs progress to stdout so you can verify which files were removed

This approach ensures that running node scripts/uninstall.js leaves your Codex configuration in a clean state without affecting other plugins or user customizations.

Summary

• Remove the plugin using codex plugin remove ponytail to stop Codex from loading the hooks and slash commands.
• Clean up state using node scripts/uninstall.js to delete the mode flag, config file, and statusLine entry that persist in your home directory.
• Key files involved in the process are scripts/uninstall.js (cleanup logic) and hooks/ponytail-config.js (path resolution).
• Manual deletion is possible but requires editing JSON files carefully to avoid syntax errors.

Frequently Asked Questions

Why doesn't codex plugin remove ponytail delete all the files?

The codex plugin remove command only removes files that are part of the plugin package itself—specifically the contents of the hooks/ and skills/ directories. Because Ponytail writes user-specific configuration to your home directory (as seen in hooks/ponytail-config.js), these files exist outside the plugin’s scope and must be removed separately.

What happens if I delete the plugin without running the cleanup script?

If you skip the cleanup step, the files ~/.claude/.ponytail-active, ~/.config/ponytail/config.json, and the statusLine entry in ~/.claude/settings.json will remain on your system. These orphaned files could cause conflicts if you reinstall Ponytail later or might leave stale configuration in your Claude environment.

Can I manually delete the configuration files instead of using the script?

Yes, you can manually delete the files using standard shell commands or file explorers. However, editing ~/.claude/settings.json requires care to avoid breaking JSON syntax. The scripts/uninstall.js script handles the parsing and editing safely, reducing the risk of configuration corruption.

Where does Ponytail store its configuration data?

Ponytail stores configuration in three locations outside the plugin directory: ~/.claude/.ponytail-active for mode flags, ~/.config/ponytail/config.json for user settings, and a statusLine entry inside ~/.claude/settings.json for UI integration. You can programmatically locate these paths using the getConfigPath() and getClaudeDir() functions exported from hooks/ponytail-config.js.

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