Vault File Refresh

Automatically picks up files added to your Obsidian vault from outside the app — no manual restart required.

If you use Obsidian installed as a Flatpak, store your vault on a network drive, sync files via scripts or AI tools, or write to the vault from external applications, you have likely noticed that new files and folders do not appear in the file explorer until you restart Obsidian. This plugin fixes that.

What It Does

Vault File Refresh runs a lightweight background poller that recursively scans your entire vault every 8 seconds. When it detects files that exist on disk but are not yet known to Obsidian, it reconciles them — making them immediately available in the file explorer, search, graph view, and Dataview queries without any manual intervention.

Why This Happens

Obsidian uses filesystem watchers (via chokidar) to detect external changes. In certain environments, those watchers do not receive events reliably:

• Flatpak installs access the filesystem through the XDG Desktop Portal, which can block or delay inotify events from reaching the app
• Network or FUSE-mounted drives may not propagate filesystem events
• Some Linux configurations restrict inotify watch limits, causing events to be silently dropped

The community Auto Refresh plugin addresses a related issue but requires explicitly listing each folder to watch and does not operate recursively.

Features

• Fully recursive — covers the entire vault including all nested subfolders
• Automatically tracks new folders as they are created
• No configuration required — works out of the box
• Removes stale paths from tracking when files are deleted
• Logs reconciled files to the developer console for transparency
• Minimal performance footprint — async polling with no blocking operations

Installation

From the Community Plugin Browser (recommended)

1. Open Obsidian Settings > Community Plugins
2. Search for Vault File Refresh
3. Click Install, then Enable

Manual Installation

1. Download manifest.json and main.js from the latest release
2. Create a folder at <your-vault>/.obsidian/plugins/vault-file-refresh/
3. Place both files in that folder
4. Open Obsidian Settings > Community Plugins and enable the plugin

Configuration

No configuration is required. The plugin works immediately on enable.

To adjust the polling interval, open main.js and change the DEFAULT_INTERVAL value at the top of the file (in milliseconds). Reload the plugin after saving.

Compatibility

• Desktop only (not applicable to mobile)
• Tested on Obsidian 1.x
• Linux (Flatpak and native), macOS, and Windows compatible

Debugging

Open the developer console (Ctrl+Shift+I or Cmd+Option+I) and filter for VaultFileRefresh. The plugin logs each reconciliation event with the affected file paths. Errors are reported under VaultFileRefresh error.

Known Limitations

• New files appear within 8 seconds of being written to disk rather than instantly
• Uses vault.adapter.reconcileFile(), an internal Obsidian API not formally documented in the public plugin API. Works reliably across current Obsidian versions but may require an update if Obsidian internals change

Use Cases

• Obsidian installed as a Flatpak on Linux
• Writing notes or documents to your vault from external scripts or automation tools
• Using AI tools such as Claude Code with the Obsidian Local REST API plugin
• Syncing vault content from another machine or service that writes files directly
• Storing your vault on a NAS or network-mounted drive

Contributing

Issues and pull requests welcome. Please open an issue before submitting a PR for significant changes.

License

MIT