Skip to main content
skill CX Codex

watch · sethgammon — Claude Code skill: what it does, how to install

watch monitors working directory changes and source marker comments to trigger skills or log batch tasks automatically.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What watch does

The skill acts as a file sentinel. It inspects diffs against the latest baseline commit using Git, falling back to file modification timestamps if the directory is not a repository. Once changed files reveal marker comments like @citadel: review or @citadel: test, it routes them directly to matched skills such as /review or queues them as pending intake items.

Running /watch start writes .planning/watch-state.json and prompts you to keep npm run watch:local running in a separate shell. The optional --remote flag switches to cloud routines via CronCreate, but running it at the default five-minute polling rate drains the platform quota of 15 runs per 24 hours in under sixty minutes.

Avoid this skill for one-off manual audits or CI checks: the repository provides separate dedicated commands for those cases.

What it helps with

  • Trigger review or test generation from in-code marker comments
  • Detect modified files across unstaged and committed Git states
  • Deduplicate repeated markers across file edits using SHA256 hashes
  • Queue pending code improvements into structured planning items

Example prompts for the agent

  • /watch start
  • /watch scan
  • /watch status

How to install watch

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill watch -a claude-code

3Manually: put the files in place

~/.claude/skills/watch/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/watch/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about watch

How to install watch in Claude Code?

Run /plugin marketplace add SethGammon/Citadel followed by /plugin install citadel@citadel-local.

What markers does watch react to?

It scans modified files for @citadel: {action} comments, mapping actions like review, test, fix, document, and refactor to corresponding skills.

Why is the --remote flag guarded by a confirmation prompt?

It invokes CronCreate, which consumes the 15 routine runs daily ceiling. At the standard 5-minute schedule, that allowance is exhausted in less than one hour.

Source text

SKILL.md · MIT
---
name: watch
license: MIT
description: >-
  File sentinel that monitors the working directory for changes and marker
  comments, then auto-triggers appropriate skills. Poll-based via git diff
  against the last scan commit. Writes intake items for batch processing and
  routes marker actions through /do. Use for automatic reactions to file
  changes; do NOT use for one-off inspection or tasks needing human judgment
  per file.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - watch
  - watch files
  - watch changes
  - file sentinel
  - monitor files
  - watch start
  - watch stop
  - watch scan
  - marker comments
  - "@citadel"
last-updated: 2026-03-29
---

# /watch -- File Sentinel

Use when the user wants automatic reactions to file changes or marker comments (`@citadel:`).
Do NOT use for one-off file inspection or tasks that need human judgment per file.

## Orientation

**Use when:** running a file sentinel that triggers a skill or command automatically when watched paths change.
**Don't use when:** monitoring CI status on a PR (use /pr-watch); running a one-shot verification check (use /verify).

## Default execution path (READ FIRST)

**`/watch start` does NOT call `CronCreate` by default.** Only pass `--remote`
to use Anthropic's routine system, and only after explicit user confirmation.
`CronCreate` counts against the **15 routine runs / 24h** cap — at the default
5-minute interval a watch exhausts the quota in under an hour.

### Default flow — `/watch start` (no `--remote` flag)
1. Do Steps 1 and 2 below (check existing watch, determine baseline commit).
2. **Skip Step 3** — do NOT call `CronCreate`. Leave `cronId: null` in state.
3. Write the state file (Step 4) with `status: "watching"`.
4. Output:
   ```
   Watch state created: .planning/watch-state.json
     Baseline: {commit hash, first 7 chars}

   To start real-time watching, run in a separate terminal:
     npm run watch:local

   For cloud-persistent polling (machine off, user away):
     /watch start --remote     (uses CronCreate, counts against 15/day cap)
   ```

### Opt-in routine flow — `/watch start --remote`
Only when `--remote` is explicitly passed:
1. Confirm: "This will use `CronCreate`, which counts against your 15 routine
   runs / 24h quota. At a 5-minute interval this exhausts the quota in under
   an hour. Continue? (y/N)"
2. On confirmation, run the full Step 1–5 protocol including `CronCreate`.

## Commands

| Command | Behavior |
|---|---|
| `/watch start` | Default: create state, prompt user to run `npm run watch:local` |
| `/watch start --remote` | Use `CronCreate` polling (counts against 15/day quota — requires confirmation) |
| `/watch start --interval {N}m` | Set poll interval for `--remote` mode (default: 5m) |
| `/watch stop` | Stop watching, tear down cron |
| `/watch status` | Show watch state, last scan time, pending actions |
| `/watch scan` | Run a single scan now (manual trigger) |

## Protocol

### /watch start

#### Step 1: Check for existing watch

1. Read `.planning/watch-state.json` if it exists
2. If `status` is `"watching"`:
   - Show current state: last scan time, interval, pending actions count
   - Ask: "A watch is already active. Stop it and start a new one?"
   - If yes: run `/watch stop` first, then continue
   - If no: abort

#### Step 2: Determine baseline commit

1. Run `git rev-parse HEAD` to get the current commit hash
2. If not a git repo: fall back to timestamp-based detection (store current
   time as `lastScanTime`, skip commit-based diffing)
3. Store this as `lastScanCommit`

#### Step 3: Create poll schedule (--remote only)

```
CronCreate:
  interval: "{N}m"  (default: 5m)
  command: "/watch scan"
```

Save the cron ID in the state file.

#### Step 4: Write state file

Write `.planning/watch-state.json`:

```json
{
  "status": "watching",
  "lastScanCommit": "abc1234",
  "lastScanTime": null,
  "interval": "5m",
  "cronId": "{id from step 3 or null}",
  "pendingActions": {},
  "processedMarkers": {},
  "stats": {
    "scansRun": 0,
    "markersFound": 0,
    "intakeItemsCreated": 0,
    "skillsDispatched": 0
  }
}
```

#### Step 5: Confirm (--remote only)

```
Watch started.
  Interval:  every {N}m
  Baseline:  {commit hash, first 7 chars}
  State:     .planning/watch-state.json
```

---

### /watch stop

1. Read `.planning/watch-state.json`. If missing or not `"watching"`: "No watch is active."
2. `CronDelete: {cronId}` — if cronId is missing or deletion fails, continue.
3. Update state: `"status": "stopped", "cronId": null`. Preserve all other fields.
4. Output:
   ```
   Watch stopped.
     Scans completed:      {stats.scansRun}
     Markers found:        {stats.markersFound}
     Intake items created: {stats.intakeItemsCreated}
     Skills dispatched:    {stats.skillsDispatched}
   ```

---

### /watch status

1. If `.planning/watch-state.json` missing: "No watch configured. Use `/watch start` to begin."
2. Output state fields: status, lastScanTime, lastScanCommit, interval, pendingActions.length, stats.
3. If `pendingActions` non-empty, list each: `[{action}] {file}:{line} -- {description}`

---

### /watch scan

#### Step 1: Load state

1. Read `.planning/watch-state.json`
2. If missing: create default state with `lastScanCommit` from `git rev-parse HEAD` and `status: "watching"`.

#### Step 2: Detect changed files

**Git mode (primary):**
1. `git diff --name-only {lastScanCommit} HEAD` (committed changes)
2. `git diff --name-only` (unstaged) and `git diff --name-only --cached` (staged)
3. Merge and deduplicate all three lists

**Fallback mode (no git):**
1. `find . -newer {timestamp_file} -type f`
2. Exclude `node_modules/`, `.git/`, `.planning/`, `dist/`, `build/`

If no files changed: update `lastScanTime` and `stats.scansRun`, exit early.

#### Step 3: Scan for marker comments

Search changed files for:

| Pattern | Languages |
|---|---|
| `// @citadel: {action} {description}` | JS, TS, Go, Rust, C, Java |
| `# @citadel: {action} {description}` | Python, Shell, YAML, Ruby |
| `/* @citadel: {action} {description} */` | CSS, multi-line C-style |
| `<!-- @citadel: {action} {description} -->` | HTML, Markdown |

**Action-to-skill mapping:**

| Action | Skill |
|---|---|
| `review` | `/review` |
| `test` | `/test-gen` |
| `fix` | `/systematic-debugging` |
| `document` | `/doc-gen` |
| `refactor` | `/refactor` |
| `todo` | intake item |

Unknown actions become intake items with the action preserved as metadata.

**Deduplication:** Every marker gets a stable identity hash: sha256 over `{file path}`, `{action}`, and the normalized marker text (trimmed, internal whitespace collapsed), joined with NUL separators and truncated to 16 hex chars. Line numbers are excluded, so the hash survives line shifts. `processedMarkers` is a map keyed by this hash with `{file, action, firstSeen, lastSeen}`; `pendingActions` uses the same hash keys. Both maps are pruned past 500 entries by dropping the oldest `lastSeen`. Markers whose hash is already in `processedMarkers` are skipped.

#### Step 4: Classify unmarked changes

| File pattern | Auto-action |
|---|---|
| `*.test.*`, `*.spec.*`, `__tests__/*` | Queue: "run tests" intake item |
| `*.md` in `docs/` or project root | Queue: "doc staleness check" intake item |
| `src/**/*.ts`, `src/**/*.tsx` | Queue: "changed source" intake item |
| `package.json`, `tsconfig.json` | Queue: "config change" intake item (high priority) |

#### Step 5: Dispatch markers

For each new marker:
1. `/do {action} in {file} at line {line}: {description}`
2. Log dispatch, add to `processedMarkers`, increment `stats.skillsDispatched`

**Batch limit:** Dispatch at most 5 per scan. Queue overflow in `pendingActions`.

#### Step 6: Write intake items

Filename: `watch-{action}-{file slug}-{epoch ms}.md` in `.planning/intake/`

```markdown
---
title: "{action} {file}:{line}"
status: pending
priority: normal
target: {file path}
source: watch
marker_hash: {16-char marker hash}
---

Marker comment found at {file}:{line}:
`{raw marker line}`

{description, if any}
```

Before writing, skip the item if the marker hash is already in `processedMarkers`, or if any existing `.planning/intake/*.md` carries a matching `marker_hash` in its frontmatter. Every new intake item records its `marker_hash` so future scans (and concurrent processes) can detect it.

#### Step 7: Update state

- `lastScanCommit`: `git rev-parse HEAD`
- `lastScanTime`: current ISO timestamp
- Increment `stats.scansRun`, `stats.markersFound`
- Update `pendingActions` and `processedMarkers`

#### Step 8: Report

Manual scan:
```
Scan complete.
  Files changed:      {N}
  Markers found:      {new} ({total} total)
  Actions dispatched: {N} (batch limit: 5)
  Intake items:       {N} written to .planning/intake/
  Pending actions:    {N}
```

Cron poll: silent.

---

## Integration Points

- **Intake pipeline:** Writes to `.planning/intake/` for `/autopilot`.
- **Intent router:** Routes markers through `/do` — never invokes skills directly.
- **Daemon:** `/daemon` can start a watch alongside a campaign.

---

## Fringe Cases

**`.planning/` missing:** Create on first scan.
**Not a git repo:** Fall back to timestamp detection; warn once.
**No files changed:** Update stats, exit silently.
**Unknown action:** Treat as intake item, preserve raw action.
**Deleted file:** Skip marker scanning; write intake item noting deletion.
**Large diff (100+ files):** Cap at 50 per scan, queue rest.
**Binary files:** Skip during marker scanning.
**Corrupted state:** Reset to defaults, preserve `processedMarkers` if readable.
**CronCreate not available:** Warn and suggest manual `/watch scan`.
**Scan overlap:** Scans serialize through a lock directory (`.planning/watch-state.json.lock`, acquired via atomic `mkdir` with ~10 retries at 100ms). Each scan records `scanStartedAt` and `scanPid` in state under the lock, and holds the lock across the state read-modify-write and intake writes. A scan that cannot acquire the lock and finds another scan started under 60 seconds ago logs a skip notice and exits cleanly. A lock older than 30 seconds (by mtime) is treated as stale and removed.
**Marker removed:** Stale `processedMarkers` entries age out via the 500-entry oldest-`lastSeen` prune.

---

## Contextual Gates

**Disclosure:** "Starting file watch on [paths]. Triggers [skill] on change. Stop with Ctrl+C."
**Reversibility:** amber — runs sentinel that triggers other skills on file change; triggered skills may modify files; stop with Ctrl+C and run `/watch stop`
**Trust gates:**
- Any: start watch and view scan reports
- Familiar (5+ sessions): triggered skills run autonomously on file change; novices should use with caution and review dispatched actions

## Quality Gates

- Scan completes in under 10 seconds for repos up to 100K lines
- No duplicate intake items for the same file and classification
- No re-dispatched already-processed markers
- Batch limit of 5 dispatches per scan enforced
- State file updated atomically at end of scan
- Works on Windows, macOS, Linux (Node.js fs + git CLI)
- CronCreate failure does not leave watch in inconsistent state

## Exit Protocol

- **`/watch start`:** Output confirmation block. No HANDOFF.
- **`/watch stop`:** Output stop summary with lifetime stats.
- **`/watch scan` (manual):** Output scan report with counts.
- **`/watch scan` (cron):** Silent.
- **`/watch status`:** Output current state.
- **On error:** Clear message with fix. Never leave cron running if state is inconsistent.

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

watch by other authors comes first.

watch bradautomates watch analyzes a video from a URL or local path, collects frames and a transcript, then lets the agent answer questions about the footage. Useful for video review inside an IDE. CX Codex +1 19,300installs watch diffusionstudio watch — a skill for analyzing video and audio files on Claude Code, Codex, Cursor, and other platforms. Answers questions about content, locates scenes and moments, extracts quotes, and describes what happens and when. CX Codex +1 2,000installs watch oxbshw watch examines linked or local videos, extracts frames and speech, then answers questions from an index. Use it to review a recording or check your own interface. CX Codex +1 948installs security-investigator-automation reason-machines security-investigator-automation — a skill that runs security investigations across Microsoft Sentinel, Defender XDR and Graph API from a plain-language request. CX Codex +1 326installs re0-watch LilMGenius re0-watch — a skill for Claude Code that watches long-running agent jobs for stalls and generates recovery proposals for human approval. CX Codex +1 129installs microsoft-security-skills-plugin reason-machines This skill gives AI agents Microsoft Security guidance for Defender, Sentinel, Entra, Purview, and Intune. Use it when planning policies or security workflows. CX Codex +1 276installs terraform-policy hashicorp This skill writes, tests, and converts Terraform Policy files. Use it for .policy.hcl, .policytest.hcl, and Sentinel migration tasks. CX Codex +1 1,800installs MCP Server for Binge-watch aahl MCP Server for Binge-watch finds media streaming links for shows and sends playback commands directly to Xiaomi TVs or Android devices running TvBox. CX Codex +1 ★ 27repo stars watch-video MarcinSufa watch-video is a Claude Code plugin that turns videos into timestamped frames, a Whisper transcript, and reports in three formats. ★ 9repo stars

From the same set55

The whole set →
houseclean houseclean audits every attached drive for abandoned git worktrees, bloated AI-tool caches, and rebuildable build artifacts, then lays out a cleanup plan. CX Codex +1 ★ 937repo stars pr-watch pr-watch monitors pull request CI status in the terminal, inspects failure logs, applies code fixes, and prompts to merge. CX Codex +1 ★ 937repo stars ascii-diagram The ascii-diagram skill plans and renders aligned text diagrams with boxes and arrows. Use it when a diagram needs to live in Markdown, a code comment, or plain text. CX Codex +1 ★ 937repo stars triage triage — a skill for investigating GitHub issues and reviewing PRs. Reads open issues, classifies them, searches the codebase for root cause, proposes fixes with file:line references, and optionally implements them. CX Codex +1 ★ 937repo stars telemetry Displays session cost, spending today and all-time totals, hook activity, trust level, and a directory of telemetry commands. CX Codex +1 ★ 937repo stars experiment experiment runs scalar-metric optimization loops in isolated worktrees, checking each candidate against a locked baseline before it's kept. CX Codex +1 ★ 937repo stars research research investigates technical questions, cross-references documentation, and saves structured Markdown briefs with confidence ratings. CX Codex +1 ★ 937repo stars learn learn turns completed campaigns or evolve cycles into structured project wiki entries. Use it to carry decisions and recurring patterns into future sessions. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open