Guide · Agent skill
How to use the Convex app log and health queries agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
convex-insights is an agent skill that teaches an AI agent how to read the logs and health data of a live Convex app, a hosted backend platform, using the official Convex MCP tools. It is for developers and teams who want quick, evidence-backed answers about recent errors or deploy problems without clicking through the dashboard. After this guide you will know what the skill does, how to install it, how to phrase requests so it triggers, and what to check before trusting its answers.
Convex app log and health queriesopenclaw/clawhub · MIT Download the skill Quick start
- 1Download the ZIP. Download the convex-insights ZIP from this page. It contains SKILL.md.
- 2Install the skill. Unzip into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
- 3Connect the Convex MCP server. Make sure your agent has the official Convex MCP server with the logs, insights, functionSpec and status read tools.
- 4Confirm the deployment. Ask the agent to identify the deployment it will read and check that it is the one you intend, especially for production.
- 5Ask a specific question. Describe the failure, function or deploy you care about in plain language.
- 6Check the evidence. Review the one-line finding, the counts and the representative stack, then open the dashboard link to verify.
What the convex-insights skill makes the agent do
A skill is a folder of instructions that an AI agent loads when a task matches it. This one covers operational questions about a Convex deployment: what is failing, what changed after a deploy, and why one specific call failed.
The agent does not guess. It first confirms which deployment it is reading and checks the real function names and deployment status. It then fetches a bounded window of recent logs and filters that window itself, because the log tool does not offer server-side filters by function, status, request ID or time.
The skill uses one of three views per question. The failures view counts errors grouped by function and error message. The health view surfaces typed read-limit and write-conflict events from the insights tool, which is available for cloud dev and prod deployments only. The trace view follows one request ID or function call to read its full execution.
Every answer has three parts: a one-line finding, the evidence (counts plus one representative stack or log line), and where possible a link to the Convex dashboard so you can verify it yourself. The skill is designed to be read-only.
Install the convex-insights skill
Download the ZIP of the skill from this page. The skill is distributed as a single file named SKILL.md inside the package.
For Claude Code, unzip the package into your user skills folder at ~/.claude/skills/, or into a project-specific folder at .claude/skills/ inside your project. Either location works; use the project folder if you want the skill only for one codebase.
In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.
You also need the official Convex MCP server connected to your agent, with its read tools available. The skill's workflow depends on the logs, insights, functionSpec and status tools.
- Claude Code: ~/.claude/skills/ for all projects, or .claude/skills/ for one project
- Claude apps: Settings, then Capabilities, then Skills, then upload the ZIP
What you need before you start
The skill only works with Convex. It is not useful for apps built on other platforms, because it relies entirely on the Convex MCP tools.
You need a Convex account and a deployment to read from. The insights part of the skill works only on cloud dev and prod deployments and requires user authentication. The logs part works with the deployment you select.
The skill runs on an MCP-capable agent such as Claude Code. It does not run scripts. It does use the network, because it calls the Convex MCP tools that read your deployment.
- Convex MCP server (official) with the read tools logs, insights, functionSpec and status
- A Convex account and a deployment to read from
- An MCP-capable agent such as Claude Code
How to trigger the skill with natural requests
Ask in plain language about a specific problem and name the deployment or function if you know it. The agent will decide which view fits your question.
Good requests describe what you want to know: which functions are erroring, whether a recent deploy caused new failures, or why one call failed. Vague requests such as 'check my app' will work less well because the agent has no scope to work within.
- What failed after the last deploy?
- Which Convex functions are erroring in production right now?
- Why did the sendMessage call from this request fail?
- Are we hitting read limits or write conflicts on the dev deployment?
Read the answer and verify it in the dashboard
Check the one-line finding first, then the counts and the representative stack. The counts show how widespread the problem is; the stack shows where it happens.
If the answer includes a dashboard link, open it to confirm the same errors appear in the Convex dashboard. The agent builds this link from the deployment name and function name, because no tool returns it, so a link can occasionally be imperfect. If it does not open the expected view, search the dashboard for the function name shown in the evidence.
When the question is about deploy causality, the agent compares the time of the first failures with the deployment version from the status tool. Treat that as a correlation to investigate, not proof that the deploy caused the problem.
Hand-offs for performance, cost and code defects
The skill reports slow and expensive functions but does not fix them. When the cause is performance or cost, it passes the finding to convex-advisor, which owns those fixes. A code defect is routed to convex-reviewer or convex-authz, and an error you want to react to going forward goes to monitor or sentinel.
Expect the agent to say when it is handing off rather than proposing a code change itself.
logs --history <n> --jsonlSafety notes: scripts, network and production
The skill runs no scripts. It uses the network only to reach the Convex MCP tools. It is designed to be read-only: an insights pass runs no mutation and does not enable production mutation flags.
Still, the skill depends on the agent choosing the correct deployment. Confirm the deployment name the agent announces before you act on any answer, especially for production. Do not use this skill as a way to change data or settings in production.
- No scripts are run by the skill
- Uses the network to call the Convex MCP tools
- Read-only by design; confirm the target deployment before acting
What people use it for
- Finding which functions started failing after a recent deploy
- Grouping errors by function and message to see what is most common in the last window of logs
- Tracing one failed request or function call through its full execution
- Checking whether the dev or prod deployment is hitting read limits or write conflicts
- Getting a quick health summary before deciding whether to hand a slow function to convex-advisor
Frequently asked questions
How do I install the convex-insights skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside a project. In the Claude apps, you can upload the ZIP under Settings, then Capabilities, then Skills.
Is the convex-insights skill free?
The skill is released under the MIT licence, as listed on this page. Convex itself requires a Convex account and a deployment to read from, so check Convex's own terms for your account.
What do I need to use convex-insights?
You need the official Convex MCP server with the logs, insights, functionSpec and status read tools, a Convex account, a deployment to read from, and an MCP-capable agent such as Claude Code. The insights tool works only on cloud dev and prod deployments and needs user authentication.
Can the skill fix slow or expensive Convex functions?
No. It reports slow and expensive functions and hands the root-cause work and fixes to convex-advisor. It is meant for finding and explaining problems, not changing your code.
Why does the skill fetch logs and filter them itself?
The logs tool only accepts a count of recent entries, not a time window, and has no server-side filter by function, status or request ID. The skill fetches a bounded recent window and filters it locally, so results cover only the window it fetched.
Does the skill change anything in my production deployment?
It is designed to be read-only and does not run mutations or enable production mutation flags for an insights pass. You should still confirm which deployment the agent is reading, because the skill depends on that choice being correct.
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
Use convex-insights if you run a Convex backend and want fast, evidence-backed answers about recent errors, failed requests or whether a deploy caused new failures. Pick something else if your app is not on Convex, or if you need the agent to fix performance or cost problems directly, since those are handed to convex-advisor.
Download the skill