Guide · Agent skill
How to use convex-sentinel: production error capture for Convex
Updated · written with AI from the project's own documentation and checked against our catalogue data
convex-sentinel is an agent skill that teaches your coding agent to set up Sentinel, a production error capture component for Convex apps. Once it is in place, server function failures, browser JavaScript and React crashes, and concurrency or scale signals are saved to a table in your own Convex deployment. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check before you enable the optional automated fix job.
Production Error Capture for Convexopenclaw/clawhub · MIT Download the skill Quick start
- 1Download the ZIP. Download the convex-sentinel skill ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ for one project. Or upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
- 3Check your Convex project. Confirm the project has convex/convex.config.ts and that your app is deployed to Convex cloud if you want production errors.
- 4Ask the agent to set up capture. Tell the agent you want Sentinel production error capture in your Convex app. It will add app.use(sentinel) and wire the client SDK.
- 5Confirm redaction is on. Redaction runs at write time and is on by default. Check that secrets are filtered before you rely on stored errors.
- 6Read recent errors. Ask the agent to list recent production errors. It reads them with the Convex CLI using convex data and run-once-query.
- 7Decide on the self-healing cron. Enable the optional cron only if you accept an automated job opening pull requests against your code, and only after reviewing the output.
What does the convex-sentinel skill make the agent do?
Agent skills are instruction packages that a compatible AI agent loads when a request matches them. This one is about production errors in a Convex app. It walks the agent through installing the @convex-dev/sentinel component, wiring up the client SDK, and then reading the errors it has captured.
Captured errors are written to a table in your own deployment. Redaction runs at write time and is on by default, so secret key names and value patterns are filtered before anything is stored. According to the skill's source, the data stays in your deployment and is not sent to a third party.
- Server function failures
- Client JavaScript and React crashes
- OCC and scale signals (concurrency and scale)
How do you install the convex-sentinel skill?
Download the skill ZIP from this page. You can install it in one of two ways, depending on where you use your agent.
For Claude Code, unzip the file into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.
The package contains a single file, SKILL.md. Once installed, the skill is available to the agent, but it does not change your app until you ask the agent to set Sentinel up.
- Option A: unzip into ~/.claude/skills/ (all projects)
- Option B: unzip into your project's .claude/skills/ (one project)
- Option C: upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills
What do you need before the skill can help?
The skill assumes a working Convex project that contains convex/convex.config.ts. It also needs the @convex-dev/sentinel npm package and the Convex CLI, which the agent uses to read recent errors.
Production capture only works on a deployed Convex cloud app. Installing the component works without an account, but you will not see production errors until the app is deployed. If you want the optional self-healing job, you also need an AI runner called ai-runner.
- A Convex project with convex/convex.config.ts
- The @convex-dev/sentinel npm package
- The Convex CLI, for reading errors
- A deployed Convex cloud app to capture production errors
- An AI runner (ai-runner), only if you enable the self-healing cron
How do you ask the agent to use the skill?
You do not need special syntax. Describe what you want in plain language and the agent should match the request to the skill. Name Convex and production errors so the match is clear.
Good requests state the goal. For example, ask the agent to set up error capture, to show you the latest production errors, or to check whether a new error needs attention. The agent will follow the skill's workflow: install the component, wire the client, then read errors.
- Set up production error capture in my Convex app.
- Install Sentinel so server and browser errors are saved to my own deployment.
- Show me the most recent production errors from my Convex deployment.
- Check for new production errors and tell me which ones look recurring.
- Turn on the self-healing cron so recurring errors get a fix pull request.
app.use(sentinel)What does the agent actually change in your project?
The core change is adding the component to convex/convex.config.ts with app.use(sentinel). The agent also wires the client SDK, which means a React error boundary plus handlers for window.onerror and unhandledrejection, along with breadcrumbs that record what happened before an error.
Reading errors uses the Convex CLI through the convex data and run-once-query commands. The monitor emits a prod_error event for new errors, which the agent can react to. Review the diff before you deploy, as you would with any change to your app.
- Adds the component in convex/convex.config.ts
- Adds a React error boundary and global error handlers on the client
- Reads stored errors with convex data and run-once-query
- Listens for the prod_error event on new errors
What is the optional self-healing cron, and how do you control it?
The optional self-healing cron runs a triage step that classifies each error. For recurring errors that are not transient, it hands the error to ai-runner, which opens a fix pull request. This is the part of the skill that changes code automatically, so decide on it deliberately.
The skill's rules also say to sample and cap captured errors to control volume and cost. Keep the cron off until you have reviewed a few pull requests and are comfortable with the results.
- Triage classifies each error
- Recurring, non-transient errors are passed to ai-runner
- ai-runner opens a fix pull request for review
- Sample and cap capture to control volume and cost
What people use it for
- Seeing server function failures from a deployed Convex app without adding a third-party error tracker
- Catching React and browser JavaScript crashes that users hit in production
- Asking the agent to summarise recent production errors and point out recurring ones
- Having an agent triage new errors and open a fix pull request for recurring, non-transient issues
Frequently asked questions
Is convex-sentinel free to use?
The skill is published under the MIT licence, according to this listing. Your Convex deployment, hosting and any AI runner you connect may have their own costs, which are not covered by the skill.
What do I need to install convex-sentinel?
You need a Convex project with convex/convex.config.ts, the @convex-dev/sentinel npm package, and the Convex CLI. To capture production errors, the app must be deployed to Convex cloud. The self-healing cron also needs an AI runner.
Does convex-sentinel send my error data to a third party?
The skill's source says data stays in your own deployment and is not sent to a third party. Redaction runs at write time and is on by default. Note that the agent's reads reach the model provider, so avoid sharing sensitive data in those reads.
Why are no errors showing up after installing it?
Production capture needs a deployed Convex cloud app. Local development and apps that are not yet deployed will not produce production errors. Check that the component is added in convex/convex.config.ts and that the client SDK is wired up.
Does convex-sentinel work outside Convex?
No. The component is for Convex apps, so non-Convex stacks are out of scope for this skill.
Is it safe to let the agent open fix pull requests?
Only if you review the pull requests closely. The optional self-healing cron hands recurring, non-transient errors to ai-runner, which opens a fix PR. Keep it off until you trust the output.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
convex-sentinel suits developers who run a Convex app in production and want error visibility kept inside their own deployment, with an agent that can help triage them. It is a poor fit for local-only projects, non-Convex stacks, or teams that cannot review automated pull requests before merging. If you want an agent to change code automatically, leave the self-healing cron off until you have checked its output.
Download the skill