Obsidian Performance TuningSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: obsidian-performance-tuning
description: 'Optimize Obsidian plugin performance for smooth operation in large vaults.

  Use when experiencing lag, memory issues, slow startup, or optimizing

  plugin code for vaults with thousands of files.

  Trigger with phrases like "obsidian performance", "obsidian slow",

  "optimize obsidian plugin", "obsidian memory usage", "obsidian lag".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 1.13.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- obsidian
- performance
- optimization
- memory
- profiling
compatibility: Designed for Claude Code
---
# Obsidian Performance Tuning

## Overview

Optimize Obsidian plugin performance for large vaults (10,000+ files): profile bottlenecks with DevTools, implement lazy initialization, process files in batches with UI yielding, use LRU caches with bounded memory, debounce event handlers, and optimize DOM rendering with virtual scrolling and DocumentFragment.

## Prerequisites

- Working Obsidian plugin with at least one performance concern
- Developer Console access (Ctrl+Shift+I / Cmd+Option+I)
- Understanding of async JavaScript and the event loop

## Performance Benchmarks

| Metric | Good | Warning | Critical |
|--------|------|---------|----------|
| Plugin load time (`onload`) | < 100ms | 100-500ms | > 500ms |
| Command execution | < 50ms | 50-200ms | > 200ms |
| Single file operation | < 10ms | 10-50ms | > 50ms |
| Memory increase on load | < 10MB | 10-50MB | > 50MB |
| Event handler execution | < 5ms | 5-20ms | > 20ms |

## Instructions

### Step 1: Profile with DevTools Performance Tab

```typescript
// Add timing instrumentation to identify bottlenecks
export default class MyPlugin extends Plugin {
  async onload() {
    const loadStart = performance.now();

    await this.loadSettings();
    console.log(`[perf] loadSettings: ${(performance.now() - loadStart).toFixed(1)}ms`);

    const indexStart = performance.now();
    await this.buildIndex();
    console.log(`[perf] buildIndex: ${(performance.now() - indexStart).toFixed(1)}ms`);

    const cmdStart = performance.now();
    this.registerCommands();
    console.log(`[perf] registerCommands: ${(performance.now() - cmdStart).toFixed(1)}ms`);

    console.log(`[perf] total onload: ${(performance.now() - loadStart).toFixed(1)}ms`);
  }
}
```

For deeper analysis, use the DevTools Performance tab:

1. Open DevTools (Ctrl+Shift+I)
2. Go to Performance tab
3. Click Record
4. Toggle your plugin off/on in Settings > Community Plugins
5. Stop recording
6. Look for long tasks (yellow bars > 50ms) in the flame chart

### Step 2: Lazy Initialization — Defer Expensive Work

```typescript
// BAD: build index on load (blocks startup)
async onload() {
  this.index = await this.buildFullIndex(); // 2 seconds on large vaults
}

// GOOD: lazy — build on first use
export default class MyPlugin extends Plugin {
  private _index: Map<string, string[]> | null = null;
  private indexPromise: Promise<Map<string, string[]>> | null = null;

  async getIndex(): Promise<Map<string, string[]>> {
    if (this._index) return this._index;
    if (!this.indexPromise) {
      this.indexPromise = this.buildFullIndex().then(idx => {
        this._index = idx;
        this.indexPromise = null;
        return idx;
      });
    }
    return this.indexPromise;
  }

  async onload() {
    // Register commands immediately — index builds on first command use
    this.addCommand({
      id: 'search',
      name: 'Search indexed notes',
      callback: async () => {
        const index = await this.getIndex(); // builds on first call only
        // ... use index
      },
    });
  }

  private async buildFullIndex(): Promise<Map<string, string[]>> {
    const index = new Map<string, string[]>();
    const files = this.app.vault.getMarkdownFiles();
    for (const file of files) {
      const cache = this.app.metadataCache.getFileCache(file);
      if (cache?.tags) {
        index.set(file.path, cache.tags.map(t => t.tag));
      }
    }
    return index;
  }
}
```

### Step 3: Batch File Processing with UI Yielding

```typescript
import { TFile, Notice } from 'obsidian';

async processAllFiles(statusEl?: HTMLElement): Promise<number> {
  const files = this.app.vault.getMarkdownFiles();
  const BATCH_SIZE = 50;
  let processed = 0;

  for (let i = 0; i < files.length; i += BATCH_SIZE) {
    const batch = files.slice(i, i + BATCH_SIZE);

    for (const file of batch) {
      // Use cachedRead — avoids hitting disk on every call
      const content = await this.app.vault.cachedRead(file);
      this.processContent(file, content);
      processed++;
    }

    // Yield to UI thread — prevents "not responding" dialog
    await sleep(0);

    // Update progress
    if (statusEl) {
      const pct = Math.round((processed / files.length) * 100);
      statusEl.setText(`Processing: ${pct}% (${processed}/${files.length})`);
    }
  }

  return processed;
}

// Helper: Obsidian exports sleep(), or use this
function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}
```

### Step 4: LRU Cache for Bounded Memory

```typescript
// src/services/lru-cache.ts
export class LRUCache<K, V> {
  private cache = new Map<K, V>();

  constructor(private maxSize: number) {}

  get(key: K): V | undefined {
    const value = this.cache.get(key);
    if (value !== undefined) {
      // Move to end (most recently used)
      this.cache.delete(key);
      this.cache.set(key, value);
    }
    return value;
  }

  set(key: K, value: V) {
    this.cache.delete(key); // remove if exists (reinserts at end)
    this.cache.set(key, value);
    if (this.cache.size > this.maxSize) {
      // Evict oldest (first) entry
      const oldest = this.cache.keys().next().value;
      if (oldest !== undefined) this.cache.delete(oldest);
    }
  }

  has(key: K): boolean { return this.cache.has(key); }
  delete(key: K): boolean { return this.cache.d

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.