notes-watcher 0.1.0__py3-none-any.whl

note_watcher/__init__.py

@@ -0,0 +1,3 @@
+"""Note Watcher - Detect @ mentions in Obsidian notes and dispatch to AI agents."""
+
+__version__ = "0.1.0"

note_watcher/cli.py

@@ -0,0 +1,116 @@
+"""Click CLI for Note Watcher.
+
+Provides two commands:
+- `watch`: Starts the file watcher daemon
+- `process`: Batch processes all pending instructions
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import click
+
+from note_watcher.config import load_config
+from note_watcher.dispatcher import AgentDispatcher
+from note_watcher.watcher import process_file_reparse, start_watcher
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure logging to stdout/stderr."""
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+@click.group()
+@click.option("--verbose", "-v", is_flag=True, help="Enable debug logging.")
+def main(verbose: bool) -> None:
+    """Note Watcher - Detect @ mentions in Obsidian notes and dispatch to AI agents."""
+    setup_logging(verbose)
+
+
+@main.command()
+@click.option(
+    "--vault",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Path to the Obsidian vault directory.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, resolve_path=True),
+    help="Path to the configuration file.",
+)
+def watch(vault: str | None, config_path: str | None) -> None:
+    """Start the file watcher daemon.
+
+    Monitors the vault directory for changes to .md files and processes
+    @ mention instructions as they appear.
+    """
+    config = load_config(config_path)
+
+    if vault:
+        config.vault = Path(vault)
+
+    if not config.vault.is_dir():
+        click.echo(f"Error: Vault directory does not exist: {config.vault}", err=True)
+        sys.exit(1)
+
+    click.echo(f"Watching vault: {config.vault}")
+    start_watcher(config)
+
+
+@main.command()
+@click.option(
+    "--all",
+    "process_all",
+    is_flag=True,
+    required=True,
+    help="Process all pending instructions.",
+)
+@click.option(
+    "--vault",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Path to the Obsidian vault directory.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, resolve_path=True),
+    help="Path to the configuration file.",
+)
+def process(process_all: bool, vault: str | None, config_path: str | None) -> None:
+    """Batch process all pending @ mention instructions.
+
+    Scans all .md files in the vault for unprocessed instructions,
+    dispatches them to configured agents, and writes results inline.
+    """
+    config = load_config(config_path)
+
+    if vault:
+        config.vault = Path(vault)
+
+    if not config.vault.is_dir():
+        click.echo(f"Error: Vault directory does not exist: {config.vault}", err=True)
+        sys.exit(1)
+
+    dispatcher = AgentDispatcher(config)
+    vault_path = config.vault
+
+    # Find all .md files
+    md_files = sorted(vault_path.rglob("*.md"))
+    total_processed = 0
+
+    for md_file in md_files:
+        count = process_file_reparse(str(md_file), dispatcher)
+        if count > 0:
+            click.echo(f"Processed {count} instruction(s) in {md_file}")
+            total_processed += count
+
+    click.echo(f"Done. Processed {total_processed} instruction(s) total.")

note_watcher/config.py

@@ -0,0 +1,110 @@
+"""Configuration loading and management for Note Watcher.
+
+Loads YAML configuration from a file, applies sensible defaults,
+and validates required fields.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "note-watcher" / "config.yml"
+
+DEFAULT_DEBOUNCE_SECONDS = 1.0
+
+DEFAULT_IGNORE_PATTERNS: list[str] = [
+    "*.excalidraw.md",
+    ".trash/**",
+]
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for a single agent."""
+
+    name: str
+    type: str
+    command: str | None = None
+    callable: str | None = None
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict[str, Any]) -> AgentConfig:
+        return cls(
+            name=name,
+            type=data.get("type", "echo"),
+            command=data.get("command"),
+            callable=data.get("callable"),
+        )
+
+
+@dataclass
+class Config:
+    """Application configuration."""
+
+    vault: Path
+    debounce_seconds: float = DEFAULT_DEBOUNCE_SECONDS
+    ignore_patterns: list[str] = field(default_factory=lambda: list(DEFAULT_IGNORE_PATTERNS))
+    agents: dict[str, AgentConfig] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Config:
+        """Create a Config from a parsed YAML dictionary."""
+        vault_str = data.get("vault", ".")
+        # Expand ~ and environment variables in the vault path
+        vault = Path(os.path.expanduser(os.path.expandvars(vault_str)))
+
+        debounce = data.get("debounce_seconds", DEFAULT_DEBOUNCE_SECONDS)
+
+        ignore = data.get("ignore_patterns", list(DEFAULT_IGNORE_PATTERNS))
+
+        agents: dict[str, AgentConfig] = {}
+        for name, agent_data in data.get("agents", {}).items():
+            if isinstance(agent_data, dict):
+                agents[name] = AgentConfig.from_dict(name, agent_data)
+            else:
+                # Simple string value treated as the type
+                agents[name] = AgentConfig(name=name, type=str(agent_data))
+
+        return cls(
+            vault=vault,
+            debounce_seconds=float(debounce),
+            ignore_patterns=ignore,
+            agents=agents,
+        )
+
+    @classmethod
+    def defaults(cls, vault: str | Path = ".") -> Config:
+        """Create a Config with default values."""
+        return cls(vault=Path(vault))
+
+
+def load_config(config_path: str | Path | None = None) -> Config:
+    """Load configuration from a YAML file.
+
+    Args:
+        config_path: Path to the config file. If None, uses the default path.
+
+    Returns:
+        A Config instance. If the config file doesn't exist, returns defaults.
+    """
+    if config_path is None:
+        path = DEFAULT_CONFIG_PATH
+    else:
+        path = Path(config_path)
+
+    if not path.exists():
+        return Config.defaults()
+
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    if data is None:
+        return Config.defaults()
+
+    return Config.from_dict(data)

note_watcher/debouncer.py

@@ -0,0 +1,78 @@
+"""Debounce logic for rapid file changes.
+
+Prevents duplicate processing when a file is modified multiple times
+in quick succession (e.g., editors that write temp files then rename).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable
+
+
+class Debouncer:
+    """Debounces file change events by path.
+
+    When a file change is triggered, the callback is delayed by the configured
+    interval. If another trigger arrives before the interval expires, the timer
+    resets. This ensures the callback fires only once after the last change
+    within a burst of rapid changes.
+    """
+
+    def __init__(
+        self,
+        interval: float,
+        callback: Callable[[str], None],
+    ) -> None:
+        """Initialize the debouncer.
+
+        Args:
+            interval: Seconds to wait after the last trigger before firing.
+            callback: Function to call with the file path when debounce fires.
+        """
+        self.interval = interval
+        self.callback = callback
+        self._timers: dict[str, threading.Timer] = {}
+        self._lock = threading.Lock()
+        self._cancelled = False
+
+    def trigger(self, file_path: str) -> None:
+        """Signal that a file has changed.
+
+        Resets the debounce timer for this file. The callback will fire
+        after ``interval`` seconds of no further triggers for this file.
+
+        Args:
+            file_path: Absolute path to the changed file.
+        """
+        with self._lock:
+            if self._cancelled:
+                return
+
+            # Cancel any existing timer for this file
+            existing = self._timers.pop(file_path, None)
+            if existing is not None:
+                existing.cancel()
+
+            # Schedule the callback after the full interval
+            timer = threading.Timer(self.interval, self._fire, args=(file_path,))
+            timer.daemon = True
+            self._timers[file_path] = timer
+            timer.start()
+
+    def _fire(self, file_path: str) -> None:
+        """Execute the callback if not cancelled."""
+        with self._lock:
+            if self._cancelled:
+                return
+            self._timers.pop(file_path, None)
+
+        self.callback(file_path)
+
+    def cancel_all(self) -> None:
+        """Cancel all pending timers. No further callbacks will fire."""
+        with self._lock:
+            self._cancelled = True
+            for timer in self._timers.values():
+                timer.cancel()
+            self._timers.clear()

note_watcher/dispatcher.py

@@ -0,0 +1,92 @@
+"""Agent dispatcher that routes instructions to configured agent handlers.
+
+Supports built-in agent types (echo, uppercase) and extensible configuration
+for command-based or callable-based agents.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from note_watcher.config import AgentConfig, Config
+    from note_watcher.parser import Instruction
+
+
+class UnknownAgentError(Exception):
+    """Raised when an instruction references an agent that isn't configured."""
+
+    def __init__(self, agent_name: str) -> None:
+        self.agent_name = agent_name
+        super().__init__(f"Unknown agent: {agent_name!r}")
+
+
+class AgentDispatcher:
+    """Routes instructions to the appropriate agent handler."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    def dispatch(self, instruction: Instruction) -> str:
+        """Dispatch an instruction to the appropriate agent and return the result.
+
+        Args:
+            instruction: The parsed instruction to process.
+
+        Returns:
+            The agent's result as a string.
+
+        Raises:
+            UnknownAgentError: If the agent isn't configured.
+        """
+        agent_config = self.config.agents.get(instruction.agent_name)
+        if agent_config is None:
+            raise UnknownAgentError(instruction.agent_name)
+
+        return self._handle(agent_config, instruction)
+
+    def _handle(self, agent_config: AgentConfig, instruction: Instruction) -> str:
+        """Route to the correct handler based on agent type."""
+        handler_type = agent_config.type
+
+        if handler_type == "echo":
+            return self._handle_echo(instruction)
+        elif handler_type == "uppercase":
+            return self._handle_uppercase(instruction)
+        elif handler_type == "command":
+            return self._handle_command(agent_config, instruction)
+        else:
+            raise UnknownAgentError(
+                f"{instruction.agent_name} (unsupported type: {handler_type})"
+            )
+
+    def _handle_echo(self, instruction: Instruction) -> str:
+        """Echo agent: returns the instruction text unchanged."""
+        return instruction.instruction_text
+
+    def _handle_uppercase(self, instruction: Instruction) -> str:
+        """Uppercase agent: returns the instruction text in uppercase."""
+        return instruction.instruction_text.upper()
+
+    def _handle_command(
+        self, agent_config: AgentConfig, instruction: Instruction
+    ) -> str:
+        """Command agent: runs a shell command with the instruction as input.
+
+        The instruction text is passed via stdin.
+        """
+        if not agent_config.command:
+            raise ValueError(f"Agent {agent_config.name!r} has type 'command' but no command configured")
+
+        result = subprocess.run(
+            agent_config.command,
+            input=instruction.instruction_text,
+            capture_output=True,
+            text=True,
+            shell=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return f"Error: {result.stderr.strip()}"
+        return result.stdout.strip()

note_watcher/parser.py

@@ -0,0 +1,78 @@
+"""Parser for extracting @ mention instructions from markdown content.
+
+Extracts instructions like `@agent_name instruction text` from markdown files,
+while skipping content that has already been processed (wrapped in completed markers).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+# Pattern to match @ mention instructions: @agent_name followed by instruction text
+INSTRUCTION_PATTERN = re.compile(r"^@(\w+)\s+(.+)$")
+
+# Markers for completed instructions
+# New format: <!-- @done agent_name: instruction text  (no closing -->)
+# Old format: <!-- @done agent_name -->  (kept for backwards compatibility)
+DONE_START_PATTERN = re.compile(r"^<!--\s*@done\s+(\w+).*$")
+DONE_END_PATTERN = re.compile(r"^.*/@done\s*-->$")
+
+
+@dataclass
+class Instruction:
+    """A parsed @ mention instruction."""
+
+    agent_name: str
+    instruction_text: str
+    line_number: int
+    original_text: str
+
+
+def parse_instructions(content: str) -> list[Instruction]:
+    """Extract @ mention instructions from markdown content.
+
+    Skips any content between `<!-- @done ... -->` and `<!-- /@done -->`
+    markers, which indicate already-processed instructions.
+
+    Args:
+        content: The full markdown file content.
+
+    Returns:
+        A list of Instruction objects for each unprocessed @ mention found.
+    """
+    instructions: list[Instruction] = []
+    lines = content.split("\n")
+    in_done_block = False
+
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+
+        # Check for start of a completed block
+        if DONE_START_PATTERN.match(stripped):
+            in_done_block = True
+            continue
+
+        # Check for end of a completed block
+        if DONE_END_PATTERN.match(stripped):
+            in_done_block = False
+            continue
+
+        # Skip lines inside completed blocks
+        if in_done_block:
+            continue
+
+        # Try to match an instruction
+        match = INSTRUCTION_PATTERN.match(stripped)
+        if match:
+            instructions.append(
+                Instruction(
+                    agent_name=match.group(1),
+                    instruction_text=match.group(2),
+                    line_number=i + 1,  # 1-indexed
+                    original_text=line,
+                )
+            )
+
+    return instructions

note_watcher/watcher.py

@@ -0,0 +1,220 @@
+"""File watcher that monitors an Obsidian vault for changes to .md files.
+
+Uses watchdog to detect file modifications, applies debouncing, and triggers
+the parse → dispatch → write pipeline for each changed file.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import signal
+import sys
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from watchdog.events import FileSystemEventHandler, FileModifiedEvent
+from watchdog.observers import Observer
+
+from note_watcher.debouncer import Debouncer
+from note_watcher.dispatcher import AgentDispatcher, UnknownAgentError
+from note_watcher.parser import parse_instructions
+from note_watcher.writer import write_result
+
+if TYPE_CHECKING:
+    from note_watcher.config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class NoteEventHandler(FileSystemEventHandler):
+    """Handles file system events for .md files in the vault."""
+
+    def __init__(self, debouncer: Debouncer, ignore_patterns: list[str]) -> None:
+        super().__init__()
+        self.debouncer = debouncer
+        self.ignore_patterns = ignore_patterns
+
+    def on_modified(self, event: FileModifiedEvent) -> None:  # type: ignore[override]
+        if event.is_directory:
+            return
+
+        src_path = str(event.src_path)
+
+        # Only process .md files
+        if not src_path.endswith(".md"):
+            return
+
+        # Check ignore patterns
+        if self._should_ignore(src_path):
+            logger.debug("Ignoring %s (matches ignore pattern)", src_path)
+            return
+
+        logger.info("Detected change: %s", src_path)
+        self.debouncer.trigger(src_path)
+
+    def _should_ignore(self, file_path: str) -> bool:
+        """Check if a file matches any of the ignore patterns."""
+        path = Path(file_path)
+        for pattern in self.ignore_patterns:
+            # Check against the filename and the full path
+            if fnmatch.fnmatch(path.name, pattern):
+                return True
+            if fnmatch.fnmatch(str(path), pattern):
+                return True
+        return False
+
+
+def process_file(file_path: str, dispatcher: AgentDispatcher) -> int:
+    """Parse a file, dispatch instructions, and write results.
+
+    Args:
+        file_path: Path to the markdown file to process.
+        dispatcher: The agent dispatcher to use.
+
+    Returns:
+        Number of instructions processed.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        logger.warning("File no longer exists: %s", file_path)
+        return 0
+
+    content = path.read_text()
+    instructions = parse_instructions(content)
+
+    if not instructions:
+        logger.debug("No pending instructions in %s", file_path)
+        return 0
+
+    processed = 0
+    for instruction in instructions:
+        try:
+            logger.info(
+                "Dispatching @%s: %s",
+                instruction.agent_name,
+                instruction.instruction_text[:50],
+            )
+            result = dispatcher.dispatch(instruction)
+            write_result(file_path, instruction, result)
+            processed += 1
+            logger.info("Wrote result for @%s", instruction.agent_name)
+
+            # Re-read content after each write since line numbers shift
+            # For subsequent instructions, we need to re-parse
+            if processed < len(instructions):
+                content = path.read_text()
+                remaining = parse_instructions(content)
+                if not remaining:
+                    break
+                # Process just the next instruction from the fresh parse
+                # The for loop will naturally move to the next one but we need
+                # to handle the shifted line numbers
+        except UnknownAgentError as e:
+            logger.warning("Skipping unknown agent: %s", e)
+        except Exception as e:
+            logger.error("Error processing instruction: %s", e)
+
+    return processed
+
+
+def process_file_reparse(file_path: str, dispatcher: AgentDispatcher) -> int:
+    """Parse a file, dispatch instructions one at a time, re-parsing after each.
+
+    This handles the line-number shift problem by re-parsing after each write.
+
+    Args:
+        file_path: Path to the markdown file to process.
+        dispatcher: The agent dispatcher to use.
+
+    Returns:
+        Number of instructions processed.
+    """
+    path = Path(file_path)
+    processed = 0
+
+    while True:
+        if not path.exists():
+            logger.warning("File no longer exists: %s", file_path)
+            break
+
+        content = path.read_text()
+        instructions = parse_instructions(content)
+
+        if not instructions:
+            break
+
+        instruction = instructions[0]
+        try:
+            logger.info(
+                "Dispatching @%s: %s",
+                instruction.agent_name,
+                instruction.instruction_text[:50],
+            )
+            result = dispatcher.dispatch(instruction)
+            write_result(file_path, instruction, result)
+            processed += 1
+            logger.info("Wrote result for @%s", instruction.agent_name)
+        except UnknownAgentError as e:
+            logger.warning("Skipping unknown agent: %s", e)
+            break
+        except Exception as e:
+            logger.error("Error processing instruction: %s", e)
+            break
+
+    return processed
+
+
+def start_watcher(config: Config) -> None:
+    """Start the file watcher daemon.
+
+    Watches the configured vault directory for .md file changes,
+    processes them through the parse → dispatch → write pipeline.
+
+    Handles SIGTERM and SIGINT for graceful shutdown.
+
+    Args:
+        config: Application configuration.
+    """
+    dispatcher = AgentDispatcher(config)
+
+    def on_file_changed(file_path: str) -> None:
+        process_file_reparse(file_path, dispatcher)
+
+    debouncer = Debouncer(
+        interval=config.debounce_seconds,
+        callback=on_file_changed,
+    )
+
+    handler = NoteEventHandler(
+        debouncer=debouncer,
+        ignore_patterns=config.ignore_patterns,
+    )
+
+    observer = Observer()
+    observer.schedule(handler, str(config.vault), recursive=True)
+
+    # Signal handling for graceful shutdown
+    shutdown_event = False
+
+    def handle_signal(signum: int, frame: object) -> None:
+        nonlocal shutdown_event
+        logger.info("Received signal %d, shutting down...", signum)
+        shutdown_event = True
+
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+
+    logger.info("Starting watcher on vault: %s", config.vault)
+    observer.start()
+
+    try:
+        while not shutdown_event:
+            time.sleep(0.5)
+    finally:
+        logger.info("Stopping watcher...")
+        debouncer.cancel_all()
+        observer.stop()
+        observer.join(timeout=5)
+        logger.info("Watcher stopped.")

note_watcher/writer.py

@@ -0,0 +1,76 @@
+"""Inline writer that replaces instructions with agent results.
+
+Wraps results in completed markers to prevent reprocessing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from note_watcher.parser import Instruction
+
+
+def format_result(agent_name: str, instruction_text: str, result: str) -> str:
+    """Format an agent result with completed markers.
+
+    The entire result is enclosed in a single HTML comment so it is hidden
+    from rendered markdown.  The original instruction text is preserved on
+    the opening line after the agent name.
+
+    Args:
+        agent_name: Name of the agent that produced the result.
+        instruction_text: The original instruction text from the @ mention.
+        result: The agent's output text.
+
+    Returns:
+        The result wrapped in a single HTML comment block.
+    """
+    return f"<!-- @done {agent_name}: {instruction_text}\n{result}\n/@done -->"
+
+
+def write_result(
+    file_path: str | Path,
+    instruction: Instruction,
+    result: str,
+) -> None:
+    """Write an agent result back into a file, replacing the original instruction.
+
+    Reads the file, finds the instruction line, replaces it with the formatted
+    result block, and writes the file back.
+
+    Args:
+        file_path: Path to the markdown file.
+        instruction: The original instruction that was processed.
+        result: The agent's output text.
+    """
+    path = Path(file_path)
+    content = path.read_text()
+    lines = content.split("\n")
+
+    # Find the instruction line (0-indexed)
+    line_idx = instruction.line_number - 1
+
+    if line_idx < 0 or line_idx >= len(lines):
+        raise IndexError(
+            f"Instruction line {instruction.line_number} out of range "
+            f"(file has {len(lines)} lines)"
+        )
+
+    # Verify the line still matches the original instruction
+    if lines[line_idx].strip() != instruction.original_text.strip():
+        raise ValueError(
+            f"Line {instruction.line_number} has changed since parsing. "
+            f"Expected: {instruction.original_text.strip()!r}, "
+            f"Got: {lines[line_idx].strip()!r}"
+        )
+
+    # Replace the instruction line with the formatted result
+    formatted = format_result(
+        instruction.agent_name, instruction.instruction_text, result
+    )
+    lines[line_idx] = formatted
+
+    # Write back
+    path.write_text("\n".join(lines))

notes_watcher-0.1.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: notes-watcher
+Version: 0.1.0
+Summary: A daemon that detects @ mentions in Obsidian notes, dispatches instructions to AI agents, and writes results back inline.
+Author: Britt Crawford
+License-Expression: MIT
+Project-URL: Repository, https://github.com/britt/obsidian-notes-watcher
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: watchdog>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Note Watcher
+
+A tool that detects `@` mentions in Obsidian markdown notes stored in Git and dispatches instructions to configured agents — like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — that can read, modify, and reorganize your notes directly.
+
+Write `@agent_name do something` in any note, and Note Watcher dispatches the instruction to the named agent. The agent can edit files, create new notes, restructure content, or make any other changes to your vault. The original instruction is then replaced with a completion marker (an HTML comment, invisible in rendered markdown) so it is never reprocessed:
+
+```markdown
+<!-- @done agent_name: do something
+Agent response summary goes here.
+/@done -->
+```
+
+The real work happens in the commit: the agent's changes to your vault are committed back to Git. The completion comment is just a record that the instruction was processed.
+
+## Modes of Operation
+
+| Mode | Use case |
+|------|----------|
+| **Daemon** | Real-time file watching on macOS via a LaunchAgent |
+| **GitHub Action** | One-shot batch processing on every push that changes `.md` files |
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install notes-watcher
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+Copy the example config and edit it:
+
+```bash
+mkdir -p ~/.config/note-watcher
+cp config.example.yml ~/.config/note-watcher/config.yml
+```
+
+The default config location is `~/.config/note-watcher/config.yml`. You can override it with `--config`:
+
+```bash
+note-watcher watch --config /path/to/config.yml
+```
+
+### Config reference
+
+```yaml
+# Path to your Obsidian vault
+vault: ~/Obsidian/MyVault
+
+# Seconds to wait before processing after a file change
+debounce_seconds: 1.0
+
+# File patterns to ignore (glob syntax)
+ignore_patterns:
+  - "*.excalidraw.md"
+  - ".trash/**"
+
+# Agent definitions
+agents:
+  summarizer:
+    type: echo        # Returns instruction text unchanged
+  uppercase:
+    type: uppercase   # Returns instruction text in uppercase
+  word_count:
+    type: command
+    command: "wc -w"  # Runs a shell command, passes instruction via stdin
+```
+
+### Agent types
+
+| Type | Behavior |
+|------|----------|
+| `echo` | Returns the instruction text unchanged |
+| `uppercase` | Returns the instruction text in uppercase |
+| `command` | Runs a shell command with instruction text on stdin, returns stdout |
+
+### Example: Using Claude Code as an agent
+
+Configure a `command` agent that dispatches instructions to [Claude Code](https://docs.anthropic.com/en/docs/claude-code):
+
+```yaml
+agents:
+  claude:
+    type: command
+    command: "claude -p"   # Dispatches instruction to Claude Code CLI
+```
+
+Claude Code runs with full access to your vault, so it can edit notes, create new files, and reorganize content — not just respond in a comment. Write `@claude` instructions in your notes:
+
+```markdown
+@claude Summarize the key points of this meeting and add action items to my Tasks note
+```
+
+## Daemon Mode
+
+Daemon mode continuously watches your Obsidian vault for changes and processes `@` mentions in real time.
+
+### Running manually
+
+```bash
+# Watch the vault specified in your config
+note-watcher watch
+
+# Override the vault path
+note-watcher watch --vault ~/Obsidian/MyVault
+
+# Enable verbose logging
+note-watcher -v watch --vault ~/Obsidian/MyVault
+```
+
+Stop the daemon with `Ctrl+C` (`SIGINT`) or `SIGTERM`.
+
+### Installing as a macOS LaunchAgent
+
+The included install script sets up Note Watcher as a LaunchAgent that starts on login and restarts on crash:
+
+```bash
+./scripts/install.sh
+```
+
+The script is idempotent and safe to run multiple times. It will:
+
+1. Detect the `note-watcher` executable on your system
+2. Generate a LaunchAgent plist from the included template
+3. Install it to `~/Library/LaunchAgents/`
+4. Start the daemon
+
+Logs are written to `~/Library/Logs/note-watcher/`.
+
+### Uninstalling the LaunchAgent
+
+```bash
+./scripts/uninstall.sh
+```
+
+To also remove the log directory:
+
+```bash
+./scripts/uninstall.sh --clean
+```
+
+## GitHub Action Mode
+
+GitHub Action mode processes all pending `@` instructions across the entire vault in a single batch run. This is useful for vaults stored in a Git repository.
+
+### CLI usage
+
+```bash
+note-watcher process --all --vault /path/to/vault
+```
+
+### Setting up the GitHub Actions workflow
+
+See [`examples/github-action/`](examples/github-action/) for a complete, ready-to-copy example that uses [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as the AI agent.
+
+To set it up:
+
+1. Copy `examples/github-action/.github/` into your notes repository
+2. Add a `config.yml` to your notes repo (see `examples/github-action/config.example.yml`)
+3. Add your `ANTHROPIC_API_KEY` as a repository secret
+4. Under **Settings > Actions > General**, set "Workflow permissions" to "Read and write permissions"
+
+The workflow triggers on any push that modifies `.md` files, processes all unprocessed `@` instructions, and commits the agent's changes back to your repository. It uses `[skip ci]` to prevent infinite loops.
+
+See the [Claude Code GitHub Actions documentation](https://docs.anthropic.com/en/docs/claude-code/github-actions) for more on setting up Claude Code in CI.
+
+## Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=note_watcher
+```
+
+## License
+
+[MIT](LICENSE)

notes_watcher-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+note_watcher/__init__.py,sha256=TSyqWVGaUFPNonbeSbWcya9PXn4uflBcTFrlKVteiYA,107
+note_watcher/cli.py,sha256=oY3_D5-rRiSw8wQMfHGxZu0wWLdmyz4DAoAwu85pmrI,3286
+note_watcher/config.py,sha256=IkZ8sHHBumrGUPEzdWSRocMc7mQPN8A2bdSqAH7X-xA,3025
+note_watcher/debouncer.py,sha256=66DQgNa-iJhAnh16VvV5LAGz1gTnBvQZtEitimUStl4,2506
+note_watcher/dispatcher.py,sha256=tbiHvpcE9xJDH19eUME-2w9g86N4m7heBJfaOswyimo,3164
+note_watcher/parser.py,sha256=NsQ6xdj0tY6YpN9Y5MO7S7hTkks2S8IA_su9o0uS-Dw,2316
+note_watcher/watcher.py,sha256=9pTicBvlXQBcFG1Nr-JDdoRElPnpr5klXZQtiOU7VT4,6849
+note_watcher/writer.py,sha256=30sVi6npOie3oKrpNhfMDrlakLTPwmzQHlaqqTxftRg,2446
+notes_watcher-0.1.0.dist-info/licenses/LICENSE,sha256=TGsvQjvTOtnI1398o78vrXa7AshhcGTmQ8jwHYQI4Cs,1071
+notes_watcher-0.1.0.dist-info/METADATA,sha256=24d_J9VW4mTtY5QVKC_I-GLMUsfSoqp0ZD-Q4BiHbxI,6259
+notes_watcher-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+notes_watcher-0.1.0.dist-info/entry_points.txt,sha256=wJKq1pcsnCq6-_KDWU2qI9kv0YU0-wIeawH_tO0Gmg4,55
+notes_watcher-0.1.0.dist-info/top_level.txt,sha256=ZK3wUA1ETERmvHpiKHYg-UMDm-ykKELQ4am5irYhkqU,13
+notes_watcher-0.1.0.dist-info/RECORD,,

notes_watcher-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

notes_watcher-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+note-watcher = note_watcher.cli:main

notes_watcher-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Britt Crawford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notes_watcher-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+note_watcher