
watchmen
Surface skill suggestions + workspace context from watchmen sessions intelligence into your Claude Code sessions
- GitHub stars
- 294
Install
/plugin install watchmen@watchmenRun it inside Claude Code after adding the marketplace with /plugin marketplace add firstbatchxyz/watchmen.
Contents
Discovered from sourceSkills 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
-
If the state says
(no state)or(not a tracked project): tell the user there's nothing new and stop. One short sentence. -
Otherwise, summarize in plain English what changed:
- Which skills were added/updated/removed
- Whether CLAUDE.md changed
- When this happened (the
tsfield) - Keep it tight — 3-5 lines max. The user will ask for detail if they want it.
-
If
suggested_skillis 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. -
Include a closing link to the run's details:
- If
diff_urlis 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.
- If
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, orbrew 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
doctorflags. 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 providerto check,watchmen settings api-key --provider <p>to fix - no corpus / 0 sessions → they haven't run
watchmen init(orwatchmen 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.
Hooks 1
Sponsors
Details
- Marketplace
- firstbatchxyz/watchmen
- Source
- plugin
- Category
- Community