ClaudeWatch

Imported from chris-peterson/ClaudeWatch (AGENTS.md). Install upstream with npx skills add chris-peterson/ClaudeWatch. Copyright stays with the author.

AGENTS.md — Working on ClaudeWatch

This is the build philosophy and key constraints document for ClaudeWatch. The contract lives in SPEC.md; this document captures the how to think about it. Every Claude Code session should read this before making non-trivial changes.

What ClaudeWatch is

A Claude Code plugin that wraps every shell invocation — Bash and Monitor, which runs its command in the same shell — in a PreToolUse hook and applies regex-based safety rules. The core safety advantage over Claude Code's built-in deny rules is that patterns match anywhere in the command string (re.search()), so compound commands (git add . && git push --force), heredocs, and reordered flags are not bypassable by syntactic tricks.

Core contracts (don't break these)

1. Determinism. Given the same command, the same cwd and project root, the same watches/ tree, and the same on-disk state of the paths those name, the engine must always produce the same decision. No clocks, no randomness, no network on the decision path. cwd and CLAUDE_PROJECT_DIR enter the decision only as the deterministic per-invocation inputs the is_in_project_tree predicate ([RL-15], [RL-16]) resolves rm targets against — pure string work, no filesystem access. CLAUDE_PROJECT_DIR is the one environment variable on the decision path; CLAUDEWATCH_LOG governs a side channel only. The one predicate that does read the filesystem is is_recoverable ([RL-18]), which asks git whether a delete target could be restored — a question with no textual answer. Its calls are read-only, bounded, and fail closed, so the decision stays a function of the command, the roots, and the on-disk state those name; a second predicate wanting filesystem access is a spec change, not a local call. Decision logging (on by default, see [LOG-01]–[LOG-04]; CLAUDEWATCH_LOG=off opts out) is a side channel: it stamps a timestamp and writes a file after the decision is computed, never feeding back into it. Keep it that way — the clock stays in _log_event, not in evaluate_rules.
2. Exit code is always 0. A non-zero exit blocks the host (Claude Code) from getting a useful decision. All errors are surfaced as deny decisions with explanatory messages.
3. Single coalesced decision per invocation. Multiple matching rules across multiple rule sets aggregate into one deny (preferred) or one ask. Never emit more than one decision.
4. The engine ships self-contained. scripts/watchdog.py and everything on the decision path use only the Python standard library (with a minimal built-in YAML parser), so the plugin installs cleanly and evaluates rules fast in any environment Claude Code runs in — no pip step on the hot path. Build- and release-time tooling that never runs on the decision path (e.g. shipyard's gen-plugin-json, run by CI's project job) may use PyYAML; it never runs in the hook.
5. Allow-by-default. When no rule matches, the engine produces no stdout output. Silence is allow.

Build philosophy

• The engine is generic; the rules are domain-specific. Treat scripts/watchdog.py as a stable library. New safety domains are new YAML files in watches/, not new code.
• unless_condition predicates are the one exception, so keep them thin. A predicate answers something a regex cannot — "does this path resolve inside the tree" — so it is domain logic living in the engine, and adding one is an engine change with a spec requirement behind it. Push everything that isn't the domain judgment down into a shared helper: _command_operands parses POSIX utility syntax and takes the program as an argument, so a predicate for a different destructive tool reuses it rather than writing a second tokenizer that drifts from its guards. A predicate that has grown its own parsing is the signal that something belongs in the shared layer.
• Make adding a rule set frictionless. Drop a watch-*.yml file, add a test file, regenerate docs. No registration, no manifest, no engine change.
• Rules are documentation. Every rule has a reason and (almost always) a ref URL. The canonical message is <rule>: <reason> — <ref>, used verbatim in the prompt and the log alike; the rule-set name is omitted since the ref URL supplies it. If you can't articulate why a rule exists, don't add it.
• Block is for "no recovery"; ask is for "permanent but recoverable". git push --force blocks (overwrites remote history). git commit asks (you can amend or reset). When in doubt, prefer ask — block rules are un-bypassable.
• except is a noise filter, not a security exception. except only applies to ask rules; block rules ignore it with a stderr warning. Use except to skip prompts on demonstrably-safe variants (rm -rf /tmp/...), not to make a block rule "softer."
• Allow-by-default (deny-list) vs ask-by-default (allow-list). Most sets are deny-lists: allow-by-default, enumerate the dangerous ops as block/ask — you don't want to prompt on every git status. Flip to an allow-list — one broad catch-all ask plus an except for the safe subset — only when the tool surface is huge and mostly consequential (a cloud control plane), the safe subset is small and cleanly identifiable (AWS get-/list-/describe-/ head- verbs), and an un-prompted action is costly (spend, data loss, prod change). Litmus test: enumerate the small side. watch-aws is the allow-list example; watch-git is the deny-list example.

Repo conventions

• One Python file (scripts/watchdog.py), one YAML format, one hook config (hooks/hooks.json). Resist refactoring into modules until there's a concrete reason — the simplicity is a feature.
• Tests are bash scripts that pipe JSON to the engine and assert decisions. Keep them readable and self-contained — tests/test-watch-<name>.sh mirrors watches/watch-<name>.yml. Those files each load one rule set, which is how the engine is not invoked: the hook loads the whole directory, so a rule reading a token out of another tool's command costs a prompt no per-set file can see. tests/test-all-watches.sh is the tier that evaluates against watches/ entire — put a cross-set expectation there.
• Docs are generated from rules YAML by build/gen-rules-doc.py. Don't hand-edit docs/_site content for rule references; edit the YAML and run just docs.

When making changes

• Rule edits — Use /ClaudeWatch:rules for interactive edits; it validates and previews. Manual edits to YAML are fine for bulk changes, but run just test before committing.

• Engine changes — Update scripts/watchdog.py and tests/test-engine.sh in the same change. The engine has a small surface; every behavior should be exercised by a test.

• New or changed rule set — Add/edit watches/watch-<name>.yml and tests/test-watch-<name>.sh. No hooks.json change needed (auto-discovery). A rule set is described in hand-maintained indexes that drift independently — update whichever the change affects:

  1. README.md — rule-sets table (one row per set)
  2. SPEC.md [SH-01] — enumeration with block/ask coverage prose

  The docs/_site reference is generated, not hand-maintained — run just docs. A dev-time PostToolUse hook (.claude/settings.json → .claude/hooks/remind-rules-index.py) emits this same checklist after any watches/watch-*.yml Write/Edit so it isn't forgotten; it is not part of the shipped plugin.

• Spec changes — Update SPEC.md first. If a code change reveals a spec problem (ambiguity, missing requirement), note it and resolve via the Gap Resolution Protocol (see the spec-driven recipe), don't silently change the implementation.

plugin.yml is canonical

plugin.yml (repo root) is the single source of truth for the plugin's descriptor. .claude-plugin/plugin.json is generated from it — don't hand-edit plugin.json. The suite: block also feeds the bridge.ai marketplace SPA.

CI is the only writer. .github/workflows/project.yml runs shipyard's project action on every push, which regenerates plugin.json, hooks.json, and plugin.yml's suite.describe block from their sources and commits the result straight back to the branch — so a committed artifact matches its source at all times, and the diff a reviewer approves is the change that lands. Editing plugin.yml, hooks/hooks.yml, a skill, or a rule needs no local regeneration step; push, and the projection job's commit is what shows up next.

To see what the projection job would write without keeping it — useful when debugging a red run — use just check, then git restore . to discard.

release.yml resyncs the generated artifacts once more as a backstop when it cuts a release, so plugin.json at a release tag is current even on the rare run where the project job didn't land first.

Releasing

Releasing is one workflow_dispatch on .github/workflows/release.yml whose only input is the bump level (patch, minor, major).

Write the notes before dispatching — reading what landed is what tells you the bump, so the two are one judgment:

git log $(git describe --tags --abbrev=0)..main --no-merges

Commit that section under ## Unreleased in CHANGELOG.md, then dispatch with the bump level the notes imply. A missing or empty ## Unreleased section fails the run.

Dispatching triggers shipyard's reusable release workflow, which:

1. derives the next version from plugin.yml,
2. retitles CHANGELOG.md's ## Unreleased section to that version,
3. resyncs the generated artifacts as a backstop (the project job already committed them when the source changed, so this ordinarily finds nothing to resync),
4. commits the bump, then tags that commit — so plugin.json at the tag reports the version the tag names,
5. publishes the GitHub Release from the section it just wrote, and
6. notifies the bridge.ai marketplace to rebuild its catalog via repository_dispatch.

main is always the latest released state, and version in plugin.yml stays the source of truth — but it's now written by the release rather than hand-edited. The chris-peterson marketplace tracks ClaudeWatch as an unpinned git source (default-branch HEAD), so step 4's commit to main is the moment consumers see the update; the tag and the marketplace notify are not what claude plugin update reads.

Known constraints (do not paper over)

• macOS-style absolute paths appear in shipped rules (~/.ssh/..., ~/.aws/credentials). These are user-home patterns, not platform-specific per se — but the documentation references unix conventions. If cross-platform support becomes a goal, that's a spec change, not a quick fix.
• YAML parser is minimal. It handles the format ClaudeWatch ships and nothing more. Multi-line strings, anchors, and !!tag constructs are not supported. If you need them, that's a spec discussion, not a copy-paste of PyYAML.
• Word normalization ([EN-15]) reaches the spellings that survive as a literal word, not obfuscation in general. "git" commit, g\it commit, git "commit" and rm "-r" /etc all resolve before matching, and the walk steps over an option to reach the subcommand behind it (git -C /repo "push"). What stays out of reach is a word assembled at runtime, because nothing in the command text says what it will be — C=git; $C commit is the shape to expect. A shell has unbounded ways to spell a word, so treat the rules as a guard against the destructive command an agent writes plainly, not as a sandbox against one trying to get past it.
• Normalization changes how a word is spelled, never where a pattern looks. Patterns search anywhere in the command, so echo rm -rf / decides the same as rm -rf / — and after normalization so does echo "rm" -rf /. That breadth is the deliberate trade in [RL-03]; resolving a spelling neither widens nor narrows it.

Reading order for new contributors

1. README.md — the elevator pitch and install path
2. SPEC.md — the contract
3. scripts/watchdog.py — the engine (under 250 lines)
4. watches/watch-git.yml — the canonical rule-set example
5. SCHEMA.md — the YAML rule format reference (for rule authors)
6. tests/test-watch-git.sh — the test pattern
7. This file — for "how to think about adding things"