agent-pulse

<p align="center">
  <img src="docs/banner.png" alt="agent-pulse" width="1000" />
</p>

<h1 align="center">agent-pulse</h1>

<p align="center">
  <strong>A local event gateway for AI code agents.</strong><br/>
  Capture lifecycle events from Claude Code, Gemini CLI, and more — fan them out to any HTTP endpoint, webhook, or device.
</p>

<p align="center">
  <a href="#installation">Install</a> •
  <a href="#quickstart">Quickstart</a> •
  <a href="#agent-setup">Agent Setup</a> •
  <a href="#configuration">Config</a> •
  <a href="#commands">Commands</a>
</p>

---

## Why agent-pulse?

Every AI code agent has its own hook system — different formats, different configs, scattered across projects. Adding a new webhook means editing every project's settings for every agent you use.

**agent-pulse** solves this with a single global config:

- **One config, all agents** — Define your clients once in `~/.config/agent-pulse/config.yaml`. Every project, every agent, every event routed through one place.
- **Zero per-project setup** — No more duplicating hook configs across repositories. Register your hooks once and you're done.
- **Fan-out to anything** — HTTP endpoints, webhooks, IoT devices (ESP32, Raspberry Pi, etc.), scripts — if it speaks HTTP, agent-pulse can reach it.
- **Fully local** — Everything runs on your machine. No cloud, no accounts, no data leaves your network.
- **Enrich with metadata** — Attach custom data to every lifecycle hook via a project-level `.agent-pulse.json` — project name, team, or anything your clients need.
- **Filter what matters** — Route specific events to specific clients. Send `notification` events to your desk light, `session_start` to your dashboard, everything to your logger.
- **Real-time streaming** — Connect to the SSE endpoint and watch events flow in real-time. Perfect for dashboards, browser UIs, or a simple `curl -N`.

---

## Diagram


<p align="center">
  <img src="docs/architecture.png" alt="Architecture diagram" width="1500" />