> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharc.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# File Watching

> Real-time incremental indexing as you code

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

```mermaid theme={null}
flowchart TB
    A["📁 File System Events<br>(add, modify, delete)"] --> B["👁️ chokidar<br>(File Watcher)"]
    B --> C["⏱️ Processing Queue<br>(2s debounce)"]
    
    subgraph Indexer["Incremental Indexer"]
        D1["Hash Check<br>(skip same)"]
        D2["Syntax Guard<br>(skip broken)"]
        D3["Chunker<br>(AST/Lang)"]
    end
    
    C --> Indexer
    Indexer --> E["🌐 Backend API<br>(Update vectors, sync metadata)"]
```

## 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 (highest precedence last):

1. Default ignore patterns (always applied)
2. Root `.gitignore` patterns
3. Root `.sharcignore` patterns
4. `ignorePatterns` passed to `index_codebase`

### `.sharcignore`

Create a `.sharcignore` file at the root of your repository to permanently exclude paths from indexing. It follows the same syntax as `.gitignore`:

```gitignore theme={null}
# Ignore generated code
generated/**
proto/**

# Ignore specific directories
internal/legacy/**

# Negation: re-include a file excluded by .gitignore
!generated/keep.ts
```

Rules:

* One pattern per line
* Lines starting with `#` are comments
* Trailing `/` is treated as a directory (e.g., `logs/` becomes `logs/**`)
* Prefix a pattern with `!` to negate (re-include something excluded by an earlier rule or `.gitignore`)
* `.sharcignore` takes precedence over `.gitignore` — use it to override `.gitignore` rules that make sense for git but not for code search

<Tip>
  Use `.sharcignore` for patterns your whole team should share. Use the `ignorePatterns` parameter on `index_codebase` for one-off exclusions.
</Tip>

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

| Event                    | Processing Time | Notes                    |
| ------------------------ | --------------- | ------------------------ |
| Single file modify       | \~2-3s          | Debounce + embed + store |
| Multiple files (batch)   | \~3-5s          | Parallel embedding       |
| Large file (>100 chunks) | \~5-8s          | More chunks to process   |
| No actual change         | \~0.1s          | Hash check, skip         |
| Syntax error             | \~0.1s          | Skip, 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...
```