How to make Claude Code check production errors before it starts
Add a short block to CLAUDE.md or AGENTS.md telling the agent to check Runheed before it debugs anything and to resolve errors with the commit hash after a fix. For Claude Code, add a SessionStart hook that fetches the five newest unresolved errors, so they are already in context when the session opens.
Step 1: the instructions block
Claude Code reads CLAUDE.md or AGENTS.md at the start of every session, and Codex and Cursor read AGENTS.md. Paste this block into whichever file your repository uses. It assumes Runheed is already connected to the agent (setup by client).
## Production errors (Runheed)
Production errors from this app are in Runheed, available through the runheed MCP tools.
- Before debugging a bug report, a failing request or anything "broken in prod",
call runheed_search_errors or runheed_get_recent first and read the real stack
trace with runheed_get_error. Don't guess from the code alone.
- When you fix an error, write a failing test that reproduces it first.
- After the fix is committed, call runheed_resolve_error with the commit hash as
the comment. A resolved error that happens again reopens on its own.
- Never ignore an error unless I ask you to.Step 2: a SessionStart hook (Claude Code)
Instructions only work when the agent decides to follow them. A SessionStart hook runs before your first message and adds its output to Claude's context, so the open errors are there without anyone asking. It has to be a command hook: Claude Code skips MCP tool hooks at launch because the MCP servers are not connected yet.
Create an agent key under Settings > Agent keys, then store it outside the repository:
mkdir -p ~/.config/runheed
printf '%s' 'al_...' > ~/.config/runheed/agent-key
chmod 600 ~/.config/runheed/agent-keyAdd the script. It asks for the five newest unresolved errors, waits at most 4 seconds, and prints nothing if the key is missing, the request fails or there are no open errors, so it never slows down or breaks a session. Set RUNHEED_PROJECT_ID to limit it to one project.
#!/usr/bin/env bash
# Adds this project's unresolved production errors from Runheed to Claude's context.
KEY="${RUNHEED_API_KEY:-$(cat "$HOME/.config/runheed/agent-key" 2>/dev/null)}"
[ -n "$KEY" ] || exit 0
OUT=$(curl -sf --max-time 4 -H "Authorization: Bearer $KEY" \
"https://runheed.com/api/mcp/errors?status=unresolved&sort=recent&limit=5${RUNHEED_PROJECT_ID:+&projectId=$RUNHEED_PROJECT_ID}") || exit 0
case "$OUT" in *'"errors":[]'*) exit 0 ;; esac
echo "Unresolved production errors in Runheed, newest first (JSON). Use the runheed MCP tools for stack traces; after a fix ships, resolve the error with the commit hash:"
echo "$OUT"{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/runheed-session-start.sh", "timeout": 10 }
]
}
]
}
}Run chmod +x on the script and commit both files. Each teammate keeps their own key in ~/.config/runheed/agent-key, so no key goes into the repository. Start a new session and ask "what production errors are open?": Claude answers from the hook's output before calling any tool.
What this costs in context
Five error summaries (type, message, count, first and last seen, project) come to well under a thousand tokens. Full stack traces are not included; the agent fetches one with runheed_get_error only when it works on that error.
Questions
- Does the hook work in Cursor or Codex?
- The SessionStart hook is a Claude Code feature. In Cursor and Codex, the AGENTS.md block does the job: it tells the agent to call the runheed tools before it debugs.
- Is the agent key safe in the hook?
- The key stays in a file in your home directory with 0600 permissions, and the script only sends it to https://runheed.com. Agent keys can read errors and change their status; they cannot touch billing, projects or your code. Revoke one in Settings at any time.
- Will the hook slow down Claude Code?
- At launch Claude Code runs SessionStart hooks in the background, so you can type right away; Claude's first answer waits for them. The script gives up after 4 seconds.