PulseAgent

English | 简体中文

PulseAgent는 장기 실행 코딩 에이전트를 위한 인터럽트 인식 MCP 사이드카입니다. 이 도구를 사용하면 IDE 에이전트가 작업 도중에 사용자 지침, 프로젝트 제약 조건 또는 현재 계획이 변경되었음을 감지할 수 있습니다.

PulseAgent는 Cursor, Codex, Claude Code, Copilot 또는 기타 IDE 에이전트를 대체하지 않습니다. 대신 소규모 프로젝트 로컬 프로토콜과 스트리밍 가능한 HTTP MCP 서버를 추가하여 에이전트가 일시 중지하고, 컨텍스트를 새로 고치고, 계획을 재수립하고, 새로운 계획을 승인한 뒤 최신 지침에 따라 계속 작업할 수 있도록 합니다.

PulseAgent가 필요한 이유

긴 코딩 작업은 사용자가 마음을 바꾸거나, 제약 조건을 추가하거나, 에이전트가 이전의 사고 모델로 실행 중인 동안 계획을 업데이트할 때 종종 방향이 어긋납니다. PulseAgent는 이러한 워크플로우에 공유된 진실의 원천(source of truth)을 제공합니다:

• 사용자가 .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/ 디렉토리, 이벤트 로그, 하나의 MCP 리소스, 두 개의 MCP 도구, 하나의 프롬프트.

IDE 에이전트 및 직접 모델 API 통합을 위한 복사 가능한 래퍼는 docs/agent-wrapper.md를 참조하십시오.

라이선스

MIT