I am not actively maintaining this project publicly, and just tinker with it for personal use.

Notes Assistant

I have been enjoying Claude Code for writing code, and I am exploring how to use it for writing and maintaining my notes. To allow me to quickly iterate and experiment with this, I wrote Notes Assistant.

Notes Assistant is a file watcher that triggers Claude Code when you modify Markdown files, and if the directory or parent directory contains a CLAUDE.md file. The CLAUDE.md file provides context for Claude Code to understand the actions to take within a specific folder.

Claude Code triggers are delayed to avoid running on every keystroke, allowing you to write and edit your notes without interruption. Delays are tracked based on the folder containing the CLAUDE.md file.

Config options allow you to override the Claude Code cli and CLAUDE.md filename, making it possible to run with different agents or configurations.

Features

• Monitors Markdown files for changes
• Automatically detects project context via CLAUDE.md files
• Debounces file changes with configurable delay
• Supports exclusion patterns for ignoring specific files/directories
• Runs in Docker for easy deployment

Quick Start

1. Copy and configure the example config:

   cp config.yaml.example config.yaml
   # Edit config.yaml with your settings

2. Build the Docker image:

   docker build -t notes-assistant .

3. Run the container:

   docker run -d \
     --name notes-assistant \
     -v /path/to/your/obsidian/vault:/notes \
     -v /path/to/your/config.yaml:/app/config.yaml \
     -v /path/to/claude/auth:/root/.claude \
     notes-assistant

Configuration

The config.yaml file supports the following options:

• notes_directory: Path to your Obsidian vault (required, mounted as /notes in container)
• exclude_patterns: List of glob patterns to ignore (optional, defaults to [])
• trigger_filename: Filename that marks a Claude-enabled directory (optional, defaults to CLAUDE.md)
• delay_seconds: Seconds to wait before triggering claude-code (optional, defaults to 300, must be positive)
• dry_run: Whether to run in dry-run mode without executing commands (optional, defaults to false)
• assistant_command: Custom command to run instead of default Claude command (optional, defaults to ["claude", "--model", "claude-sonnet-4-20250514", "--print", "--allowedTools", "Edit,Write,Read,MultiEdit,WebSearch,WebFetch,Bash(mv:*)"])

Development

To run locally with uv:

# Install dependencies
uv pip install -e .

# Run with default config location
python -m nass

# Run with custom config file
python -m nass --config /path/to/your/config.yaml

Claude Authentication

If you're running Notes Assistant in a container, you need to authenticate Claude inside the container. After building and starting the container for the first time:

# Run claude inside the running container (it will start the authentication wizard)
docker exec -it notes-assistant claude

# Or if container isn't running yet, run it interactively first:
docker run -it --rm \
  -v /path/to/your/obsidian/vault:/notes \
  -v /path/to/your/config.yaml:/app/config.yaml \
  notes-assistant bash

# Then inside the container:
claude

The authentication will persist when you mount the Claude configuration directory as shown in the deployment examples below.