From 299498288189f8b6bbcc8f0d60e1805575813727 Mon Sep 17 00:00:00 2001 From: aktasbatuhan Date: Mon, 8 Jun 2026 23:43:34 +0100 Subject: [PATCH 1/2] =?UTF-8?q?feat(plugin):=20add=20`setup`=20skill=20?= =?UTF-8?q?=E2=80=94=20guided=20watchmen=20install=20across=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A thin orchestrator skill (`/watchmen:setup` in Claude Code, `/skills setup` or `$setup` in Codex) that walks a user through installing and wiring watchmen: detects uv + existing install, installs the CLI, hands off the interactive `watchmen init` wizard and the agent-only `/plugin` steps, wires the statusline, and verifies with `watchmen doctor`. Cross-agent: covers both Claude Code and Codex. Never touches credentials — defers all provider auth to the init wizard. - plugin/skills/setup/SKILL.md (Claude variant, with allowed-tools) - plugin-codex/skills/setup/SKILL.md (Codex variant: $-invocation, AGENTS.md, no statusline, no allowed-tools — matching the brief skill's conventions) - Bump both plugin manifests 0.1.7 -> 0.1.8 (the #123 CI guard requires a bump when plugin/skills changes; keeps the two harnesses in version lockstep). Note: shipping in the plugin means a brand-new user can't invoke it until they install the plugin (the thing it sets up) — it's primarily for wiring a second agent, repairing, or verifying. A standalone-install README line can follow. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugin-codex/.codex-plugin/plugin.json | 2 +- plugin-codex/skills/setup/SKILL.md | 86 +++++++++++++++++++++++ plugin/.claude-plugin/plugin.json | 2 +- plugin/skills/setup/SKILL.md | 97 ++++++++++++++++++++++++++ 4 files changed, 185 insertions(+), 2 deletions(-) create mode 100644 plugin-codex/skills/setup/SKILL.md create mode 100644 plugin/skills/setup/SKILL.md diff --git a/plugin-codex/.codex-plugin/plugin.json b/plugin-codex/.codex-plugin/plugin.json index d3b3003..10ac1dc 100644 --- a/plugin-codex/.codex-plugin/plugin.json +++ b/plugin-codex/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "watchmen", - "version": "0.1.7", + "version": "0.1.8", "description": "Skill suggestions + workspace context from your watchmen sessions corpus, surfaced into Codex sessions.", "author": { "name": "Dria", diff --git a/plugin-codex/skills/setup/SKILL.md b/plugin-codex/skills/setup/SKILL.md new file mode 100644 index 0000000..0b9308e --- /dev/null +++ b/plugin-codex/skills/setup/SKILL.md @@ -0,0 +1,86 @@ +--- +name: setup +description: Set up watchmen end-to-end for the current machine — install the CLI, run the init wizard, wire the plugin into Codex (and Claude Code), and verify the install with doctor. Use when someone wants to install, onboard, or configure watchmen with their coding agent. +--- + +# 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 install), 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: + +```bash +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: + +```bash +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 `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. + +**Codex:** + +``` +/plugins marketplace add github:firstbatchxyz/watchmen +/plugins install watchmen +``` + +You then get `/skills brief` (or `$brief`) inside Codex with the workspace digest. Codex has no statusline, so the skill-suggestion hint is on-demand `brief` instead of a live indicator. + +**Claude Code:** + +``` +/plugin marketplace add firstbatchxyz/watchmen +/plugin install watchmen@watchmen +/reload-plugins +``` + +Then the statusLine, one-time (Claude Code only): `watchmen statusline install`. + +If watchmen was already installed and you're updating it, the refresh path is `/plugins 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

` 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. diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 7bc013f..d7ca0d4 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "watchmen", "description": "Surface skill suggestions + workspace context from watchmen sessions intelligence into your Claude Code sessions", - "version": "0.1.7", + "version": "0.1.8", "author": { "name": "dria", "url": "https://github.com/firstbatchxyz/watchmen" diff --git a/plugin/skills/setup/SKILL.md b/plugin/skills/setup/SKILL.md new file mode 100644 index 0000000..c62cf95 --- /dev/null +++ b/plugin/skills/setup/SKILL.md @@ -0,0 +1,97 @@ +--- +name: setup +description: Set up watchmen end-to-end for the current machine — install the CLI, run the init wizard, wire the plugin + statusline into Claude Code (and Codex), and verify the install with doctor. Use when someone wants to install, onboard, or configure watchmen with their coding agent. +allowed-tools: + - Bash(uname*) + - Bash(which*) + - Bash(command -v*) + - Bash(uv*) + - Bash(git clone*) + - Bash(watchmen*) +--- + +# 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: + +```bash +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: + +```bash +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): + +```bash +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

` 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. From 9c7b92f041d4e7211b5fb5c913d48098d28e3b96 Mon Sep 17 00:00:00 2001 From: aktasbatuhan Date: Tue, 9 Jun 2026 00:08:54 +0100 Subject: [PATCH 2/2] docs(readme): document the setup skill + standalone pre-install path Adds a 'Guided setup skill' note to the Plugins section: how to invoke /watchmen:setup (or $setup in Codex) once installed, and how to curl the SKILL.md into ~/.claude/skills/ standalone so a brand-new machine can run it before any plugin exists (resolving the in-plugin chicken-and-egg). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 250187b..881bd08 100644 --- a/README.md +++ b/README.md @@ -139,6 +139,18 @@ watchmen statusline install You then get `/skills brief` (or `$brief`) inside Codex with the same workspace digest behavior as `/watchmen:brief` in Claude Code. Codex has no statusline, so the live skill-suggestion hint is on-demand `brief` instead. +### Guided setup skill + +Once the plugin is installed, `/watchmen:setup` (Claude Code) or `$setup` (Codex) walks the whole flow above for you — install check, the `init` wizard hand-off, the `/plugin` steps, statusline, and a closing `watchmen doctor`. Handy for wiring a second agent, repairing, or verifying an install. + +To use it on a fresh machine *before* any plugin exists, drop the skill in standalone first, then start a new Claude Code session and run `/setup`: + +```bash +mkdir -p ~/.claude/skills/setup +curl -fsSL https://raw.githubusercontent.com/firstbatchxyz/watchmen/main/plugin/skills/setup/SKILL.md \ + -o ~/.claude/skills/setup/SKILL.md +``` + ## Requirements - macOS, Linux, or Windows 10/11