How It Works

Feed collects structured lifecycle events from coding agents and surfaces them in a real-time dashboard.

---

Architecture

Coding agent (Claude Code)
  └── Feed hooks (shell scripts)
        └── POST /api/v1/events → Feed API
              └── PostgreSQL LISTEN/NOTIFY
                    └── SSE stream → Dashboard

The agent runs hooks at key lifecycle points. Each hook fires a shell script that POSTs a JSON payload to the Feed API. The API writes the event to PostgreSQL and broadcasts it via LISTEN/NOTIFY. The dashboard holds an open SSE connection and renders new events live.

---

Event types

Event	When it fires
session_start	Agent session begins — sends repo path, branch, suggested name
user_prompt	User sends a message to the agent
pre_tool	Agent is about to call a tool
post_tool	Tool call completed
heartbeat	Periodic progress report with task summary and step count
learning	Agent records a discovery (gotcha, pattern, decision, etc.)
question	Agent raises a blocker or question for the operator
stop	Agent session is ending — sends final summary
session_end	Session fully closed

---

Agents and liveness

An agent is active if it has sent a heartbeat or any event within the last 5 minutes. The dashboard shows active agents in the top panel; inactive agents age out silently.

Agents identify themselves by:

• Machine: hostname of the machine they run on
• Repo: the local path or remote URL of the repository
• Name: a suggested name (e.g. "Claude on feed") set by the operator or auto-generated

---

Workspaces

Every user has a personal workspace created on first sign-in. Teams can use Clerk organizations — each org gets its own workspace with shared agents, events, and API keys.

API keys are workspace-scoped. An agent registered with a personal workspace key cannot post to a team workspace and vice versa.

---

Real-time delivery

The dashboard connects to /api/v1/stream via Server-Sent Events. PostgreSQL's LISTEN/NOTIFY mechanism broadcasts new events to the Node.js server which fans them out to all connected clients for the same workspace. The SSE client uses exponential backoff (1s → 30s) to reconnect on network interruptions.

---

Data model

workspace
  └── machine (hostname)
  └── repository (url or local path)
  └── agent (name, machine, repo)
        └── task (title, status)
        └── event (type, payload, createdAt)
              └── learning (category, body, evidence)
              └── question (text, urgency, status)