agent-purge

Overview

agent-purge is a local CLI and web console for applying one shared persona across multiple coding agents. It unifies each harness's system-prompt entry point into install, shim, and slash channels, with replace, strict, append, and off modes that can be switched hot and reverted.

Key Features

• One persona file body is shared across managed coding-agent entry points.
• Four modes: replace, strict (persona only), append, and off; all can be switched hot and reverted.
• Three delivery channels: install writes managed config, hooks, or plugins; shim fronts same-name commands; slash commands switch in-session.
• A local web console and CLI list personas and show runtime harness support, versions, injection layer, and channel availability.
• Supports harnesses including Codex, Claude, Grok, OMP, Hermes, ZCode, OpenCode, OpenCode2, dsh, Pi, Antigravity, and CodeBuddy.
• An optional magpie gateway plugin rewrites the system segment for requests traversing the gateway.

Use Cases

• Maintain a consistent persona across Codex, Claude, and other coding agents without rewriting prompts per tool.
• Switch persona or mode for a single session with in-session slash commands while leaving disk unchanged.
• Use the local web console to choose personas and inspect runtime harness support and channel availability.
• Apply the current persona at a local magpie gateway for requests from multiple agents.

Getting Started

• Install globally with npm i -g agent-purge, or run npx agent-purge web.
• Run agent-purge web to open the local console on port 7788 and generate the persona directory; use agent-purge ls if you do not want the UI.
• Launch an agent with the current persona, such as agent-purge codex, or make a one-off query with agent-purge pi --ask.
• Manage personas with agent-purge ls, agent-purge use, or a one-run persona override.

Deployment & Requirements

• Node.js 20 or newer; zero dependencies.
• Data lives under ~/.agent-purge/ by default; set AGENT_PURGE_HOME to change the location.
• The optional magpie plugin is installed from the repository magpie-plugin directory, not from the npm package, and requires generated persona data via node magpie-plugin/gen-personas.mjs.
• For dsh, the cordis plugin is installed into desktop, web, and headless profiles and requires a restart once before hot updates.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• Closed-source desktop harnesses whose prompts live server-side or in binaries are launched as-is with no injection.
• OpenCode and OpenCode2 are separate npm packages with different plugin interfaces and independent support.
• The magpie gateway plugin is not part of the npm package and must be installed by repository path.
• The gateway plugin only rewrites text in the request body and cannot intercept content assembled client-side by the harness.
• Runtime state is stored locally and no data is uploaded.