Obsidian Local Dev LoopSAFE

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-local-dev-loop
description: 'Set up a fast Obsidian plugin development loop with hot reload.

  Covers cloning the sample plugin, esbuild watch mode, symlinking

  into a vault, Ctrl+R hot reload, Chrome DevTools debugging, and

  testing with vitest. Use when starting plugin development or

  configuring a dev environment.

  Trigger with "obsidian dev loop", "obsidian hot reload",

  "obsidian development setup", "develop obsidian plugin".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Bash(mkdir:*), Bash(ln:*),
  Bash(ls:*), Grep
version: 1.13.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- obsidian
- development
- hot-reload
- debugging
- testing
compatibility: Designed for Claude Code
---
# Obsidian Local Dev Loop

## Overview

Establish a fast edit-build-test cycle for Obsidian plugins. Clone the official
sample plugin, run esbuild in watch mode, symlink into a dev vault, hot-reload
with Ctrl+R, debug with Chrome DevTools, and run tests with vitest. Aimed at
sub-second feedback from save to reload.

## Prerequisites

- Node.js 18+ with npm
- Git
- Obsidian desktop app installed
- A vault dedicated to development (keep it separate from your real notes)

## Instructions

### Step 1: Clone the official sample plugin

Start from the maintained template rather than from scratch:

```bash
set -euo pipefail

git clone https://github.com/obsidianmd/obsidian-sample-plugin.git my-plugin
cd my-plugin
rm -rf .git
git init

npm install
```

The sample includes `esbuild.config.mjs`, `tsconfig.json`, `manifest.json`, and
a working `src/main.ts`.

### Step 2: Create a dedicated dev vault

Keep a vault just for testing. Pre-populate it with sample notes.

```bash
set -euo pipefail

DEV_VAULT="$HOME/ObsidianDev"
mkdir -p "$DEV_VAULT/.obsidian/plugins"
mkdir -p "$DEV_VAULT/Test Notes"

cat > "$DEV_VAULT/Test Notes/Sample.md" << 'EOF'
---
tags: [test, sample]
---
# Sample Note

This note exists for plugin development testing.

## Section A

Some content with a [[link]] and a #tag.

## Section B

- Item 1
- Item 2
- Item 3
EOF

echo "Dev vault ready at $DEV_VAULT"
```

Open this vault in Obsidian: File > Open vault > select `~/ObsidianDev`.

### Step 3: Symlink the plugin into the dev vault

Instead of copying files after every build, symlink the entire project directory.
The build outputs `main.js` at the project root, right where Obsidian expects it.

```bash
set -euo pipefail

DEV_VAULT="$HOME/ObsidianDev"
PLUGIN_DIR="$(pwd)"
PLUGIN_ID=$(node -e "console.log(require('./manifest.json').id)")

# Symlink project root into vault plugins folder
ln -sfn "$PLUGIN_DIR" "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID"

# Verify
ls -la "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID/manifest.json"
echo "Symlinked $PLUGIN_ID into dev vault."
```

On Windows, use an admin terminal:

```powershell
mklink /D "%USERPROFILE%\ObsidianDev\.obsidian\plugins\my-plugin" "%cd%"
```

### Step 4: Run esbuild in watch mode

Watch mode rebuilds `main.js` on every source file change (typically <50ms).

```bash
npm run dev
# esbuild watches src/ and rebuilds main.js on save
# Output: "build finished" messages in the terminal
```

The `esbuild.config.mjs` from the sample plugin already supports this.
Inline source maps are enabled in dev mode for accurate stack traces.

### Step 5: Hot-reload in Obsidian

After esbuild rebuilds, reload the plugin in Obsidian:

**Method A -- Keyboard (fastest):**
Press `Ctrl+R` (or `Cmd+R` on macOS) to reload the app. This unloads all plugins
and reloads them, picking up the new `main.js`.

**Method B -- Hot Reload plugin (automatic):**
Install the [Hot Reload](https://github.com/pjeby/hot-reload) community plugin.
It watches for `main.js` changes in plugin directories and auto-reloads only the
changed plugin. No manual refresh needed.

1. In Obsidian, install "Hot Reload" from Community plugins
2. Enable it
3. Create a `.hotreload` file in your plugin directory: `touch .hotreload`
4. Now every esbuild rebuild triggers an automatic plugin reload

**Method C -- Command palette:**
Press `Ctrl+P`, type "Reload app without saving", Enter.

### Step 6: Debug with Chrome DevTools

Obsidian is an Electron app, so full Chrome DevTools are available.

1. Press `Ctrl+Shift+I` (or `Cmd+Option+I` on macOS) to open DevTools
2. **Console** tab -- see `console.log` output from your plugin
3. **Sources** tab -- set breakpoints in your code (source maps required)
4. **Network** tab -- inspect any HTTP requests your plugin makes
5. **Elements** tab -- inspect Obsidian's DOM for CSS/layout work

Tips:

- With inline source maps enabled, your TypeScript source appears in Sources > `src/main.ts`
- Use `debugger;` statements in code for precise breakpoints
- `console.log('[MyPlugin]', ...)` prefix makes filtering easy

```typescript
// Add to onload() for development:
if (process.env.NODE_ENV !== "production") {
  console.log("[MyPlugin] Dev mode active. Use Ctrl+Shift+I for DevTools.");
}
```

### Step 7: Testing with vitest

Obsidian plugins can be unit-tested by mocking the `obsidian` module.

```bash
set -euo pipefail
npm install --save-dev vitest
```

Create `vitest.config.ts`:

```typescript
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
  },
});
```

Create a mock for the obsidian module at `__mocks__/obsidian.ts`:

```typescript
export class Plugin {
  app = {};
  loadData = vi.fn().mockResolvedValue({});
  saveData = vi.fn().mockResolvedValue(undefined);
  addCommand = vi.fn();
  addRibbonIcon = vi.fn();
  addSettingTab = vi.fn();
  addStatusBarItem = vi.fn().mockReturnValue({ setText: vi.fn() });
  registerEvent = vi.fn();
  registerInterval = vi.fn();
}

export class Notice {
  constructor(public message: string) {}
}

export class PluginSettingTab {
  containerEl = { empty: vi.fn(), createEl: vi.fn() };
  constructor(public app: any, public plugin: any) {}
  display() {}

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.