# How to Uninstall Ponytail and Clean Up Related Files

> Easily uninstall Ponytail and clean up related files. Run node scripts/uninstall.js before host plugin removal for a complete system cleanup.

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

---

**Run `node scripts/uninstall.js` to remove Ponytail's persistent state files before executing your host's plugin removal command to ensure complete cleanup.**

Uninstalling Ponytail requires more than a simple plugin removal command. Because the tool integrates with AI code assistants through Node.js lifecycle hooks and writes persistent state outside its plugin directory, you must follow a specific two-step process to fully uninstall Ponytail and eliminate all related configuration files from the DietrichGebert/ponytail repository.

## Step-by-Step Uninstallation Process

### Step 1: Execute the Cleanup Script

The utility script [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) removes external state files that host uninstall commands cannot reach. You must run this script before removing the plugin itself, otherwise the script gets deleted before it can execute.

The script performs three critical operations:

1. **Removes the mode flag file** located at `getClaudeDir()/.ponytail-active`, which stores your current intensity setting (`lite`, `full`, `ultra`, or `off`)

2. **Deletes the user configuration** at the path returned by `getConfigPath()` (typically `~/.config/ponytail/config.json` on Unix systems or the Windows equivalent)

3. **Cleans the Claude settings.json** by parsing the `statusLine.command` string, identifying the `ponytail-statusline` segment, and removing only Ponytail's entry while preserving other plugins' status line configurations

Execute the script from any repository clone:

```bash
node scripts/uninstall.js

```

### Step 2: Remove the Host Plugin Registration

After the cleanup script completes, run your specific AI assistant's removal command:

```bash

# Claude Code

/plugin remove ponytail

# OpenAI Codex CLI

codex plugin remove ponytail

# Cognition Devin CLI

devin plugins remove ponytail

# xAI Grok Build

grok plugin uninstall ponytail

# Inflection Pi agent

pi uninstall ponytail

```

For lightweight adapters (Cursor, Windsurf, Cline, Qoder), manually delete the rules file from your project directory:

```bash
rm .cursor/rules/ponytail.mdc

```

## What the Cleanup Script Targets

Understanding the specific artifacts targeted by [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) ensures you can verify complete removal. The script uses `removeIfExists()` to handle missing files gracefully.

The script targets these specific locations:

- **Mode flag**: `.ponytail-active` in Claude's plugin directory, tracked via `getClaudeDir()` from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)
- **Configuration**: User-level JSON at `~/.config/ponytail/config.json` 
- **Status line integration**: The `STATUSLINE_SCRIPT` segment within Claude's [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json), parsed and removed via string manipulation

The script implements defensive error handling in its `catch (e)` blocks, ignoring missing files, warning on malformed [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json), and re-throwing unexpected errors to prevent silent failures.

## Package Manager Alternative

If you installed Ponytail via npm, use standard package manager commands:

```bash
npm uninstall @dietrichgebert/ponytail

```

Note that npm uninstallation does not automatically trigger the cleanup script. You must still run `node scripts/uninstall.js` to remove the mode flag, config file, and status line entries from your AI assistant's configuration.

## Summary

- **Always run `node scripts/uninstall.js` first** to delete external state files including the `.ponytail-active` mode flag, user config, and status line entries
- The script uses `removeIfExists()` to safely handle missing files and preserves other plugins' status line configurations when editing [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json)
- Follow with host-specific removal commands such as `/plugin remove ponytail` or `codex plugin remove ponytail`
- Manual cleanup is required for lightweight adapters by deleting `.mdc` rule files from project directories like `.cursor/rules/`
- npm uninstallation of `@dietrichgebert/ponytail` requires separate execution of the cleanup script to remove persistent state

## Frequently Asked Questions

### What happens if I remove the host plugin before running the cleanup script?

If you execute the host removal command first, [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) gets deleted along with the plugin files, leaving the mode flag, config file, and status line entries orphaned on your system. You would need to manually delete `.ponytail-active` from Claude's directory, remove `~/.config/ponytail/config.json`, and edit [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json) to strip the Ponytail status segment using the logic found in the original script.

### Where does Ponytail store its configuration files?

According to the source code in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), Ponytail stores user configuration at the path returned by `getConfigPath()`, which resolves to `~/.config/ponytail/config.json` on Unix systems or the Windows equivalent. The mode flag is stored at `getClaudeDir()/.ponytail-active` within the Claude plugin directory. Both paths are computed at runtime based on the operating system and Claude's installation location.

### Does the cleanup script affect other Claude plugins?

No. The [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) specifically targets the `STATUSLINE_SCRIPT` segment containing `ponytail-statusline` within Claude's [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json). If other segments exist in the `statusLine.command` string, the script preserves them intact, removing only Ponytail's contribution to the status line while leaving other plugins' configurations untouched.

### How do I verify that Ponytail is completely removed?

Check that three specific artifacts no longer exist: the `.ponytail-active` file in Claude's directory (returned by `getClaudeDir()`), the `~/.config/ponytail/config.json` file (returned by `getConfigPath()`), and any reference to `ponytail-statusline` in your Claude [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json). Additionally, verify that the host no longer lists Ponytail in its active plugins via commands like `/plugin list` or `codex plugin list`.