Claude Code Hook

Stateful connects to Claude Code through its hooks. Once wired, Claude Code gets your relevant context on every prompt, and a Stateful agent can react to what happens during the session. You set it up yourself from inside the app by pasting a short config snippet.

What it does

The hook wires three of Claude Code's events to Stateful:

• Every prompt (UserPromptSubmit) — Stateful returns the most relevant slice of your context, and Claude Code prepends it to your message. You stop re-explaining your projects, decisions, and constraints.
• When Claude Code tries to stop (Stop) — if you've set up an agent for this (below), it decides whether Claude Code should keep going and, if so, with what instruction. If you haven't, Claude Code just stops normally.
• Notifications — session events are recorded so your agents can act on them.

If Stateful is ever unreachable, every one of these fails open: your prompt is never blocked and Claude Code never gets stuck.

Set it up

You'll need jq and curl available in your shell (brew install jq if you don't have it).

1. In the app, open the Agents view and start the Claude Code setup. It generates a personal token and a ready-to-paste snippet.
2. Copy the snippet — it already has your token filled in — into ~/.claude/settings.json, merging the hooks key if you already have one.
3. Claude Code picks it up automatically; no restart needed.

The snippet looks like this (the app fills in your real token in place of <YOUR-TOKEN>):

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "jq -c . | curl -fsS -X POST https://api.stateful.me/webhooks/claude-code/<YOUR-TOKEN>/context --data @-" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "jq -c . | curl -fsS -X POST https://api.stateful.me/webhooks/claude-code/<YOUR-TOKEN>/stop --data @-" } ] }
    ],
    "Notification": [
      { "hooks": [ { "type": "command", "command": "jq -c . | curl -fsS -X POST https://api.stateful.me/webhooks/claude-code/<YOUR-TOKEN> --data @- >/dev/null" } ] }
    ]
  }
}

Your token is a secret — anyone with it can post to your account. If it leaks, regenerate it in the same panel; the old one stops working immediately.

The "keep going" agent

The Stop hook only does something if you've created an agent triggered on Claude Code events (see Agents in Stateful). That agent's purpose — plus your context — is what decides whether to nudge Claude Code onward. Think of it as a guardrail you define: "don't stop until the tests pass," "keep going until the migration is complete." Without such an agent, the Stop hook is a harmless no-op.

Verifying it works

Start a new Claude Code session and ask something personal — "what am I working on?" or "what's my preferred stack?" — without giving any context. If the hook is working, Claude Code answers from your Stateful context.

Want Claude Code to use Stateful's tools too?

The hook injects context and powers the agent guardrail. If you also want Claude Code to actively call Stateful — search your subjects, propose edits — connect it as an MCP client as well. See Connect via MCP.