Hooks Reference

Feed uses six Claude Code lifecycle hooks. Each hook fires a shell script that reads its input from stdin (Claude Code passes a JSON payload) and POSTs an event to the Feed API.

Hook scripts

Hooks are installed at ~/.feed/hooks/ by npx skills add dennisonbertram/feed -a claude-code -g followed by bash ~/.claude/skills/feed/scripts/install-hooks.sh, which also registers them in ~/.claude/settings.json.

Hook event	Script	What it sends
`SessionStart`	`on-session-start.sh`	`session_start` event with cwd, branch, suggested agent name
`UserPromptSubmit`	`on-user-prompt.sh`	`user_prompt` event with prompt text and session context
`PreToolUse`	`on-pre-tool.sh`	`pre_tool` event with tool name and input
`PostToolUse`	`on-post-tool.sh`	`post_tool` event with tool name and output summary
`Stop`	`on-stop.sh`	`stop` event with session summary
`SessionEnd`	`on-session-end.sh`	`session_end` event

Claude Code settings

Hooks are registered in ~/.claude/settings.json. The Feed plugin adds an entry for each hook event matching all tools (".*"):

{
  "hooks": {
    "SessionStart": [
      { "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.feed/hooks/on-session-start.sh" }] }
    ],
    "UserPromptSubmit": [
      { "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.feed/hooks/on-user-prompt.sh" }] }
    ],
    "PreToolUse": [
      { "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.feed/hooks/on-pre-tool.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.feed/hooks/on-post-tool.sh" }] }
    ],
    "Stop": [
      { "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.feed/hooks/on-stop.sh" }] }
    ],
    "SessionEnd": [
      { "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.feed/hooks/on-session-end.sh" }] }
    ]
  }
}

Environment variables

Each hook script reads these variables from the environment or .env file in the repo root:

Variable	Description
`FEED_API_URL`	Base URL for the Feed API, e.g. `https://www.tryfeed.dev/api/v1`
`FEED_API_KEY`	Workspace-scoped API key generated from the dashboard
`FEED_WORKSPACE_ID`	Your workspace ID
`FEED_AGENT_NAME`	Optional display name for the agent (e.g. `Claude on feed`)

Reliability

The hook library (_lib.sh) handles:

Session ID generation — a UUID per session, persisted at ~/.feed/sessions/{id}/
Agent registration — registers the machine + repo on first hook fire
Retry on failure — one retry on network errors or 5xx responses; 4xx errors are not retried
Connection timeout — 3-second connect timeout per request to avoid blocking the agent

Hooks run asynchronously and do not block Claude Code's main loop.

Heartbeats

Heartbeats are sent separately by the agent (not via hooks) using the POST /api/v1/heartbeats endpoint. The agent is responsible for sending periodic heartbeats while it's working. The dashboard considers an agent active if a heartbeat or event was received within the last 5 minutes.