agent-purge とは
agent-purge は、複数の Coding Agent を対象としたシステムプロンプト管理ツールです。Agent によって、起動引数、設定ファイル、Hook、プラグインなど、プロンプトの読み込み方法は異なります。agent-purge はこれらの違いを吸収し、同じ Persona の内容を基準に注入、切り替え、撤回を行えるようにします。
このプロジェクトは、次の 3 つのモードに対応しています。
- replace：Persona 本文で対象のシステムプロンプトを置き換えます。
- append：Persona 本文を既存のプロンプトに追加します。
- off：注入を無効にし、変更を撤回します。
モードはリアルタイムで切り替えられます。Web の全体スイッチをオフにするか --mode off を使用すると、ツールは関連する変更を元の状態に戻し、管理対象の注入の残骸を残しません。
コアの仕組みと機能
3 つの統一チャンネル
agent-purge は、異なる Harness に対応するために 3 つのチャンネルを使用します。3 層のチャンネルはいずれも、現在の personas/<id>.md ファイルの本文を使用します。
- install：対象 Harness に管理対象の設定ブロックを書き込みます。Markdown、Hooks、プラグインなどの仕組みが使われる場合があります。常駐設定に該当するため、他のユーザーが対応する Harness を直接起動した場合にも有効になります。
- shim：同名のコマンドシェルを
PATHの先頭に配置し、呼び出しをagent-purge <h>に転送することで、直接入力された元のコマンドを引き継ぎます。 - slash：セッション中に
/purge on、/purge off、/purge statusを使用してリアルタイムに切り替えます。ディスク上の設定は変更しません。
ローカル処理と可逆性
プロジェクトはプロンプトに関係する箇所だけを変更し、バイナリファイルの変更、認証の解除や回避は行いません。状態はローカルの state.json に保存され、アップロードされることはありません。アンインストール、引き継ぎの解除、モードの無効化によって元の状態に戻せます。
agent-purge uninstall <h>
agent-purge disarm
agent-purge <h> --mode off対応する Harness と利用可能なチャンネルは、ローカル環境での実行時検出結果を基準にしてください。
インストール要件
agent-purge の実行には Node.js 20 以上が必要です。プロジェクト自体に依存関係はなく、npm でグローバルインストールすることも、npx で Web コンソールを直接起動することもできます。
インストールと初回起動
方法 1：グローバルインストール
npm i -g agent-purgeインストールが完了したら、次のコマンドを直接実行できます。
agent-purge webローカルコンソールのデフォルトアドレスは http://127.0.0.1:7788 です。ブラウザーでこのアドレスを開くと、Persona、Harness の状態、全体スイッチを確認・管理できます。
方法 2：npx で起動
先にグローバルインストールを行わない場合は、次のコマンドを直接実行できます。
npx agent-purge webデータディレクトリ
設定と Persona は npm パッケージのディレクトリには保存されないため、パッケージをアップグレードしてもユーザーデータは上書きされません。デフォルトの場所は次のとおりです。
- Linux と macOS：
~/.agent-purge/ - Windows：
C:\Users\<あなた>\.agent-purge\
ディレクトリには主に state.json と personas/ が含まれます。初回起動時、ツールは Persona ディレクトリに開始用テンプレート neutral.md を生成します。
0.1.x を使用したことがある場合、新版の初回起動時に、パッケージディレクトリ内にあった既存データが自動的に移行され、元のファイルも保持されます。
カスタムデータ保存場所
AGENT_PURGE_HOME 環境変数を使用して、独立したデータディレクトリを指定できます。Persona のバックアップ、作業環境の分離、別のディスクへの設定保存が必要な場合に適しています。
Linux または macOS
export AGENT_PURGE_HOME=/path/to/your/dataWindows
setx AGENT_PURGE_HOME D:\ap-data設定後は、新しいターミナルセッションで agent-purge を実行し、環境変数が有効になっていることを確認してください。
Persona の理解と管理
各 Persona は 1 つの personas/<id>.md ファイルに対応します。ファイルは Frontmatter と本文で構成され、本文がシステムプロンプトに実際に書き込まれる内容です。
Frontmatter では次のフィールドを使用できます。
- description：Persona の説明。Web リストと
agent-purge lsの出力に表示されます。 - desc：旧版の説明フィールド。引き続き互換性があります。
- order：任意の並び順情報。
- harness：任意の Harness マッチング情報。
- model：任意のモデルマッチング情報。
Web コンソールで名前と説明だけを変更した場合、その他の Frontmatter キーは保持され、全体が上書きされることはありません。
Persona の一覧表示
agent-purge lsこのコマンドはすべての Persona を一覧表示し、現在の一致項目を示します。また、実行時に検出された Harness のインストール状況、バージョン、注入層、各チャンネルの利用可能性も表示します。
現在の Persona の切り替え
agent-purge use <id>ここでの <id> は、personas/ ディレクトリにある Persona ファイルの名前に対応する識別子です。切り替え後は、以降の管理対象呼び出しでその Persona が使用されます。
1 回の呼び出しだけ Persona を指定
現在のグローバル選択を変更せず、今回の呼び出しだけ別の Persona を指定することもできます。
agent-purge pi --persona <id>この方法は、異なるプロンプトの効果を一時的に試す場合に適しています。呼び出し終了後、その Persona が以降の呼び出しのデフォルトとして設定されることはありません。
基本的な使用例
Web コンソールを起動
agent-purge webその後、http://127.0.0.1:7788 にアクセスします。コンソールでは実行状態の確認と全体スイッチの操作ができます。全体スイッチをオフにすると、注入が撤回されます。
現在の Persona で Codex を起動
agent-purge codexagent-purge は対応する Backend とローカルの実行環境に基づいて起動を処理し、その Harness で実際に利用可能な仕組みを通じて現在の Persona の適用を試みます。
pi に 1 回だけ質問
agent-purge pi --ask "このプロジェクトのエラー処理ロジックを確認してください"このコマンドは現在の Persona で 1 回の呼び出しを起動し、--ask の後に続く内容を今回の質問として渡します。
セッション内でのリアルタイム切り替え
Slash チャンネルに対応する Harness では、セッション内で次のコマンドを使用できます。
/purge on
/purge status
/purge off/purge on：Persona の注入を有効にします。/purge status：現在の状態を確認します。/purge off：注入を無効にします。ディスク上の設定は変更しません。
注入が実際に有効になっているか確認する方法
matrix.json に保存されているのは静的な機能マトリックスであり、静的な宣言が現在のマシン上の実際の状態と一致するとは限りません。バージョンの違い、インストール方法、Harness 自体の変更によって、チャンネルの利用可能性が変わる場合があります。
そのため、まず agent-purge ls または Web コンソールに表示される実行時情報を確認してください。次の内容が反映されます。
- Harness がインストール済みかどうか。
- 検出された Harness のバージョン。
- プロンプトが
SYSとUSERのどちらの注入層にあるか。 install、shim、slashの 3 つのチャンネルを利用できるかどうか。
静的な機能表と実行時の検出結果が一致しない場合は、実行時の結果を基準にしてください。
高度な使用方法
タスクごとに複数の Persona を用意
personas/ 配下に複数の Markdown ファイルを管理し、コードレビュー、リファクタリングの提案、日常の開発協力などにそれぞれ使い分けられます。description に用途を明記し、order で表示順を調整してください。マッチング範囲を限定する必要がある場合は、harness または model フィールドを使用できます。
切り替える前に次を実行します。
agent-purge ls対象の Persona を確認してから、次を実行します。
agent-purge use <id>長期設定と一時的な実験を区別
- 常時有効にする場合は、対象 Harness がサポートする install チャンネルを使用します。
- 元のコマンドを直接入力した場合も agent-purge に引き継がせる場合は、shim チャンネルを使用します。
- 現在のセッションだけで試す場合は、slash チャンネルまたは 1 回限りの
--persona引数を優先します。
利用できるチャンネルの種類は、引き続き実行時の検出結果を基準にしてください。
変更前に復元経路を確保
プロジェクトは状態を保存し、可逆操作を提供していますが、実際に使用する際は、現在の Persona、対象 Harness、そして有効なモードをあらかじめ確認することをおすすめします。テスト終了後は、次の方法で撤回できます。
agent-purge uninstall <h>
agent-purge disarm--mode off に切り替えるか、Web コンソールで全体スイッチをオフにすることもできます。
元の状態で起動したことを注入成功と誤認しない
システムプロンプトがサーバー側またはクローズドなバイナリに含まれているクローズドソースのデスクトップ版では、agent-purge は元の状態で起動するだけで、プロンプト注入は実行しません。agent-purge <h> を実行すると、ツールは注入できない理由を明確に出力し、すでに有効になったかのように装うことはありません。
プロジェクト構成の概要
bin/：CLI のエントリーポイント。lib/：状態、Persona、注入、チャンネル、検出のロジック。backends/：各 Harness の起動引数と ID 処理。web/：ローカルコンソール。server.mjsとui.htmlを含みます。bench/：注入成功率の実測と判定スクリプト。開発専用で、通常の実行には関与しません。matrix.json：静的な機能マトリックス。
セキュリティ、プライバシー、コンプライアンスの境界
agent-purge は、ユーザーが管理権限を持つローカルの公式 Harness を対象とし、プロンプトエンジニアリングと堅牢性評価に使用します。バイナリファイルを変更せず、認証を回避せず、ローカルの状態を外部にアップロードすることもありません。また、承認されていないシステムで使用してはなりません。
- 本人が管理権限を持つデバイス、ソフトウェア、およびコンプライアンスに準拠した実験環境でのみ使用してください。
- 未承認の攻撃、脆弱性の悪用、データ窃取、不正侵入、または悪意のあるペイロードの拡散に使用してはなりません。
- 適用される法令、モデルサービスの利用規約、および不正利用ポリシーに違反してはなりません。
- 本プロジェクトは MIT ライセンスに基づき「現状のまま」提供されます。利用者は、自身の入力、出力、および利用行為について責任を負うものとします。
- プロジェクト名、アイデア、コード、またはプロンプトを借用する場合は、リポジトリの声明に従ってクレジットを付与し、出典を明記してください。
README では、特定地域のサーバーおよびウェブサイトへのアクセスについても厳格な制限が定められています。実際に使用する前に、リポジトリに記載された免責事項とコンプライアンスに関する声明をすべて読み、操作範囲が要件を満たしていることを確認してください。
まとめ
agent-purge は、複数の Coding Agent における一貫性のないプロンプトの入口を、Persona、install、shim、slash などの概念に統一し、Web コンソール、実行時検出、および可逆的な撤回機能を提供します。使い始める際は、まずツールをインストールして Web コンソールを開き、agent-purge ls を実行して対応状況を確認してから、Persona を選択して対象の Harness を起動できます。一時的な実験では、単発の Persona またはセッション中の切り替えを優先してください。長期的な設定では、実行時の機能とコンプライアンス上の境界を確認したうえで、常駐チャネルを有効にしてください。