Read-only virtual filesystem exposing an Obsidian vault via the obs:// protocol. Three entrypoints — a VS Code extension, a Claude Code plugin, and a CLI — built on a shared core engine.
| Package | Description | Docs |
|---|---|---|
packages/core |
obs:// URI resolution, LRU cache, Obsidian CLI wrapper, direct file reads via node:fs |
README |
packages/vscode |
VS Code FileSystemProvider for obs:// — browse, search, and edit your vault in the editor |
README |
packages/claude-plugin |
Claude Code plugin resolving @obs: and /obs: mentions into context via UserPromptSubmit hook |
README |
packages/cli |
npx obsidian-vfs — inspect, resolve, list, and provision vault skills and agents |
README |
The consumer packages (vscode, claude-plugin, cli) depend on core but have no cross-dependencies between each other.
pnpm install
pnpm build
pnpm testPlace a JSON file at .obsidian/obsidian-vfs.json inside your vault. All fields are optional and default to empty arrays:
{
"agents": ["path/to/agents"],
"skills": ["path/to/skills"],
"allowed": ["folder-a", "folder-b"],
"blocked": ["folder-a/private"]
}| Field | Type | Description |
|---|---|---|
agents |
string[] |
Vault-relative directories containing agent definitions (flat .md files) |
skills |
string[] |
Vault-relative directories containing skill definitions (name/SKILL.md) |
allowed |
string[] |
Restrict general vault access to these directories. Empty = full vault access |
blocked |
string[] |
Deny access to these directories (evaluated before allowed) |
allowed and blocked restrict general vault content — notes, wikilinks, directory browsing, and workspace mounts. agents and skills directories are implicitly allowed and exempt from these restrictions.
blocked is evaluated first (deny wins). When a path matches both allowed and blocked, it is blocked. A blocked entry may be a child of an allowed entry (carving an exception), but not a parent — that configuration is rejected at load time.
Wikilinks inside allowed notes that reference disallowed targets are visible but inert: the text remains, but the target cannot be resolved, read, or clicked.
See CONTRIBUTING.md for development setup, scripts, architecture, and coding conventions.