Obsidian

obsidian

Operate on the user's Obsidian vault as plain Markdown files. Obsidian itself does not need to be running — the vault is just a directory tree of .md files.

Setup check (lazy — resolve path once, don't re-probe)

The vault path resolves as $OBSIDIAN_VAULT_PATH env var → fallback ~/Documents/Obsidian Vault. Resolve it once when you first need it this conversation; do not re-probe printenv on every turn. Operate on the resolved path directly and map failures:

• os.fs.list / read errors with ENOENT / "no such file or directory" → Setup playbook → "Vault path does not exist".
• the path exists but holds no .md files → Setup playbook → "Resolved path is not a real vault".

Vault paths often contain spaces — pass them through os.fs.* tools verbatim, no quoting needed.

Setup playbook (when prerequisites are missing)

When a check fails, the agent's job is to OFFER concrete help and EXECUTE the fix itself — not to dump setup instructions on the user. Use this dialogue shape:

1. State plainly what is missing.
2. Offer the most direct remediation the agent can perform via tools.
3. Wait for the user's reply.
4. Execute the fix via tools.
5. Retry the original command; only then proceed.

Vault path does not exist

Reply:

"I couldn't find an Obsidian vault in either $OBSIDIAN_VAULT_PATH or ~/Documents/Obsidian Vault. Send me the absolute path to your vault — I'll verify it and save it to ~/.atomic-agent/.env so I can find it automatically in the future."

When the user replies with a path, verify it exists:

[{ "tool": "os.fs.list", "args": { "path": "<user-supplied-path>" } }]

If it lists .md files, persist the choice:

[{ "tool": "os.fs.write", "args": {
   "path": "~/.atomic-agent/.env",
   "mode": "append",
   "content": "\nOBSIDIAN_VAULT_PATH=<user-supplied-path>\n"
} }]

Then reply: "Vault found and saved. Restart the agent so the env variable is picked up — I'll continue after the restart. (I'm already using the path for the current session.)" Continue using the path in-memory for the current session — no need to wait for restart to serve the user's request.

If the path does NOT contain .md files, ask once more before persisting: "There are no markdown files at this path. Is the vault really there, or is it a different path?"

Resolved path is not a real vault

Same playbook as above, but skip the "not found" framing — just say: "The default folder (~/Documents/Obsidian Vault) exists, but it doesn't look like an Obsidian vault — there are no markdown files. Send me the correct path."

When to use

• The user asks to read, list, search, create, or append to notes in their Obsidian vault.
• Markdown-native knowledge management with [[wikilinks]] between notes.

When NOT to use

• Apple Notes (cross-device iCloud) — use the apple-notes skill instead.
• Agent-internal scratch notes that don't need to live in the vault — use the memory.notes.store tool.

Common operations

List notes

All Markdown files in the vault:

os.fs.glob { patterns: ["**/*.md"], cwd: "<vault>" }

Notes in a specific subfolder:

os.fs.glob { patterns: ["Daily/**/*.md"], cwd: "<vault>" }

Read a note

os.fs.read { path: "<vault>/Note Name.md" }

For very long notes, use offset / limit to page through.

Search by filename

os.fs.glob { patterns: ["**/*keyword*.md"], cwd: "<vault>" }

Search by content

os.fs.grep { pattern: "keyword", path: "<vault>", glob: ["*.md"] }

Use outputMode: "files_with_matches" to get just the file list.

Create a new note

os.fs.write { path: "<vault>/New Note.md", content: "# Title\n\nBody here.\n" }

Append to an existing note

os.fs.write { path: "<vault>/Existing Note.md", content: "\nAppended line.\n", mode: "append" }

Notes

• Wikilinks use the [[Note Name]] syntax (no .md extension). Use them when creating notes that should link to other notes — Obsidian will render them as clickable links and surface backlinks automatically.
• Daily notes typically live under Daily/YYYY-MM-DD.md — confirm the user's pattern before assuming.
• Do not edit .obsidian/ config files unless the user explicitly asks; they hold the vault's plugin and theme settings.