agent-purge Tutorial: Centrally Manage Coding Agent System Prompts and Personas

What is agent-purge

agent-purge is a system prompt management tool for multiple Coding Agents. Different Agents may read prompts through startup arguments, configuration files, Hooks, or plugins. agent-purge encapsulates these differences, allowing users to inject, switch, and retract prompts around the same Persona content.

The project supports three modes:

• replace: Replaces the target system prompt with the Persona body.
• append: Appends the Persona body to the existing prompt.
• off: Disables injection and retracts the changes.

Modes can be switched at runtime. After disabling the Web global switch or using --mode off, the tool restores the related changes to their original state without leaving managed injection residue.

Core Mechanisms and Features

Three Unified Channels

agent-purge uses three channels to adapt to different Harnesses. All three channels ultimately use the body of the current personas/<id>.md file.

• install: Writes a managed configuration block to the target Harness, possibly using Markdown, Hooks, or a plugin mechanism. This is persistent configuration and also takes effect when someone else starts the corresponding Harness directly.
• shim: Places a wrapper with the same command name at the front of PATH, then forwards the call to agent-purge <h>, thereby taking over directly entered original commands.
• slash: Switches modes within a session using /purge on, /purge off, or /purge status without modifying disk configuration.

Localization and Reversibility

The project modifies only prompt-related locations. It does not modify binary files or crack or bypass authorization. State is stored locally in state.json and is never uploaded. You can restore the original state by uninstalling, releasing control, or disabling the mode.

agent-purge uninstall <h>
agent-purge disarm
agent-purge <h> --mode off

The channels supported by a specific Harness are determined by the runtime detection results on the local machine.

Prerequisites

Running agent-purge requires Node.js 20 or later. The project itself has zero dependencies. It can be installed globally through npm, or you can use npx to launch the Web console directly.

Installation and First Run

Method 1: Global Installation

npm i -g agent-purge

After installation, run:

agent-purge web

The default local console address is http://127.0.0.1:7788. Open this address in a browser to view and manage Personas, Harness status, and the global switch.

Method 2: Launch Through npx

If you do not want to install the package globally first, run:

npx agent-purge web

Data Directory

Configuration and Personas are not stored in the npm package directory, so upgrading the package will not overwrite user data. The default locations are:

• Linux and macOS: ~/.agent-purge/
• Windows: C:\Users\<your-user>\.agent-purge\

The directory mainly contains state.json and personas/. On the first run, the tool creates a starter template named neutral.md in the Personas directory.

If you previously used version 0.1.x, the first run of the new version automatically migrates the data previously located in the package directory while preserving the original files.

Custom Data Storage Location

You can specify an independent data directory through the AGENT_PURGE_HOME environment variable. This is useful for backing up Personas, separating work environments, or storing configuration on another disk.

Linux or macOS

export AGENT_PURGE_HOME=/path/to/your/data

Windows

setx AGENT_PURGE_HOME D:\ap-data

After setting it, run agent-purge in a new terminal session to ensure that the environment variable has taken effect.

Understanding and Managing Personas

Each Persona corresponds to a personas/<id>.md file. The file consists of Frontmatter and a body. The body is the content actually written to the system prompt.

Frontmatter supports the following fields:

• description: A description of the Persona, displayed in the Web list and in the output of agent-purge ls.
• desc: The legacy description field, still supported.
• order: Optional sorting information.
• harness: Optional Harness matching information.
• model: Optional model matching information.

When only the name and description are edited in the Web console, other Frontmatter keys are preserved rather than being overwritten wholesale.

List Personas

agent-purge ls

This command lists all Personas and marks the currently matched item. It also displays the Harness installation status, version, injection layer, and channel availability detected at runtime.

Switch the Current Persona

agent-purge use <id>

Here, <id> corresponds to the name identifier of a Persona file in the personas/ directory. After switching, subsequent managed calls use this Persona.

Specify a Persona for One Call Only

If you do not want to change the current global selection, specify another Persona only for the current call:

agent-purge pi --persona <id>

This is suitable for temporarily testing the effects of different prompts. After the call ends, this Persona will not become the default for subsequent calls.

Basic Usage Examples

Start the Web Console

agent-purge web

Then visit http://127.0.0.1:7788. The console can be used to view runtime status and operate the global switch. When the global switch is disabled, injection is retracted.

Start Codex with the Current Persona

agent-purge codex

agent-purge handles startup based on the corresponding Backend and the local runtime environment, and attempts to apply the current Persona through the mechanisms actually available in that Harness.

Ask pi a One-Time Question

agent-purge pi --ask "Please check the error-handling logic in this project"

This command starts one call with the current Persona and uses the content following --ask as the question for this round.

Switch Modes Within a Session

For Harnesses that support the Slash channel, use the following within a session:

/purge on
/purge status
/purge off

• /purge on: Enables Persona injection.
• /purge status: Displays the current status.
• /purge off: Disables injection without modifying disk configuration.

How to Confirm That Injection Really Took Effect

matrix.json stores the static capability matrix, but static declarations do not necessarily equal the actual state on the current machine. Version differences, installation methods, and changes within the Harness itself can all affect channel availability.

Therefore, check the runtime information provided by agent-purge ls or the Web console first. It reflects:

• Whether the Harness is installed.
• The detected Harness version.
• Whether the prompt is in the SYS or USER injection layer.
• Whether the install, shim, and slash channels are available.

When the static capability table conflicts with the runtime detection results, use the runtime results.

Advanced Usage Tips

Prepare Multiple Personas for Different Tasks

You can maintain multiple Markdown files under personas/, for example, separate files for code reviews, refactoring suggestions, or everyday development collaboration. Use description to clearly state each purpose and order to adjust the display order. When you need to limit the matching scope, use the harness or model field.

Before switching, run:

agent-purge ls

After confirming the target Persona, run:

agent-purge use <id>

Separate Persistent Configuration from Temporary Experiments

• When persistent activation is required, use the install channel supported by the target Harness.
• When you want directly entered original commands to also be handled by agent-purge, use the shim channel.
• When you only want to test in the current session, prefer the slash channel or the one-time --persona argument.

Whether a particular channel can be used still depends on the runtime detection results.

Keep a Recovery Path Before Making Changes

Although the project saves state and provides reversible operations, you should still confirm the current Persona, target Harness, and enabled mode before use. After testing, you can retract changes with:

agent-purge uninstall <h>
agent-purge disarm

You can also switch to --mode off or disable the global switch in the Web console.

Do Not Mistake an Unmodified Launch for Successful Injection

For closed-source desktop clients whose system prompts are located on the server or inside closed binaries, agent-purge only launches them unchanged and does not inject prompts. When running agent-purge <h>, the tool clearly outputs the reason injection is unavailable instead of pretending that it took effect.

Project Structure at a Glance

• bin/: CLI entry point.
• lib/: State, Persona, injection, channel, and detection logic.
• backends/: Startup arguments and identity handling for each Harness.
• web/: Local console, including server.mjs and ui.html.
• bench/: Injection success-rate tests and judge scripts, used only for development and not during normal operation.
• matrix.json: Static capability matrix.

Security, Privacy, and Compliance Boundaries

agent-purge is designed for official local Harnesses that users are authorized to manage, supporting prompt engineering and robustness evaluation. It does not modify binary files, bypass authorization, or upload local state externally, and it must not be used on unauthorized systems.

• Use only on devices, software, and compliant experimental environments that you are authorized to control.
• Do not use it for unauthorized attacks, vulnerability exploitation, data theft, unlawful intrusion, or malicious payload distribution.
• Do not violate applicable laws and regulations, model service terms, or abuse policies.
• The project is provided "as is" under the MIT License. Users are responsible for their own inputs, outputs, and use of the project.
• When borrowing the project's name, ideas, code, or prompts, provide attribution and identify the source as required by the repository notice.

The README also imposes strict restrictions on accessing servers and websites in specific regions. Before using the project, read the repository's disclaimers and compliance statements in full, and ensure that the scope of your operations meets their requirements.

Summary

agent-purge unifies inconsistent prompt entry points across multiple Coding Agents into concepts such as Persona, install, shim, and slash, while providing a Web console, runtime detection, and reversible rollback capabilities. To get started, install the tool, open the Web console, run agent-purge ls to check support, and then select a Persona to launch the target Harness. For temporary experiments, prefer a one-time Persona or hot session switching. For long-term configuration, enable persistent channels only after confirming runtime capabilities and compliance boundaries.