Add a read-only Sprite Inspector pane as a Claude Code mod

.github/workflows/ci.yml

@@ -45,12 +45,20 @@ jobs:
         with:
           node-version: "22"
 
+      # 2.1.287 is the first release with mods generally available: older
+      # validators reject the manifest's `types` contract, though older clients
+      # still load the plugin and ignore its hooks module.
       - name: Install Claude Code CLI
-        run: npm install --global --no-fund --no-audit @anthropic-ai/claude-code@2.1.224
+        run: npm install --global --no-fund --no-audit @anthropic-ai/claude-code@2.1.287
 
       - name: Validate plugin and marketplace manifests
         env:
           CLAUDE_CONFIG_DIR: ${{ runner.temp }}/claude-config
         run: |
           claude plugin validate ./plugins/sprites --strict
           claude plugin validate . --strict
+
+      - name: Test the Sprite Inspector mod
+        env:
+          CLAUDE_CONFIG_DIR: ${{ runner.temp }}/claude-config
+        run: claude plugin test ./plugins/sprites

README.md

@@ -2,7 +2,7 @@
 
 Use [Sprites](https://sprites.dev) from Claude Code as persistent, isolated Linux development environments for builds, tests, sandboxes, previews, and long-running services.
 
-This repository is a Claude Code plugin marketplace containing the `sprites` plugin. The plugin bundles the hosted Sprites MCP server, browser OAuth, workflow skills, explicit status and smoke-test commands, and confirmation hooks for risky remote operations. No Sprites CLI is required.
+This repository is a Claude Code plugin marketplace containing the `sprites` plugin. The plugin bundles the hosted Sprites MCP server, browser OAuth, workflow skills, explicit status and smoke-test commands, confirmation hooks for risky remote operations, and a read-only Sprite Inspector pane. No Sprites CLI is required.
 
 ## Install
 
@@ -43,6 +43,7 @@ An empty Sprite list means the integration is authenticated and working.
 - Automatic workflow guidance for creating, inspecting, and operating Sprites.
 - `/sprites:status` for a read-only integration and authentication check.
 - `/sprites:smoke` for list → create → exec → approved cleanup.
+- `/sprites-inspector` for a read-only pane to browse Sprites, their services, checkpoints, and logs, and to point Claude at one.
 - Confirmation prompts before destroying a Sprite, restoring a checkpoint, replacing the network policy, or serving a new service on the Sprite's URL.
 - Checkpoint prompts before risky remote package installs, migrations, or broad destructive commands.
 
@@ -65,6 +66,35 @@ Claude Code remains on the local machine. The plugin's MCP server is the control
 
 There is no dedicated MCP file-upload tool. Prefer cloning a repository into the Sprite. For small generated files, the bundled skill documents a base64 transfer pattern that avoids fragile shell quoting.
 
+## Sprite Inspector
+
+`/sprites-inspector [name prefix]` opens a pane beside the conversation in the terminal and in the Code tab of the Claude desktop app. It is a [Claude Code mod](https://code.claude.com/docs/en/plugins/mods/overview), the counterpart of the Inspector the hosted server offers MCP App hosts, and calls the same read-only tools over the plugin's own MCP connection:
+
+- Browse and filter Sprites by name prefix (`open_sprite_inspector`), 20 at a time.
+- Select a Sprite to see its organization, creation date, status, and URL (`get_sprite_info`, which does not wake it).
+- Load its services and checkpoints (`service_list`, `checkpoint_list`) and the last 100 lines of a service's logs (`service_logs`). These calls may wake a cold Sprite, so they run only when asked.
+- **Use in chat** tells Claude which Sprite you mean, with its `sprite_id`, so later calls are checked against that exact Sprite rather than a deleted and recreated one with the same name.
+
+The pane never changes a Sprite. It lists again when it is opened and when it regains focus, and does not poll.
+
+Mods need Claude Code 2.1.287 or later. Older versions load the rest of the plugin and skip the pane. Where nothing can draw a pane, such as the VS Code extension's chat panel or `claude -p`, the command answers with a text listing instead.
+
+In auto mode, Claude Code puts the pane's MCP calls to the auto-mode classifier, which has no request of yours to judge a button press by, and refuses them. Allow the pane's read-only tools in your settings to use it there:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_sprites_sprites__open_sprite_inspector",
+      "mcp__plugin_sprites_sprites__get_sprite_info",
+      "mcp__plugin_sprites_sprites__service_list",
+      "mcp__plugin_sprites_sprites__checkpoint_list",
+      "mcp__plugin_sprites_sprites__service_logs"
+    ]
+  }
+}
+```
+
 ## OAuth restrictions
 
 Restricted connector tokens use a non-empty Sprite-name prefix and may limit how many Sprites the connector can create. The usual default is `mcp-`, but Claude learns the actual rule from API responses rather than assuming it.
@@ -105,16 +135,22 @@ python3 scripts/check_repository.py
 python3 -m unittest discover -s tests -v
 claude plugin validate ./plugins/sprites
 claude plugin validate .
+claude plugin test ./plugins/sprites
 ```
 
+`claude plugin test` runs the Sprite Inspector's tests against a stand-in for the MCP server, so it needs no network or sign-in.
+
 ## Repository layout
 
 ```text
 .claude-plugin/marketplace.json  Marketplace catalog
 plugins/sprites/
   .claude-plugin/plugin.json     Plugin manifest
   .mcp.json                      Hosted MCP configuration
-  hooks/hooks.json               Claude Code safety hook
+  hooks/hooks.json               Claude Code safety hook and mod registration
+  hooks/register.tsx             Sprite Inspector mod
+  types/index.d.ts               The mod's state contract
+  tests/                         Sprite Inspector mod tests
   scripts/sprites_guard.py       Dependency-free hook implementation
   skills/                        Workflow skills and references
 ```

plugins/sprites/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "sprites",
   "displayName": "Sprites",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Use Sprites from Claude Code to create, inspect, and operate remote isolated development environments.",
   "author": {
     "name": "Fly.io",
@@ -12,6 +12,7 @@
   "homepage": "https://sprites.dev",
   "repository": "https://github.com/superfly/sprites-claude-plugin",
   "license": "MIT",
+  "types": "./types/index.d.ts",
   "keywords": [
     "sprites",
     "development-environments",

plugins/sprites/README.md

@@ -4,7 +4,7 @@
 
 The Sprites plugin gives Claude Code hosted MCP access to persistent, isolated development environments, plus skills and confirmation hooks for safe remote workflows.
 
-After installation, run `/sprites:status` to list visible Sprites and complete OAuth if needed. Run `/sprites:smoke` for an end-to-end list, create, and exec check with cleanup only after approval.
+After installation, run `/sprites:status` to list visible Sprites and complete OAuth if needed. Run `/sprites:smoke` for an end-to-end list, create, and exec check with cleanup only after approval. Run `/sprites-inspector` to browse Sprites, their services, checkpoints, and logs in a read-only pane, and to point Claude at one.
 
 The local Claude Code workspace and the remote Sprite filesystem are separate. Use the plugin-provided MCP tools for Sprite commands, services, checkpoints, and policy. Do not install the Sprites CLI or register a second MCP server for normal plugin use.
 

plugins/sprites/hooks/hooks.json

@@ -12,5 +12,6 @@
         ]
       }
     ]
-  }
+  },
+  "modules": ["./register.tsx"]
 }