Add /checkup skill for Copse setup health diagnostics by jonathanKingston · Pull Request #975 · copse-dev/agent-pane

jonathanKingston · 2026-07-17T01:05:36Z

Summary

Adds a new /checkup skill that provides a read-only health check of the user's Copse setup, similar to Claude Code's /doctor command. The feature diagnoses configuration issues (LLM providers, API keys, MCP servers, skills, context windows, semantic search, permissions, workspace state) and offers actionable fixes.

Key Changes

New checkup report system (checkup-report.ts): Pure, testable report model that builds a structured diagnostic report from a snapshot of the setup state. Includes:
- CheckupSnapshot interface capturing all diagnostic data
- buildCheckupReport() function that evaluates the snapshot and produces checks grouped by severity (error/warn/ok)
- formatCheckupReport() function that renders the report as plain text for the agent to relay
- Comprehensive test suite (checkup-report.test.ts) with 100% logic coverage
Checkup gatherer (checkup.ts): Electron/service-touching layer that collects live setup state and invokes the pure report builder. Gathers:
- App version, platform, workspace/git state
- LLM provider availability and API key encryption status
- MCP server connection states and tool counts
- Skills discovery and custom tool registration
- Semantic search backend availability
- Command permissions and terminal helper executable status
Built-in skills infrastructure (builtin-skills.ts): New system for shipping first-party skills with Copse itself (e.g., /checkup). Skills live in assets/skills/<name>/SKILL.md and are discovered alongside user/project/plugin skills, with project skills able to override built-ins.
Checkup skill (assets/skills/checkup/SKILL.md): User-facing skill that:
- Calls the run_checkup tool to gather diagnostics
- Presents findings grouped by severity with suggested fixes
- Offers to help fix actionable items (with user confirmation)
- Marked with disable-model-invocation: true so it only runs on explicit /checkup invocation
Checkup tool (checkup-tool.ts): New tool that backs the skill, exposing run_checkup to the agent.
Skills registry updates:
- Added listModelInvocableSkills() to exclude skills with disable-model-invocation: true from the model's system-prompt catalog
- Integrated built-in skills discovery into the registry
- Updated tests to cover built-in skill discovery and override behavior
Integration: Registered the checkup tool in the bootstrap registry and added display name mapping.

Notable Implementation Details

The report logic is completely pure and snapshot-based, making it fully unit-testable without Electron/service dependencies
Built-in skills are discovered last during registry refresh, allowing user/project/plugin skills to override them by name
API key encryption status is captured and surfaced as a warning when keys are stored as plaintext (no OS keyring available)
The checkup is read-only and never modifies settings; it only proposes fixes for user approval
Graceful error handling throughout: each diagnostic source fails soft to a safe default rather than crashing the checkup

https://claude.ai/code/session_01FjtSFzviPw8ryFfhSjvcDS

Note

Low Risk
Read-only diagnostics and an always-on tool with no auto-fixes; skills catalog filtering is additive with tests. Minor exposure of setup metadata (e.g. key storage mode) in checkup output only when invoked.

Overview
Adds a /checkup flow (doctor-style) so users can get a read-only report on Copse setup health and optional help fixing issues.

Diagnostics: A snapshot gatherer (checkup.ts) collects live state (providers/API keys and encryption, MCP, skills, context window, semantic search, permissions, workspace/git, terminal spawn-helper). A pure buildCheckupReport / formatCheckupReport layer turns that into severity-grouped checks with suggested fixes; unit tests cover the rules (e.g. plaintext keys, untrusted MCP blocked, missing providers).

Agent surface: Always-on run_checkup tool returns the formatted report; the bundled checkup skill (disable-model-invocation: true) tells the agent to call it only on explicit /checkup, present findings, and not change anything without confirmation.

Skills plumbing: First-party skills ship from assets/skills via builtin-skills (discovered last so project skills can override). listModelInvocableSkills hides user-only skills from the model catalog while keeping them in /name pickers.

^{Reviewed by Cursor Bugbot for commit 6b64b83. Bugbot is set up for automated code reviews on this repo. Configure here.}

Mirror Claude Code's /checkup ("doctor"): a user-runnable command that diagnoses the Copse setup, reports findings by severity, and offers to fix what's actionable. - Diagnostics engine (services/diagnostics): a pure, unit-tested report builder over a snapshot, plus a gatherer that inspects the live setup — LLM providers/API keys and their at-rest encryption, MCP server status, skills, model context window, semantic search, command permissions, app version, workspace/git, and the node-pty terminal helper. - run_checkup tool: always-registered, read-only. Returns the report; the agent surfaces findings and proposes fixes for the user to approve. - First-party checkup + doctor skills shipped under assets/skills and discovered via a new builtin-skills root (copied to dist/assets by the build), so /checkup and /doctor work in any workspace. Added last in discovery so a user/project/plugin skill of the same name can override. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FjtSFzviPw8ryFfhSjvcDS

…r alias Address review feedback on the checkup feature: - Enforce the `disable-model-invocation` skill frontmatter flag, which was parsed into SkillMetadata but never honoured. Add listModelInvocableSkills() and use it to build the model's skill catalog, so a skill marked `disable-model-invocation: true` is never advertised to the model (it can't auto-invoke it) while staying fully user-invocable via the /name picker. - Mark the checkup skill `disable-model-invocation: true` and tighten the run_checkup tool description so a checkup only runs when the user explicitly asks for it, never on the agent's own initiative. - Remove the /doctor alias skill; /checkup is the single entry point. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FjtSFzviPw8ryFfhSjvcDS

MCP servers blocked by an untrusted workspace report state 'untrusted' (with an explanatory error), not 'error', so the checkup ignored them — /checkup could show a healthy MCP summary while those project servers never started. Surface each as a warning with a fix, and count them in the summary so it no longer reads as healthy when nothing connected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FjtSFzviPw8ryFfhSjvcDS

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2bd46af. Configure here.}

node-pty ships with Copse, not the opened project. Probing process.cwd()/node_modules first meant a packaged app launched from an unrelated directory (with its own broken node-pty) could report a false terminal error. Resolve the prebuilds tree from the app instead: the unpacked-asar path when packaged, and cwd only in dev (where the app runs from the repo). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FjtSFzviPw8ryFfhSjvcDS

cursor · 2026-07-17T08:22:47Z

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_56b5d9f7-0ba3-4d4b-ae84-b4f3816546f6)

cursor

Stale comment

Not approving: Cursor Bugbot skipped on the latest sync (usage limit reached), so there is no clean automated review for the current head. Prior Bugbot findings were addressed and their threads are resolved. No reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

cursor · 2026-07-18T00:07:37Z

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b59d2681-8994-475d-ab57-3784498e0914)

cursor

Not approving: Cursor Bugbot skipped on the latest sync (usage limit reached), so there is no clean automated review for the current head. Prior Bugbot findings were addressed and their threads are resolved. No reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

…1003) ## Summary Fixes #1001: auto-merge can land a PR while the trailing `commit-screenshots` job is still queued; GitHub deletes the head branch and the job's checkout fails with `branch not found` — a red X on a successfully-merged PR (observed on #975: merged at 00:36:44, checkout failed at 00:36:46). ## Change New first step probes whether the head branch still exists (plain `gh api` with the job's token). When it's gone, every subsequent step is skipped via `if: steps.head.outputs.exists == 'true'` (combined with the existing conditions on the commit/comment steps) and the job exits green with a `::notice::` explaining why. There is nothing to commit screenshots to once the branch is deleted. YAML validated; conditions preserved verbatim otherwise. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  --- > [!NOTE] > **Low Risk** > CI-only guard on a non-gating trailing job; skips work when the branch is already gone with no change to merge gates or screenshot policy. > > **Overview** > When auto-merge lands the PR while **`commit-screenshots`** is still queued, GitHub deletes the head branch and checkout by **`github.head_ref`** fails with “branch not found,” leaving a red X on an already-merged PR (#1001). > > The job now **probes the head branch first** (`gh api …/branches/$BRANCH`) and sets **`steps.head.outputs.exists`**. If the branch is gone, it logs a **`::notice::`** and **skips** checkout, artifact download, filter/commit/reconcile/push, and the PR comment via **`if: steps.head.outputs.exists == 'true'`** (combined with the existing conditions on commit and comment). The job exits **green** with nothing to push. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit bcc7b21. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  Co-authored-by: Jonathan Kingston <KingstonMailBox@gmail.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

jonathanKingston enabled auto-merge (squash) July 17, 2026 01:05

claude added 2 commits July 17, 2026 01:07

cursor Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread src/main/services/diagnostics/checkup-report.ts

jonathanKingston force-pushed the claude/user-runnable-checkup-wihvt3 branch from d11ce51 to 2bd46af Compare July 17, 2026 01:12

cursor Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread src/main/services/diagnostics/checkup.ts Outdated

claude and others added 2 commits July 17, 2026 01:16

Merge branch 'main' into claude/user-runnable-checkup-wihvt3

2e5644b

cursor Bot reviewed Jul 17, 2026

View reviewed changes

jonathanKingston added this to the Release readiness milestone Jul 17, 2026 — with ChatGPT Codex Connector

Merge branch 'main' into claude/user-runnable-checkup-wihvt3

6b64b83

cursor Bot reviewed Jul 18, 2026

View reviewed changes

jonathanKingston merged commit fbe075f into main Jul 18, 2026
17 of 18 checks passed

jonathanKingston deleted the claude/user-runnable-checkup-wihvt3 branch July 18, 2026 00:36

This was referenced Jul 18, 2026

commit-screenshots races auto-merge branch deletion → red X on merged PRs #1001

Closed

fix(ci): commit-screenshots no-ops green when the PR merged mid-run #1003

Merged

Navigation Menu

Add /checkup skill for Copse setup health diagnostics - #975

Add /checkup skill for Copse setup health diagnostics#975
jonathanKingston merged 6 commits into
mainfrom
claude/user-runnable-checkup-wihvt3

jonathanKingston commented Jul 17, 2026 •

edited by cursor Bot

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

cursor Bot commented Jul 17, 2026

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

cursor Bot commented Jul 18, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jonathanKingston commented Jul 17, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Notable Implementation Details

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot commented Jul 17, 2026

Bugbot couldn't run - usage limit reached

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot commented Jul 18, 2026

Bugbot couldn't run - usage limit reached

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jonathanKingston commented Jul 17, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading