pulse-service

pulse-service

Local heartbeat daemon for Pulse — an enterprise control plane for AI development agencies.

What it does

pulse-service runs as a local daemon that monitors your multi-agent AI development environment:

• Detects master and sub-agent panes in WezTerm
• Polls MACP (Multi-Agent Coordination Protocol) SQLite databases for task/agent state
• Captures terminal text snapshots on a configurable interval
• Exposes a local HTTP API for real-time state queries
• Delivers directives (commands) to agent panes
• Tracks git status, agent liveness, and task progress
• Can install as a system service (launchd on macOS, systemd on Linux)

Install

npm install -g pulse-service

Prerequisites

• Node.js 18+
• WezTerm — terminal pane detection requires the wezterm CLI
• C++ build tools — better-sqlite3 compiles a native module via node-gyp. On macOS: Xcode Command Line Tools. On Linux: build-essential.

Quick start

# Initialize in your project directory
pulse-service init --project . --master claude

# Start the daemon (foreground)
pulse-service start --foreground

# Check status
pulse-service status

Commands

Command	Description
init	Initialize Pulse for a project (creates .pulse/config.json)
start	Start the heartbeat daemon
status	Show current service state
install	Install as a system service (launchd/systemd)
uninstall	Remove the system service

Local HTTP API

When running, the service exposes a localhost-only API (default port 9850):

• GET /status — Full service state snapshot
• GET /agents — List of detected agents
• GET /tasks — MACP task summary
• POST /directive — Send a directive to master or an agent

Configuration

After pulse-service init, edit .pulse/config.json:

{
  "pulseInterval": 30,
  "masterAgent": {
    "cli": "claude",
    "projectRoot": "/path/to/project",
    "sessionResume": true
  },
  "screenshotInterval": 300,
  "screenshotEnabled": true,
  "macpDbPath": ".macp/project.macp.db",
  "logPath": ".pulse/pulse.log",
  "statePath": ".pulse/state.json",
  "localApiPort": 9850
}

ESM only

This package is ESM-only ("type": "module"). Requires Node.js 18+.

License

MIT