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

> Uninstall Ponytail from Codex easily with this two-step guide. Remove plugin files and delete residual configurations to completely remove Ponytail.

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

---

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

```bash
codex plugin remove ponytail

```

This command is documented in the **Uninstall** table of the repository’s [`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md). It removes the plugin entry from [`plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash
node scripts/uninstall.js

```

The script in [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) to resolve the exact paths on your system:

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

```bash
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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) file imports path resolvers from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) (cleanup logic) and [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).