Skip to main content
SHARC’s file watching system keeps your index up-to-date as you modify code. This enables real-time semantic search without manual re-indexing.

​
How It Works

​
Automatic Activation

File watching starts automatically after index_codebase completes: 
> Index this codebase

● index_codebase (MCP)
  ⎿ Indexed 3,450 chunks in 22.4s
  ⎿ File watcher started ← Automatic!
You don’t need to call start_watch separately.

​
Event Processing

​
Debouncing

SHARC waits 2 seconds after the last file change before processing. This:
  • Batches rapid changes (e.g., IDE auto-save)
  • Reduces redundant API calls
  • Prevents indexing incomplete saves

​
Deduplication

If the same file changes multiple times within the debounce window, only the final state is indexed.

​
Hash Checking

Before re-indexing a file, SHARC compares SHA-256 hashes:
  • Same hash: Skip (no actual change)
  • Different hash: Re-index the file
This prevents unnecessary work when files are touched but not modified.

​
Syntax Guard

SHARC validates syntax before indexing to prevent corrupted vectors:

​
Supported Languages

Full AST validation for:
  • TypeScript / JavaScript
  • Python
  • Go
  • Rust
  • Java
  • C / C++
  • C#
  • Scala

​
How It Works

  1. Parse file syntax
  2. Check for syntax errors
  3. If errors found:
    • Keep old vectors (don’t corrupt the index)
    • Skip indexing until syntax is fixed
  4. If valid:
    • Remove old vectors
    • Index new content

​
Example Scenario

1. User saves auth.ts with incomplete code:
   export async function authenticate(
   // Missing closing brace

2. Syntax guard detects error

3. Old vectors preserved:
   "The authenticate function validates JWT tokens..."

4. User completes the code:
   export async function authenticate(token: string) {
     return jwt.verify(token);
   }

5. File re-indexed with new content

​
File Filters

​
Soft ignore rules

SHARC merges ignore rules from four sources, in this precedence order:
  1. Default ignore patterns
  2. Root .gitignore patterns
  3. Root .sharcignore patterns
  4. ignorePatterns passed to index_codebase
Default ignore patterns include: 
node_modules/**, target/**, dist/**, build/**, out/**, .next/**, .nuxt/**, .svelte-kit/**,
.turbo/**, .parcel-cache/**, .cache/**, coverage/**, .nyc_output/**, __pycache__/**,
.pytest_cache/**, .mypy_cache/**, .ruff_cache/**, .tox/**, .nox/**, .venv/**, venv/**, env/**,
.git/**, .svn/**, .hg/**, .idea/**, .vscode/**, tmp/**, temp/**, logs/**, *.log, *.min.js,
*.min.css, *.bundle.js, *.chunk.js, *.map

​
Hard safety blocks

Some paths and files are always blocked even if they are not in ignore patterns. Blocked system paths:
  • Windows: C:\Windows, C:\Program Files, C:\Program Files (x86), C:\ProgramData, $Recycle.Bin, System Volume Information
  • POSIX: /proc, /sys, /dev, /run, /boot, /lib, /lib64, /system, /Library, /private/var/vm
Blocked sensitive/binary content:
  • Secret/env files: .env, .env.* (except .env.example)
  • Key/cert files: .pem, .key, .p12, .pfx
  • Binaries/media/archives/docs: executable, object, image, audio/video, archive, and office/PDF file types
  • OS/editor artifacts: .DS_Store, Thumbs.db, .suo, .ntvs_analysis.dat

​
Size Limits

  • Maximum file size: 1MB
  • Files larger than this are skipped (usually generated/minified code)

​
Custom Extensions

Add custom file types during indexing: 
index_codebase({
  path: "/my/project",
  customExtensions: [".vue", ".svelte", ".astro"]
})

​
Custom Ignore Patterns

Exclude specific files or directories: 
index_codebase({
  path: "/my/project",
  ignorePatterns: [
    "vendor/**",
    "generated/**",
    "*.generated.ts"
  ]
})
Patterns use glob semantics. Examples:
  • static/** excludes a directory tree
  • *.tmp excludes matching files at any depth
  • private/** excludes private source trees
Team-dependent patterns like vendor/**, third_party/**, and generated/** are not enabled by default; add them via ignorePatterns when needed.

​
Performance

EventProcessing TimeNotes
Single file modify~2-3sDebounce + embed + store
Multiple files (batch)~3-5sParallel embedding
Large file (>100 chunks)~5-8sMore chunks to process
No actual change~0.1sHash check, skip
Syntax error~0.1sSkip, keep old vectors

​
Manual Control

​
Stop Watching

To disable automatic updates: 
> Stop watching this project

● stop_watch (MCP)
  path: "/my/project"
  ⎿ ✓ Stopped watching

​
Resume Watching

To re-enable: 
> Start watching again

● start_watch (MCP)
  path: "/my/project"
  ⎿ ✓ Started watching

​
Check Status

> What's being watched?

● get_watch_status (MCP)
  ⎿ Watching 2 codebases:
  ⎿ 1. /projects/app-a
  ⎿ 2. /projects/app-b

​
Troubleshooting

​
Changes Not Detected

  1. Verify watching is active: get_watch_status
  2. Check file extension is supported
  3. Ensure file is not in ignored patterns
  4. File might be too large (>1MB)

​
Slow Updates

  1. Check network connectivity
  2. Large files take longer to process
  3. Many simultaneous changes batch together

​
Index Out of Sync

If the index seems outdated: 
> Force re-index this codebase

● index_codebase (MCP)
  path: "/my/project"
  force: true
  ⎿ Deleting existing index...
  ⎿ Full re-index starting...