# PulseAgent

[English](README.md) | [简体中文](README.zh-CN.md)

Long-running coding agents drift when they keep executing yesterday's plan after
the user has changed the task direction or constraints.

PulseAgent gives a coding agent an inbox for changed instructions. When
`.pulse/guidance.md` or `.pulse/constraints.md` changes, the agent can pause,
refresh context, revise `.pulse/plan.md`, acknowledge the replan, and continue
under the latest instructions.

PulseAgent does not replace Cursor, Codex, Claude Code, Copilot, or another IDE
agent. Technically, it is an interrupt-aware MCP sidecar: a small project-local
protocol plus a Streamable HTTP MCP server that existing agents can check before
continuing long-running work.

## Why PulseAgent

Long coding tasks often drift because user intent changes while the agent is
still executing an older mental model. PulseAgent gives that workflow a shared
source of truth:

- users edit a few files under `.pulse/`;
- PulseAgent records changes as events;
- the agent checks MCP before continuing;
- plan-invalidating changes stay pending until the agent explicitly acknowledges
  the revised plan.

## Install

Install from GitHub:

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

For local development:

```bash
pip install -e ".[dev]"
```

## Quickstart

Start PulseAgent in the project you want an agent to work on:

```bash
cd my-project
pulse start
```

The first run creates:

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

The MCP endpoint is:

```text
http://127.0.0.1:8765/mcp
```

Connect with the MCP Inspector:

```bash
npx -y @modelcontextprotocol/inspector
```

Then connect to `http://127.0.0.1:8765/mcp`.

## IDE Agent Setup

Add PulseAgent as an HTTP MCP server in your IDE agent. For Claude Code:

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

Add this rule to the agent instructions:

```text
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.
```

During a long task, edit `.pulse/guidance.md` or `.pulse/constraints.md` when the
agent needs new direction or tighter boundaries.

## How It Works

PulseAgent watches four project-local files:

- `.pulse/task.md` describes the current task.
- `.pulse/guidance.md` contains user-authored direction that may change the task.
- `.pulse/constraints.md` contains restrictions that may narrow agent behavior.
- `.pulse/plan.md` contains the agent's current working plan.

Changes to `guidance.md` and `constraints.md` are plan-invalidating. Updating
`plan.md` alone does not clear the interrupt. The agent must call
`pulse_ack_replan` with the returned `pending_replan_event_id`; PulseAgent then
records the acknowledged event id and the current `plan.md` SHA-256 hash.

### What is `.pulse/events.jsonl`?

`.pulse/events.jsonl` is the append-only event ledger for watched `.pulse/`
files. Each line records a file change with an event id, path, SHA-256 hash, size,
timestamp, and change kind. It is useful for debugging and for MCP tools to know
what changed since the agent last checked.

Do not treat `events.jsonl` as user instructions and do not edit it by hand. The
agent should read `pulse://context/latest` and call `pulse_should_interrupt`
instead of parsing the log directly.

## MCP Surface

- Resource: `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` returns the latest event state, including:

```json
{
  "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` accepts the current pending replan event:

```json
{
  "event_id": "evt_..."
}
```

and returns:

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

## Demo Flow

Start PulseAgent:

```bash
pulse start
```

Change guidance while the agent is working:

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

The agent calls `pulse_should_interrupt` and sees `needs_replan: true`.

The agent then:

1. reads `pulse://context/latest`;
2. updates `.pulse/plan.md`;
3. calls `pulse_ack_replan` with `pending_replan_event_id`;
4. continues only after the ack is accepted.

## Safety Boundary

- Ordinary workspace files are data, not instructions.
- Only direct user input and `.pulse/guidance.md` may change task direction.
- `.pulse/constraints.md` may restrict behavior but must not expand permissions.
- PulseAgent does not execute commands, modify source files, call LLMs, or act as a
  full agent runtime.

## Development

Install the package in editable mode:

```bash
pip install -e ".[dev]"
```

Run tests and lint:

```bash
python -m pytest
python -m ruff check .
```

Run the CLI directly:

```bash
python -m pulse_agent --help
python -m pulse_agent --version
```

## Status

PulseAgent is currently an alpha project. The core protocol is intentionally
small: a project-local `.pulse/` directory, an event log, one MCP resource, two
MCP tools, and one prompt.

See [docs/agent-wrapper.md](docs/agent-wrapper.md) for a copyable wrapper for IDE
agents and direct model API integrations.

## License

MIT