# Runheed setup instructions for coding agents
# https://runheed.com

Follow these steps in order. Ask the user only for what you cannot do yourself.

## 1. Account, plan and DSN (needs the user)
1. Ask the user to open https://runheed.com/login, sign in with the emailed link and choose a plan.
2. Ask them to create a project under Projects and paste you its DSN
   (format: runheed://pk_...@runheed.com/<project-id>).
3. Save it as the environment variable RUNHEED_DSN (in .env, .env.local or the
   deploy platform's secrets). Never commit it to git.

## 2. Install the SDK
Detect the stack from the repo:
- package.json present: Node.js / TypeScript
- pyproject.toml or requirements.txt present: Python
- anything else: use the HTTP API (step 2c)

### 2a. Node.js / TypeScript
  npm install https://runheed.com/dl/runheed-0.1.0.tgz        (or: bun add / pnpm add the same spec)
  Note: The npm and PyPI releases are not out yet, so these commands install the same package files straight from runheed.com. Nothing else changes when the registry versions ship.


In the earliest-loaded server file (e.g. instrument.ts, server.ts, app entry):

  import runheed, { expressErrorHandler } from 'runheed';
  runheed.init({ dsn: process.env.RUNHEED_DSN, environment: process.env.NODE_ENV, release: process.env.GIT_SHA });

If the app uses Express, add after all routes:
  app.use(expressErrorHandler());

Elsewhere, report caught errors you re-throw or swallow:
  runheed.captureException(err, { context: 'checkout' });

Record which agent wrote the code (optional, recommended):
  runheed.setAgent({ name: 'claude-code', sessionId: process.env.AGENT_SESSION_ID });

### 2b. Python
  pip install https://runheed.com/dl/runheed-0.1.0-py3-none-any.whl

  import os, runheed
  runheed.init(dsn=os.environ["RUNHEED_DSN"])
  # FastAPI / Django / Flask hooks: see runheed.integrations

### 2c. HTTP (any language)
  POST https://runheed.com/api/ingest
  Header: X-Runheed-Key: <the pk_... part of the DSN>
  JSON body: {"errorType": "...", "errorMessage": "...", "stacktrace": [{"filename": "...", "function": "...", "lineno": 1}], "environment": "production"}

## 3. Verify
Trigger a test error once (for example a temporary route that throws), then
confirm it appears in https://runheed.com/dashboard/errors. Remove the test code afterwards.

## 4. Connect yourself through MCP
Ask the user to create an agent key in https://runheed.com/dashboard/settings (starts with al_).

Claude Code:
  claude mcp add runheed -e RUNHEED_API_KEY=al_... -e RUNHEED_API_URL=https://runheed.com -- npx -y https://runheed.com/dl/runheed-mcp-0.1.0.tgz

Other MCP clients (mcp.json):
  {"mcpServers": {"runheed": {"command": "npx", "args": ["-y", "https://runheed.com/dl/runheed-mcp-0.1.0.tgz"],
    "env": {"RUNHEED_API_KEY": "al_...", "RUNHEED_API_URL": "https://runheed.com"}}}}

Tools you will have: runheed_search_errors, runheed_get_recent, runheed_get_error,
runheed_get_error_context, runheed_get_trends, runheed_get_project_health,
runheed_resolve_error, runheed_ignore_error, runheed_unignore_error.

## 5. Working loop
- After a deploy, call runheed_get_trends or runheed_search_errors (status: unresolved).
- Read the error with runheed_get_error, fix the cause, add a test.
- After the fix ships, call runheed_resolve_error with the commit hash as the comment.