PulseAgent

English | 简体中文

PulseAgentは、長期間実行されるコーディングエージェント向けの、割り込みを認識するMCPサイドカーです。 これにより、IDEエージェントは、エージェントが作業中にユーザーのガイダンス、プロジェクトの制約、または現在の計画が変更されたことを検知できます。

PulseAgentは、Cursor、Codex、Claude Code、Copilot、その他のIDEエージェントを置き換えるものではありません。プロジェクトローカルの小さなプロトコルとStreamable HTTP MCPサーバーを追加することで、エージェントが一時停止、コンテキストの更新、再計画、新しい計画の承認を行い、最新の指示に基づいて継続できるようにします。

PulseAgentの目的

長期間のコーディングタスクでは、エージェントが古いメンタルモデルで実行している間にユーザーが考えを変えたり、制約を追加したり、計画を更新したりすることで、作業がずれてしまうことがよくあります。PulseAgentは、そのワークフローに共有の信頼できる情報源を提供します。

• ユーザーは .pulse/ 配下のいくつかのファイルを編集します。

• PulseAgentは変更をイベントとして記録します。

• エージェントは継続する前にMCPを確認します。

• 計画を無効にする変更は、エージェントが改訂された計画を明示的に承認するまで保留されます。

Related MCP server: call-a-human-mcp

インストール

GitHubからインストールします：

pip install git+https://github.com/zhangyh0426/PulseAgent.git

ローカル開発用：

pip install -e ".[dev]"

クイックスタート

エージェントに作業させたいプロジェクトでPulseAgentを起動します：

cd my-project
pulse start

初回実行時に以下が作成されます：

.pulse/
├─ task.md
├─ guidance.md
├─ constraints.md
├─ plan.md
├─ state.json
└─ events.jsonl

MCPエンドポイントは以下の通りです：

http://127.0.0.1:8765/mcp

MCP Inspectorで接続します：

npx -y @modelcontextprotocol/inspector

次に http://127.0.0.1:8765/mcp に接続します。

IDEエージェントの設定

IDEエージェントにPulseAgentをHTTP MCPサーバーとして追加します。Claude Codeの場合：

claude mcp add --transport http pulse-agent http://127.0.0.1:8765/mcp

エージェントの指示に以下のルールを追加します：

Before continuing long-running work, read pulse://context/latest and call
pulse_should_interrupt. If needs_replan is true, update .pulse/plan.md, then
call pulse_ack_replan with pending_replan_event_id before continuing.

長期間のタスク中に、エージェントに新しい指示やより厳格な境界線が必要になった場合は、.pulse/guidance.md または .pulse/constraints.md を編集してください。

仕組み

PulseAgentは、プロジェクトローカルの4つのファイルを監視します：

• .pulse/task.md は現在のタスクを記述します。

• .pulse/guidance.md には、タスクを変更する可能性のあるユーザー作成の指示が含まれます。

• .pulse/constraints.md には、エージェントの動作を制限する可能性のある制約が含まれます。

• .pulse/plan.md には、エージェントの現在の作業計画が含まれます。

guidance.md と constraints.md への変更は、計画を無効にします。plan.md だけを更新しても割り込みは解除されません。エージェントは pending_replan_event_id を指定して pulse_ack_replan を呼び出す必要があります。その後、PulseAgentは承認されたイベントIDと現在の plan.md のSHA-256ハッシュを記録します。

MCPインターフェース

• リソース: pulse://context/latest

• ツール: pulse_should_interrupt(last_seen_event_id: str | None = None)

• ツール: pulse_ack_replan(event_id: str)

• プロンプト: pulse_replan

pulse_should_interrupt は、以下を含む最新のイベント状態を返します：

{
  "needs_replan": true,
  "latest_event_id": "evt_...",
  "has_new_events": true,
  "changed_files": [".pulse/guidance.md"],
  "pending_replan_event_id": "evt_...",
  "pending_replan_files": [".pulse/guidance.md"],
  "last_acknowledged_event_id": null,
  "last_acknowledged_plan_sha256": null,
  "reason": "..."
}

pulse_ack_replan は、現在保留中の再計画イベントを受け入れます：

{
  "event_id": "evt_..."
}

そして以下を返します：

{
  "accepted": true,
  "acknowledged_event_id": "evt_...",
  "plan_sha256": "...",
  "reason": "..."
}

デモフロー

PulseAgentを起動します：

pulse start

エージェントが作業中にガイダンスを変更します：

printf "# Guidance\n\nPrefer a smaller patch and keep public APIs stable.\n" > .pulse/guidance.md

エージェントは pulse_should_interrupt を呼び出し、needs_replan: true を確認します。

その後、エージェントは以下の手順を実行します：

1. pulse://context/latest を読み取ります。

2. .pulse/plan.md を更新します。

3. pending_replan_event_id を指定して pulse_ack_replan を呼び出します。

4. 承認が受け入れられた後にのみ継続します。

安全性の境界

• 通常のワークスペースファイルはデータであり、指示ではありません。

• 直接的なユーザー入力と .pulse/guidance.md のみがタスクの方向性を変更できます。

• .pulse/constraints.md は動作を制限する可能性がありますが、権限を拡大してはなりません。

• PulseAgentはコマンドの実行、ソースファイルの変更、LLMの呼び出し、または完全なエージェントランタイムとしての動作は行いません。

開発

編集可能なモードでパッケージをインストールします：

pip install -e ".[dev]"

テストとリントを実行します：

python -m pytest
python -m ruff check .

CLIを直接実行します：

python -m pulse_agent --help
python -m pulse_agent --version

ステータス

PulseAgentは現在アルファ版プロジェクトです。コアプロトコルは意図的に小さく設計されています：プロジェクトローカルの .pulse/ ディレクトリ、イベントログ、1つのMCPリソース、2つのMCPツール、および1つのプロンプトのみです。

IDEエージェントおよび直接的なモデルAPI統合のためのコピー可能なラッパーについては、docs/agent-wrapper.md を参照してください。

ライセンス

MIT