BlockWatch

BlockWatch

BlockWatch is a linter that keeps your code, documentation, and configuration in sync and enforces strict formatting and validation rules.

It helps you avoid broken docs and messy config files by enforcing rules directly in your comments. You can link code to documentation, enforce sorted lists, ensure uniqueness, and even validate content with Regex, AI, or custom Lua scripts.

It works with almost any language (Rust, Python, JS, Go, Markdown, YAML, etc.) and can run on your entire repo or just your VCS diffs.

Annotate your project with an AI agent (recommended)

Adding the first <block> tags by hand is the tedious part of picking up BlockWatch. AI coding agents are good at this. An agent can read through the repo, pick reasonable spots, add the tags in the correct comment syntax for each language, and run blockwatch to check its own work.

There's a skill in this repo for it: .agents/skills/blockwatch/SKILL.md. It tells the agent where blocks are worth adding, documents the tag syntax, and explains how to verify the result.

1. Install the binary so the agent can run it:

cargo install blockwatch   # or: brew install mennanov/blockwatch/blockwatch

2. Give the skill to your agent.

Claude Code users: install the plugin once and the skill is available in every project — no per-project setup:

/plugin marketplace add mennanov/blockwatch
/plugin install blockwatch@blockwatch

For other agents (or if you prefer a project-local copy), place SKILL.md where your tool looks for instructions:

Agent	Where to put the skill
Claude Code	Use the plugin above (recommended), or .claude/skills/blockwatch/SKILL.md (project) / ~/.claude/skills/... (global)
Cursor	.cursor/rules/blockwatch.mdc
GitHub Copilot	append to .github/copilot-instructions.md
Codex / others	append to AGENTS.md

You can pull the file straight from this repo:

mkdir -p .claude/skills/blockwatch
curl -sL https://raw.githubusercontent.com/mennanov/blockwatch/main/.agents/skills/blockwatch/SKILL.md \
  -o .claude/skills/blockwatch/SKILL.md

3. Ask the agent to annotate the project, for example:

Using the BlockWatch skill, annotate this repository with <block> tags. Focus on lists that should stay sorted/unique and on code that must stay in sync with docs or config. Add only high-value blocks, then run blockwatch to confirm they all pass.

Review the diff before you commit it: the agent's choices are a starting point.

4. Turn on enforcement so the rules stay in place: wire up the pre-commit hook and GitHub Action from CI Integration.

Features

• Drift Detection: Link a block of code to its documentation. If you change the code but forget the docs, BlockWatch alerts you.
• Strict Formatting: Enforce sorted lists (keep-sorted) and unique entries (keep-unique) so you don't have to nitpick in code reviews.
• Content Validation: Check lines against Regex patterns (line-pattern) or enforce block size limits ( line-count).
• AI Rules: Use natural language to validate code or text (e.g., "Must mention 'banana'").
• Lua Scripting: Write custom validation logic in Lua scripts (check-lua).
• Flexible: Run it on specific files, glob patterns, or just your unstaged changes.

Installation

Homebrew (macOS/Linux)

brew tap mennanov/blockwatch
brew install blockwatch

From Source (Rust)

cargo install blockwatch

Prebuilt Binaries

Check the Releases page for prebuilt binaries.

Quick start example