{"title":"Runheed, Error Tracking My Agent Can Read","html_url":"https://deallocatedobjects.com/posts/runheed-error-tracking-my-agent-can-read","source_url":"","markdown_content":"A lot of the code running in my apps now was written by an agent. When that code throws in production, the usual path back to a fix goes through me: an alert email, a dashboard, a stack trace I copy into a terminal, and then an explanation of what I think happened. The agent that's about to fix it is the one that needs the details, and it's the one furthest from them.\n\nSo this week I launched [Runheed](https://runheed.com). It's error tracking built so your coding agent can read it. Your app reports exceptions to it, and Claude Code, Cursor or any other MCP client can ask \"what broke in production since yesterday's deploy?\", read the full context, fix the bug and mark it resolved.\n\n### How the Loop Works\n\nThere are four steps, and only the first one is your app's job.\n\n1. **Your app throws.** The SDK sends the exception with its stack trace, the breadcrumbs leading up to it, request details and, if you set it, the agent session that wrote the code.\n2. **Runheed groups it.** Repeats fold into one issue, so the agent sees \"TypeError in checkout.ts:42, 318 events\" instead of 318 separate reports.\n3. **Your agent reads it.** It searches errors and pulls the full context through MCP.\n4. **Your agent closes it.** Once the fix ships, the agent marks the error resolved with a note about the fix. If the same error comes back, it reopens on its own.\n\nThat last part is a small rule in the ingest path. When an event arrives for a group that was marked resolved, the group goes back to unresolved. A regression shows up the next time the agent checks, with no one needing to remember the old issue.\n\n### Grouping\n\nGrouping is the part that decides whether an error tracker is pleasant or exhausting, and for an agent it matters even more. Every duplicate it has to read costs context.\n\nRunheed fingerprints each event from the error type, the message and the first stack frame that belongs to your own code:\n\n```ts title=\"src/app/api/ingest/route.ts\"\nfunction generateFingerprint(event: IngestEvent): string {\n const parts: string[] = [event.errorType, event.errorMessage];\n\n // Add first in-app stack frame if available\n if (event.stacktrace && event.stacktrace.length > 0) {\n const inAppFrame = event.stacktrace.find((frame) => frame.inApp !== false) || event.stacktrace[0];\n if (inAppFrame.filename) parts.push(inAppFrame.filename);\n if (inAppFrame.function) parts.push(inAppFrame.function);\n if (inAppFrame.lineno !== undefined) parts.push(String(inAppFrame.lineno));\n }\n // ...hashed into the group's fingerprint\n}\n```\n\nUsing the first in-app frame matters. Plenty of errors surface deep inside a framework or a library, and grouping on the top frame would lump unrelated bugs together under some line in `node_modules`. The frame in your code is the one the agent needs to open anyway. If you know better for a particular error, you can pass your own fingerprint array and Runheed hashes that instead.\n\n### What the Agent Gets\n\nMost error trackers are designed for a person looking at a dashboard. I picked the fields an agent needs to go from report to fix without asking me anything:\n\n- The stack trace with file, function, line and column for each frame, with your own code marked so the agent opens the right file first.\n- Agent context: which agent and version wrote the code, the session id, and which tool or action was running when it failed.\n- Breadcrumbs, the steps your code recorded before the failure, like requests, queries and log lines.\n- Environment and release, so \"since yesterday's deploy\" means something.\n\nOn the MCP side there are nine tools, all prefixed `runheed_`: search errors, get one error, get the most recent ones, get trends over 24 hours, 7 days or 30 days, get the full context for an error, resolve, ignore, unignore, and a project health check. The health tool gives a score from 0 to 100 based on unresolved issues and the last 24 hours of errors, plus a few recommendations, which makes it a nice thing for an agent to call right after a deploy.\n\nRecording which agent wrote the code is one line in the SDK:\n\n```ts title=\"instrument.ts\"\nimport runheed from 'runheed';\n\nrunheed.init({ dsn: process.env.RUNHEED_DSN, environment: process.env.NODE_ENV, release: process.env.GIT_SHA });\nrunheed.setAgent({ name: 'claude-code', sessionId: process.env.AGENT_SESSION_ID });\n```\n\nThere's a Python SDK with FastAPI, Django and Flask hooks, an Express error handler for Node, and a plain JSON endpoint for any other language.\n\n### Setup Your Agent Can Do\n\nMy favorite file on the site is [runheed.com/SETUP.txt](https://runheed.com/SETUP.txt). It's setup instructions written for a coding agent. You point your agent at it and it does almost everything: it looks at the repo to decide between Node, Python or the HTTP endpoint, installs the SDK, adds the init call to the earliest-loaded server file, wires up the framework hook, triggers a test error to confirm it shows up, removes the test code, and then connects itself over MCP.\n\nThe only things it asks you for are the parts that need a person: signing in, creating a project and pasting it the DSN, and creating an agent key in settings. The npm and PyPI releases aren't out yet, so for now the SDK and MCP server install straight from runheed.com, and the setup file has the exact commands.\n\n### Being Careful With What Comes In\n\nError reports tend to collect things that shouldn't be stored. Authorization, cookie and API key headers are redacted when an event arrives, before anything is written. Agent keys are hashed in the database and shown to you once when you create them. Events older than your plan's history window are deleted by a daily job, so old reports don't pile up forever.\n\n### Where It Fits\n\nRunheed is for people who already let agents write and ship a good share of their code. The fix loop gets shorter when the agent can read production errors itself: you ask what's new, it reads the grouped errors with their context, and it can come back with a fix and a test. If you want your agent to see what its code is doing out in the world, give [Runheed](https://runheed.com) a try.","html_content":"

A lot of the code running in my apps now was written by an agent. When that code throws in production, the usual path back to a fix goes through me: an alert email, a dashboard, a stack trace I copy into a terminal, and then an explanation of what I think happened. The agent that’s about to fix it is the one that needs the details, and it’s the one furthest from them.

\n

So this week I launched Runheed. It’s error tracking built so your coding agent can read it. Your app reports exceptions to it, and Claude Code, Cursor or any other MCP client can ask “what broke in production since yesterday’s deploy?”, read the full context, fix the bug and mark it resolved.

\n

How the Loop Works

\n

There are four steps, and only the first one is your app’s job.

\n
    \n
  1. Your app throws. The SDK sends the exception with its stack trace, the breadcrumbs leading up to it, request details and, if you set it, the agent session that wrote the code.
    2. \n
  2. Runheed groups it. Repeats fold into one issue, so the agent sees “TypeError in checkout.ts:42, 318 events” instead of 318 separate reports.
    3. \n
  3. Your agent reads it. It searches errors and pulls the full context through MCP.
    4. \n
  4. Your agent closes it. Once the fix ships, the agent marks the error resolved with a note about the fix. If the same error comes back, it reopens on its own.
    5. \n
\n

That last part is a small rule in the ingest path. When an event arrives for a group that was marked resolved, the group goes back to unresolved. A regression shows up the next time the agent checks, with no one needing to remember the old issue.

\n

Grouping

\n

Grouping is the part that decides whether an error tracker is pleasant or exhausting, and for an agent it matters even more. Every duplicate it has to read costs context.

\n

Runheed fingerprints each event from the error type, the message and the first stack frame that belongs to your own code:

\n
src/app/api/ingest/route.tsTypeScript
function generateFingerprint(event: IngestEvent): string {\n  const parts: string[] = [event.errorType, event.errorMessage];\n\n  // Add first in-app stack frame if available\n  if (event.stacktrace && event.stacktrace.length > 0) {\n    const inAppFrame = event.stacktrace.find((frame) => frame.inApp !== false) || event.stacktrace[0];\n    if (inAppFrame.filename) parts.push(inAppFrame.filename);\n    if (inAppFrame.function) parts.push(inAppFrame.function);\n    if (inAppFrame.lineno !== undefined) parts.push(String(inAppFrame.lineno));\n  }\n  // ...hashed into the group's fingerprint\n}

Using the first in-app frame matters. Plenty of errors surface deep inside a framework or a library, and grouping on the top frame would lump unrelated bugs together under some line in node_modules. The frame in your code is the one the agent needs to open anyway. If you know better for a particular error, you can pass your own fingerprint array and Runheed hashes that instead.

\n

What the Agent Gets

\n

Most error trackers are designed for a person looking at a dashboard. I picked the fields an agent needs to go from report to fix without asking me anything:

\n\n

On the MCP side there are nine tools, all prefixed runheed_: search errors, get one error, get the most recent ones, get trends over 24 hours, 7 days or 30 days, get the full context for an error, resolve, ignore, unignore, and a project health check. The health tool gives a score from 0 to 100 based on unresolved issues and the last 24 hours of errors, plus a few recommendations, which makes it a nice thing for an agent to call right after a deploy.

\n

Recording which agent wrote the code is one line in the SDK:

\n
instrument.tsTypeScript
import runheed from 'runheed';\n\nrunheed.init({ dsn: process.env.RUNHEED_DSN, environment: process.env.NODE_ENV, release: process.env.GIT_SHA });\nrunheed.setAgent({ name: 'claude-code', sessionId: process.env.AGENT_SESSION_ID });

There’s a Python SDK with FastAPI, Django and Flask hooks, an Express error handler for Node, and a plain JSON endpoint for any other language.

\n

Setup Your Agent Can Do

\n

My favorite file on the site is runheed.com/SETUP.txt. It’s setup instructions written for a coding agent. You point your agent at it and it does almost everything: it looks at the repo to decide between Node, Python or the HTTP endpoint, installs the SDK, adds the init call to the earliest-loaded server file, wires up the framework hook, triggers a test error to confirm it shows up, removes the test code, and then connects itself over MCP.

\n

The only things it asks you for are the parts that need a person: signing in, creating a project and pasting it the DSN, and creating an agent key in settings. The npm and PyPI releases aren’t out yet, so for now the SDK and MCP server install straight from runheed.com, and the setup file has the exact commands.

\n

Being Careful With What Comes In

\n

Error reports tend to collect things that shouldn’t be stored. Authorization, cookie and API key headers are redacted when an event arrives, before anything is written. Agent keys are hashed in the database and shown to you once when you create them. Events older than your plan’s history window are deleted by a daily job, so old reports don’t pile up forever.

\n

Where It Fits

\n

Runheed is for people who already let agents write and ship a good share of their code. The fix loop gets shorter when the agent can read production errors itself: you ask what’s new, it reads the grouped errors with their context, and it can come back with a fix and a test. If you want your agent to see what its code is doing out in the world, give Runheed a try.

","created_at":"2026-10-10T13:00:00.000Z","updated_at":"2026-10-10T13:00:00.000Z"}