ZiChuanLan/agent-purge

What it claims

agent-purge is an MIT-licensed tool that keeps persona prompts as Markdown files in ~/.agent-purge/personas/ and feeds them to several coding agents through four separate delivery channels. The page draws a clear line between "config written", "tests passed historically" and "actually in effect in the current session". Same-session hot switching is verified only for pi/omp, OpenCode, DSH and PI-Desktop. For Codex, Claude Code, CodeBuddy, Grok and WorkBuddy, only the launch path is verified.

How it works

Only the persona body becomes prompt text. The id, name and description front matter is used for management only, and the legacy key desc still works. The four channels differ in when changes take effect:

• install writes managed config or a plugin into the host. Static config needs a new session; a loaded dynamic plugin reads changes on the next turn.
• shim forwards a same-named command on PATH, so it applies the next time that command is launched.
• slash adds an in-session /purge extension, which depends on the host's extension support.
• project writes a rules file into a chosen directory, which applies to new sessions there.

arm <host> tries the resident, command and slash channels and reports each result. The project channel is chosen separately. Enabling several channels for one persona can deliver it more than once.

replace identifies the host's identity line approximately. Where the host text cannot be read, it falls back to strict. strict does not mean the model sees only the persona: hosts can still add text, and the persona may land as a system, developer or project-context message.

Evidence

Verified host versions on the page:

• pi 1.4.0 and omp 18.14.1
• OpenCode 1.19.5 and 2.2.5
• DSH 0.2.1-rc.5
• Codex 0.166.0
• Claude Code 2.1.316
• CodeBuddy 2.179.0
• Grok 1.0.73
• Kilo Code CLI 7.8.18
• WorkBuddy 5.9.3
• PI-Desktop 0.21.0

Kilo Code is the only host listed with real packet captures across all four modes. Regression testing covers Windows and WSL/Linux. The page does not count Hermes, zcode or antigravity as passing, and it does not accept a model's self-reported identity as proof.

How to use it

npm install -g agent-purge
agent-purge web

Use npx agent-purge web to skip a global install, or agent-purge web --no-open over SSH or WSL. Per-agent and one-off use:

agent-purge use <id> --for codex
agent-purge use follow --for codex
agent-purge codex --mode append
agent-purge pi --ask "解释这段代码"
agent-purge codex -- --help
agent-purge install codex
agent-purge arm pi --slash
agent-purge project on pi --dir /path/to/project
agent-purge status

To undo changes, pause/resume, uninstall <h>, disarm <h> and clean all keep personas. Run clean before npm uninstall -g agent-purge. self-uninstall --yes is a different, destructive operation.

Windows builds come in three forms. The setup.exe installer and the ZIP both need an external Node.js 20+, and the ZIP's EXE is only a thin launcher. The standalone agent-purge.exe bundles its own runtime. Builds may be unsigned, so check the SHA-256 before running them. AGENT_PURGE_HOME relocates the data directory. To develop on the tool, run npm ci --ignore-scripts, npm run check:repo and npm test.

Limits

macOS has not been tested on real hardware. Hot switching is unverified for Codex and Claude Code, and the first install or any plugin update still needs a host reload. Personas are sent to each host's model provider, and update checks contact GitHub, so secrets do not belong in persona text. Content already sent in past sessions cannot be recalled. If a restore conflicts, keep the reported files and restore records and do not delete backups. The web console listens only on 127.0.0.1 and should not be exposed to the internet. An optional magpie gateway plugin lives in magpie-plugin/, not the repository root.