Surface skill suggestions + workspace context from watchmen sessions intelligence into your Claude Code sessions

GitHub stars
294

Install

/plugin install watchmen@watchmen

Run it inside Claude Code after adding the marketplace with /plugin marketplace add firstbatchxyz/watchmen.

Contents

Discovered from source

Skills 2

Watchmen brief

You are reporting watchmen's latest findings for the user's current workspace. The user invoked you because they saw a 💡 watchmen indicator in their statusLine and want to know what changed.

Current state for this workspace

The block below contains the JSON state file watchmen wrote at the end of its last curator run for this project. If it says (no state) or (not a tracked project), watchmen has nothing new to report.

!${CLAUDE_PLUGIN_ROOT}/bin/read_state.sh

What to do

  1. If the state says (no state) or (not a tracked project): tell the user there's nothing new and stop. One short sentence.

  2. Otherwise, summarize in plain English what changed:

    • Which skills were added/updated/removed
    • Whether CLAUDE.md changed
    • When this happened (the ts field)
    • Keep it tight — 3-5 lines max. The user will ask for detail if they want it.
  3. If suggested_skill is non-null in the state: ask the user "Want me to load the <skill> skill for this session?" and wait for a yes/no. If yes, instruct them to invoke it (e.g. /skill-name) — you can't load it programmatically, only signal.

  4. Include a closing link to the run's details:

    • If diff_url is non-null (schema 2+): show that — it points at the side-by-side diff for this exact run, e.g. Diff: http://127.0.0.1:8979/p/kai-agent-new/diff/<sha>
    • Else fall back to viewer_url (the project overview page)
    • One line, link only — no extra commentary.

The read_state.sh call also touches an acknowledgment file, which clears the statusLine indicator for this project. So once you've shown the user this brief, the indicator will be gone until the next curator run.

Set up watchmen

You are guiding the user through installing and wiring watchmen on this machine. watchmen is a local CLI that turns past coding-agent sessions into a curated skills library and surfaces it back into new sessions. This skill is a thin orchestrator: you run the non-interactive shell steps yourself, and for the steps that are interactive (the init wizard) or that only the agent UI can do (/plugin), you give the user the exact commands and wait.

Do not touch the user's API keys or credentials directly — the init wizard handles provider auth. Never paste a key on the user's behalf.

Before you start

Check what's already here so you don't redo work:

!uname -s; command -v uv >/dev/null && echo "uv: $(uv --version)" || echo "uv: MISSING"; command -v watchmen >/dev/null && echo "watchmen: $(watchmen --version 2>/dev/null)" || echo "watchmen: not installed"

Read that output and branch:

  • uv: MISSING → stop and tell the user to install uv first (curl -LsSf https://astral.sh/uv/install.sh | sh, or brew install uv), then re-run this skill. uv is the only hard prerequisite besides a provider credential.
  • watchmen already installed → skip to step 3 (verify) and only fix what doctor flags. Don't reinstall over a working setup.
  • Fresh machine → walk steps 1 → 4 in order.

1. Install the CLI

watchmen installs as an editable uv tool from a clone, so git pull + the daemon pick up updates:

git clone https://github.com/firstbatchxyz/watchmen.git
cd watchmen
uv sync && uv tool install --editable .

Run these for the user (pick a sensible parent dir, or ask where they want the clone). If the clone already exists, cd into it and just run the uv sync && uv tool install --editable . line.

2. Run the init wizard (interactive — hand off)

watchmen init is an interactive wizard: it asks which LLM provider to use (OpenRouter / OpenAI / Anthropic, or an OAuth subscription on macOS), prompts for that provider's API key, ingests ~/.claude/projects/ history, lets the user pick projects, previews cost, runs analyze + curate, and installs the daemon + viewer for autostart.

You can't drive an interactive prompt cleanly, so tell the user to run it themselves in their terminal:

watchmen init

Wait for them to confirm it finished before continuing. If they'd rather skip the wizard and just install the background services with defaults, watchmen up is the non-interactive equivalent (no provider/project picking) — but they'll still need a provider credential set via watchmen settings api-key or an OAuth login.

3. Wire the plugin into the agent (agent UI — hand off)

The plugin (skill suggestions + the /watchmen:brief digest) installs through the agent's own plugin system, which you cannot invoke from here. Give the user the exact commands for whichever agent(s) they use and ask them to paste them.

Claude Code:

/plugin marketplace add firstbatchxyz/watchmen
/plugin install watchmen@watchmen
/reload-plugins

Then the statusLine (this one you can run for them):

watchmen statusline install

Codex:

/plugins marketplace add github:firstbatchxyz/watchmen
/plugins install watchmen

(Codex has no statusline; the digest is on-demand via brief / $brief instead.)

If watchmen was already installed and you're updating it, the refresh path is /plugin marketplace update watchmen then reinstall — the plugin only re-caches when its version changes.

4. Verify

Run doctor and read it back to the user:

!watchmen doctor 2>&1 | tail -20

Walk the ✓/✗/! lines. Common follow-ups:

  • viewer not responding → watchmen viewer install
  • hooks not wired → watchmen hooks install
  • API key invalid/missing → watchmen settings provider to check, watchmen settings api-key --provider <p> to fix
  • no corpus / 0 sessions → they haven't run watchmen init (or watchmen ingest) yet

Close with a one-line "you're set up" summary and point them at watchmen status for the daily view and watchmen --help for the full command surface. Keep the whole interaction tight; only dig into a step if it failed.

Sponsors

Details

Marketplace
firstbatchxyz/watchmen
Source
plugin
Category
Community