ZiChuanLan/agent-purge

If you run more than one coding agent and keep retyping the same instructions into each, agent-purge is worth a quick look — but treat it as a prompt-routing utility for locally installed tools, not a guarantee that every agent behaves identically afterwards.

The problem

Each coding agent reads system-level instructions from a different place: a launch flag, a config file, a plugin hook, or a runtime object. If you want the same working style applied across Codex, Claude Code, opencode and others, you either copy the text into several config files or paste the same context at the start of every session. agent-purge puts a persona in one Markdown file and routes it to each installed harness, so switching modes takes effect the next time you start a run rather than after hand-editing each tool. The practical result is one place to maintain the text and one switch to turn it on or off.

What's different

Rather than only wrapping commands, the project describes three channels that all point at the same persona body: install writes a managed block into the harness's config (persistent, and it applies even when someone else starts the agent), shim puts a same-named wrapper earlier in PATH so a bare command is forwarded through agent-purge, and slash toggles modes inside a running session without touching disk. That layering is the useful mechanism: you can prototype with the slash command and later persist the same text through install, and the README says --mode off or the web master switch restores the original state.

The console and ls are meant to report run-time truth — whether a harness is installed, its version, and which channels are available — while a static matrix.json holds the declared capability table, with run-time information taking precedence on conflict. The documented limitation is equally important: closed desktop clients whose prompts live on a server or inside a binary are launched as-is with a printed reason and no injection (support notes). That means coverage depends on the individual harness, not on the project's general promise.

Who should try it

This fits a developer who already has two or more supported local coding agents and wants a shared tone, safety clause or workflow note applied consistently, while keeping an easy path back to the original prompts. It is also reasonable for prompt-evaluation work on your own machine, which is the use the authors describe.

It is a poor fit if you work mainly through a vendor's desktop app with prompts served remotely, or if you expect the tool to enforce behavior across every agent you use. The documented per-harness channel availability is the deciding constraint there, so check the run-time channel report for the specific harness before building a workflow around it.

Requirements and limitations

Node 20 or newer is required, and the package advertises zero dependencies (installation). Data lives outside the package in ~/.agent-purge/ by default, holding state.json and the personas/ folder; an AGENT_PURGE_HOME environment variable relocates it, which matters if you plan to keep personas under your own backup or dotfile arrangement. The README notes that older 0.1.x data is migrated on first run with the original files left in place, so expect two copies after upgrading until you clean up.

The bigger ongoing constraint is maintenance alignment: install and shim layers hook into each harness's config or PATH, so a harness update that moves its config location may require re-checking the channel status. The README defines reversal through uninstall, disarm and off mode, but that describes the project's own cleanup path, not a warranty that third-party tools will read the restored state identically. The long legal and compliance section is aimed at limiting misuse, and it adds reading overhead rather than technical capabilities. The README also does not detail how each harness's prompt is merged when append mode is used, so validate the joined output on your setup before relying on it.

HotRepo's take

The only dated signal is a 2026-10-26 snapshot on the JavaScript NEW-REPOSITORY board (新项目榜, not the overall/daily Trending board), showing 163 total stars at #6 — a single observation, not daily growth. With one recorded date and no comparable daily-board history, HotRepo cannot judge whether interest persists; the repository was one day old at that snapshot. The idea is straightforward and the reversible modes are easy to understand, but breadth across harnesses is the risky part. Before adopting, check the run-time support report for the exact agent and version you use, and confirm that its available channel matches how you start that tool.