notes-watcher 0.1.0__tar.gz

notes_watcher-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,190 @@
+# 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/note_watcher/__init__.py

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

notes_watcher-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.")

notes_watcher-0.1.0/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)