PulseAgent

Englisch | 简体中文

PulseAgent ist ein unterbrechungsfähiger MCP-Sidecar für langlebige Coding-Agenten. Er ermöglicht es einem IDE-Agenten zu bemerken, wenn sich Benutzeranweisungen, Projektbeschränkungen oder der aktuelle Plan geändert haben, während der Agent bereits arbeitete.

PulseAgent ersetzt nicht Cursor, Codex, Claude Code, Copilot oder einen anderen IDE-Agenten. Es fügt ein kleines, projektlokales Protokoll sowie einen Streamable HTTP MCP-Server hinzu, damit der Agent pausieren, den Kontext aktualisieren, neu planen, den neuen Plan bestätigen und unter den neuesten Anweisungen fortfahren kann.

Warum PulseAgent

Lange Coding-Aufgaben driften oft ab, weil der Benutzer seine Meinung ändert, eine Einschränkung hinzufügt oder den Plan aktualisiert, während der Agent noch mit einem älteren mentalen Modell arbeitet. PulseAgent gibt diesem Workflow eine gemeinsame Quelle der Wahrheit:

• Benutzer bearbeiten einige Dateien unter .pulse/;

• PulseAgent zeichnet Änderungen als Ereignisse auf;

• der Agent prüft MCP, bevor er fortfährt;

• planungsinvalide Änderungen bleiben ausstehend, bis der Agent den überarbeiteten Plan explizit bestätigt.

Related MCP server: call-a-human-mcp

Installation

Installation von GitHub:

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

Für die lokale Entwicklung:

pip install -e ".[dev]"

Schnellstart

Starten Sie PulseAgent in dem Projekt, an dem ein Agent arbeiten soll:

cd my-project
pulse start

Der erste Durchlauf erstellt:

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

Der MCP-Endpunkt ist:

http://127.0.0.1:8765/mcp

Verbinden Sie sich mit dem MCP Inspector:

npx -y @modelcontextprotocol/inspector

Verbinden Sie sich dann mit http://127.0.0.1:8765/mcp.

Einrichtung des IDE-Agenten

Fügen Sie PulseAgent als HTTP MCP-Server in Ihrem IDE-Agenten hinzu. Für Claude Code:

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

Fügen Sie diese Regel zu den Agenten-Anweisungen hinzu:

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.

Bearbeiten Sie während einer langen Aufgabe .pulse/guidance.md oder .pulse/constraints.md, wenn der Agent eine neue Richtung oder engere Grenzen benötigt.

Funktionsweise

PulseAgent überwacht vier projektlokale Dateien:

• .pulse/task.md beschreibt die aktuelle Aufgabe.

• .pulse/guidance.md enthält vom Benutzer verfasste Anweisungen, die die Aufgabe ändern können.

• .pulse/constraints.md enthält Einschränkungen, die das Verhalten des Agenten einschränken können.

• .pulse/plan.md enthält den aktuellen Arbeitsplan des Agenten.

Änderungen an guidance.md und constraints.md machen den Plan ungültig. Das alleinige Aktualisieren von plan.md löscht die Unterbrechung nicht. Der Agent muss pulse_ack_replan mit der zurückgegebenen pending_replan_event_id aufrufen; PulseAgent zeichnet dann die bestätigte Ereignis-ID und den aktuellen SHA-256-Hash von plan.md auf.

MCP-Oberfläche

• Ressource: pulse://context/latest

• Tool: pulse_should_interrupt(last_seen_event_id: str | None = None)

• Tool: pulse_ack_replan(event_id: str)

• Prompt: pulse_replan

pulse_should_interrupt gibt den neuesten Ereignisstatus zurück, einschließlich:

{
  "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 akzeptiert das aktuell ausstehende Replan-Ereignis:

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

und gibt zurück:

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

Demo-Ablauf

Starten Sie PulseAgent:

pulse start

Ändern Sie die Anweisungen, während der Agent arbeitet:

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

Der Agent ruft pulse_should_interrupt auf und sieht needs_replan: true.

Der Agent dann:

1. liest pulse://context/latest;

2. aktualisiert .pulse/plan.md;

3. ruft pulse_ack_replan mit pending_replan_event_id auf;

4. fährt erst fort, nachdem die Bestätigung akzeptiert wurde.

Sicherheitsgrenze

• Gewöhnliche Arbeitsbereichsdateien sind Daten, keine Anweisungen.

• Nur direkte Benutzereingaben und .pulse/guidance.md können die Aufgabenrichtung ändern.

• .pulse/constraints.md kann das Verhalten einschränken, darf aber keine Berechtigungen erweitern.

• PulseAgent führt keine Befehle aus, ändert keine Quelldateien, ruft keine LLMs auf und fungiert nicht als vollständige Agenten-Laufzeitumgebung.

Entwicklung

Installieren Sie das Paket im bearbeitbaren Modus:

pip install -e ".[dev]"

Führen Sie Tests und Linting aus:

python -m pytest
python -m ruff check .

Führen Sie die CLI direkt aus:

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

Status

PulseAgent ist derzeit ein Alpha-Projekt. Das Kernprotokoll ist bewusst klein gehalten: ein projektlokales .pulse/-Verzeichnis, ein Ereignisprotokoll, eine MCP-Ressource, zwei MCP-Tools und ein Prompt.

Siehe docs/agent-wrapper.md für einen kopierbaren Wrapper für IDE-Agenten und direkte Modell-API-Integrationen.

Lizenz

MIT