External Editors & AI Agents

Scratch stores notes as plain Markdown files, making them accessible to any text editor or AI agent. The built-in file watcher automatically detects external changes and reloads notes in real-time.

Why Use External Editors?

AI coding agents - Claude Code, Cursor, Windsurf can read and edit your notes
Advanced text editing - Vim, Emacs, VS Code with custom extensions
Automation scripts - Process notes with Python, Node.js, shell scripts
Bulk operations - Rename, search/replace, or format multiple files at once

Scratch’s file watcher runs continuously when a notes folder is set. External changes appear in Scratch within 500ms (debounced per file).

File Watcher Implementation

Scratch uses the Rust notify crate to watch your notes folder for changes:

How It Works

Recursive watching - Monitors the entire notes folder (up to 10 levels deep)
Event debouncing - Groups rapid changes (500ms window per file)
Change detection - Detects create, modify, and delete events
Frontend notification - Emits file-change events to the UI
Auto-reload - Reloads the current note if changed externally

What’s Watched

All .md files except those in excluded folders:

.git (Git metadata)
.scratch (App settings)
.obsidian (Obsidian vault)
.trash (Deleted notes)
assets (Images and attachments)

Create a .scratch/ folder in your notes directory to store app-specific data that won’t appear in Scratch’s note list.

Using External Text Editors

Quick Edit Workflow

Open in Editor

Right-click a note in Scratch’s sidebar and select Reveal in File Manager. Then open the .md file in your preferred editor.

Make Changes

Edit the note in your external editor and save (Cmd+S).

Auto-Reload in Scratch

Scratch detects the file change and shows a notification: “External changes detected.” Click Reload or press Cmd+R.

Recommended Editors

Editor	Best For	Setup
VS Code	Markdown extensions, AI plugins	Install Markdown Preview Enhanced
Vim/Neovim	Keyboard-driven editing	Use markdown plugins like `vim-markdown`
Sublime Text	Fast, lightweight editing	Install Markdown Extended package
Obsidian	Graph view, community plugins	Open same folder as Scratch
iA Writer	Distraction-free writing	Set notes folder as library

Avoid concurrent edits: Don’t edit the same note in Scratch and an external editor simultaneously. The last save wins, potentially losing changes.

AI Agent Integration

Scratch works seamlessly with AI coding agents that can read and write files:

Claude Code (Anthropic)

Claude can read your notes, answer questions, and make edits:

# Ask Claude about your notes
claude "What are the main themes in my notes?"

# Edit a specific note
claude "Add a 'Next Steps' section to my Project Ideas note"

# Create a new note from a template
claude "Create a meeting notes file for today's standup"

Setup:

Install Claude Code CLI from claude.ai
Run claude in your notes folder
Scratch auto-reloads when Claude saves changes

Cursor / Windsurf

AI-first code editors can edit notes like source code:

Open Notes Folder

In Cursor, select File → Open Folder and choose your notes directory.

Use AI Chat

Ask Cursor to edit notes:

"Add tags to all notes in the Archive folder"
"Reformat all meeting notes to use a consistent template"

Watch Changes in Scratch

Scratch detects file changes and reloads affected notes automatically.

GitHub Copilot Workspace

Use Copilot to generate note content:

Open your notes folder in VS Code
Create a new .md file
Write a prompt as a comment: 
Copilot generates the summary
Save the file - Scratch adds it to the note list

Use AI agents for bulk operations (tagging, formatting, link extraction) and Scratch for daily writing (fast, focused, WYSIWYG).

Automation Scripts

Example: Daily Note Generator

Create daily notes automatically with a shell script:

#!/bin/bash
# daily-note.sh - Create a daily note with template

NOTES_DIR="$HOME/Documents/Notes"
DATE=$(date +"%Y-%m-%d")
FILE="$NOTES_DIR/Daily/$DATE.md"

mkdir -p "$NOTES_DIR/Daily"

cat > "$FILE" <<EOF
# Daily Note - $DATE

## Tasks
- [ ] Review yesterday's notes
- [ ] Plan today's priorities

## Notes

## Reflections

EOF

echo "Created daily note: $FILE"

Run daily:

chmod +x daily-note.sh
./daily-note.sh

Scratch detects the new file and adds it to the note list instantly.

Example: Markdown Linter

Fix markdown formatting across all notes:

# Install markdownlint-cli
npm install -g markdownlint-cli

# Lint and fix all notes
cd ~/Documents/Notes
markdownlint --fix '**/*.md'

Scratch reloads all modified notes automatically.

Example: Note Tagger (Python)

Add tags to notes based on content:

import os
import re
from pathlib import Path

NOTES_DIR = Path.home() / "Documents" / "Notes"

for note_file in NOTES_DIR.rglob("*.md"):
    content = note_file.read_text()
    
    # Skip if already has tags
    if "tags:" in content:
        continue
    
    # Extract keywords
    tags = []
    if "meeting" in content.lower():
        tags.append("meeting")
    if "project" in content.lower():
        tags.append("project")
    
    # Add tags as YAML frontmatter
    if tags:
        frontmatter = f"---\ntags: {', '.join(tags)}\n---\n\n"
        note_file.write_text(frontmatter + content)
        print(f"Tagged: {note_file.name}")

Run with:

python tag-notes.py

Scratch’s file watcher handles frontmatter changes gracefully. The editor shows the rendered note (frontmatter hidden), while source mode shows the raw YAML.

File Watcher Behavior

Reload Logic

When an external change is detected:

Debounce check - Waits 500ms for additional changes to the same file
Self-save detection - Ignores changes from Scratch’s own saves
Notification - Shows “External changes detected” toast
Auto-reload - If the changed note is currently open, shows reload prompt

Manual Reload

If auto-reload doesn’t trigger:

Single note: Press Cmd+R or click the Reload button (↻)
All notes: Close and reopen Scratch
Search index: Search automatically rebuilds on file changes

If you’re making many external changes at once (e.g., mass rename), close Scratch first to avoid excessive reloads. Reopen when done.

External Change Detection

Current Note Detection

Scratch shows a banner when the open note changes externally:

⚠️ This note was modified externally. [Reload] [Dismiss]

Reload - Fetches the latest content from disk (discards unsaved changes)
Dismiss - Keeps the current editor content (your version)

The note list refreshes automatically when:

A new .md file is created
A note is deleted externally
A note’s title (first # Heading) changes

Unsaved changes are lost if you reload while editing. Scratch auto-saves every 500ms, but rapid external changes can still cause conflicts.

Conflict Resolution

If you edit the same note in Scratch and externally:

Scenario 1: External Edit While Not Editing

✅ Safe - Scratch reloads the note seamlessly

Scenario 2: External Edit While Editing

⚠️ Conflict - Scratch shows the reload banner. Choose:

Reload - Accept external changes (lose your unsaved edits)
Dismiss - Keep your version (save to overwrite external changes)

Scenario 3: Simultaneous Edits

❌ Last save wins - No merge conflict UI. Use Git for version control if this is common.

Best practice: Use Scratch for interactive editing and external tools for batch operations. Avoid editing the same note simultaneously.

Combining Scratch with Obsidian

Many users run Scratch and Obsidian on the same notes folder:

Setup

Create Shared Folder

Create a folder for your notes (e.g., ~/Documents/Notes).

Open in Scratch

In Scratch, set this folder as your notes folder.

Open in Obsidian

In Obsidian, select Open folder as vault and choose the same folder.

What Works

✅ Basic Markdown - Both editors support standard Markdown
✅ Wikilinks - [[Note Title]] works in both
✅ Images - Both use ![](assets/image.png) syntax
✅ Frontmatter - YAML metadata is preserved

What Doesn’t Work

❌ Obsidian plugins - Dataview, Templater, etc. are Obsidian-specific
❌ Canvas files - Scratch doesn’t support .canvas format
❌ Embedded queries - Obsidian’s query blocks won’t render in Scratch

Scratch focuses on fast, distraction-free writing. Use Obsidian for graph view, advanced queries, and community plugins.

Performance Considerations

Large Note Collections

The file watcher is optimized for thousands of notes:

Efficient recursion - Only watches note folders (excludes .git, etc.)
Debouncing - Prevents event spam from rapid saves
Incremental index updates - Search index updates per-file, not full rebuild

High-Frequency Edits

If an external tool edits files rapidly (e.g., live sync):

Debounce prevents thrashing - Multiple edits within 500ms are batched
Reload only if viewing - Sidebar updates don’t disrupt the editor

Disabling File Watching

File watching cannot be disabled (by design). If you need to pause it:

Close Scratch
Make bulk changes
Reopen Scratch - notes and search index refresh on startup

Troubleshooting

”File watcher failed to start”

Cause: OS file descriptor limit exceeded (macOS/Linux). Fix: Increase the limit:

# macOS
ulimit -n 10240

# Linux (persistent)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Notes not auto-reloading

Check file watcher status - Restart Scratch
Verify file changes - Save the file in your external editor
Manual reload - Press Cmd+R

High CPU usage

Cause: Too many file change events (e.g., live sync). Fix: Exclude the sync folder from Scratch’s notes folder or disable live sync temporarily.

Best Practices

Close before bulk operations - Avoid overwhelming the file watcher
Use Git for versioning - External edits don’t create undo history in Scratch
Test on a subset first - When running automation scripts, test on a few notes
Keep backups - External tools can corrupt files; Git or Time Machine saves the day
Communicate intent - If using AI agents, review changes before closing Scratch

Create a “Scratch + AI” workflow: Use Scratch for daily writing, Claude for summarization/tagging, and Git for version control.

Get Started

Core Features

Advanced

Guides

​Why Use External Editors?

​File Watcher Implementation

​How It Works

​What’s Watched

​Using External Text Editors

​Quick Edit Workflow

​Recommended Editors

​AI Agent Integration

​Claude Code (Anthropic)

​Cursor / Windsurf

​GitHub Copilot Workspace

​Automation Scripts

​Example: Daily Note Generator

​Example: Markdown Linter

​Example: Note Tagger (Python)

​File Watcher Behavior

​Reload Logic

​Manual Reload

​External Change Detection

​Current Note Detection

​Sidebar Refresh

​Conflict Resolution

​Scenario 1: External Edit While Not Editing

​Scenario 2: External Edit While Editing

​Scenario 3: Simultaneous Edits

​Combining Scratch with Obsidian

​Setup

​What Works

​What Doesn’t Work

​Performance Considerations

​Large Note Collections

​High-Frequency Edits

​Disabling File Watching

​Troubleshooting

​”File watcher failed to start”

​Notes not auto-reloading

​High CPU usage

​Best Practices

Build docs developers (and LLMs) love

Why Use External Editors?

File Watcher Implementation

How It Works

What’s Watched

Using External Text Editors

Quick Edit Workflow

Recommended Editors

AI Agent Integration

Claude Code (Anthropic)

Cursor / Windsurf

GitHub Copilot Workspace

Automation Scripts

Example: Daily Note Generator

Example: Markdown Linter

Example: Note Tagger (Python)

File Watcher Behavior

Reload Logic

Manual Reload

External Change Detection

Current Note Detection

Sidebar Refresh

Conflict Resolution

Scenario 1: External Edit While Not Editing

Scenario 2: External Edit While Editing

Scenario 3: Simultaneous Edits

Combining Scratch with Obsidian

Setup

What Works

What Doesn’t Work

Performance Considerations

Large Note Collections

High-Frequency Edits

Disabling File Watching

Troubleshooting

”File watcher failed to start”

Notes not auto-reloading

High CPU usage

Best Practices