obsidian-curator

Manage Obsidian vaults via LiveSync CouchDB — capture notes, AI-enrich and file them, manage tasks, audit and tidy vault structure. Use when working with Obsidian vaults through CouchDB/LiveSync (not local filesystem). Requires CouchDB with Obsidian LiveSync plugin. AI features (process, file) need an AI provider configured; capture, audit, tidy, and tasks work rule-based without any API key.

Manage Obsidian vaults through the CouchDB database that powers Obsidian LiveSync. Capture, process, file, audit, tidy, and manage tasks — all via CLI or Node.js API.

Prerequisites: CouchDB with LiveSync configured, E2EE disabled.

Security & Trust

• Open source: github.com/philmossman/obsidian-curator (MIT)
• npm provenance: Published via GitHub Actions OIDC with Sigstore attestation — cryptographically verifiable build provenance
• No lifecycle scripts: No preinstall, install, or postinstall scripts — npm install only copies files
• Minimal dependencies: Only nano (CouchDB client) and date-fns (date parsing)
• Local network only: Connects to your CouchDB instance (user-configured host/port). No external telemetry, no phone-home, no data leaves your network
• Credentials: Stored locally in ~/.obsidian-curator/config.json — never transmitted except to your own CouchDB
• E2EE note: LiveSync E2EE must be disabled because the tool reads/writes vault documents directly via CouchDB. This is a LiveSync architectural requirement, not a security compromise by this tool

Setup

Run the interactive wizard — it tests the CouchDB connection live:

bash

obsidian-curator init

Configures: CouchDB connection, vault structure preset (PARA/Zettelkasten/Johnny Decimal/Flat/Custom), AI provider (OpenAI/Anthropic/Ollama/None), task projects.

Config location: ~/.obsidian-curator/config.json

Commands

Capture (no AI needed)

bash

obsidian-curator capture "Quick thought about project X"
obsidian-curator capture "Meeting notes from standup" --source meeting

Process inbox (AI required)

Enrich inbox notes with tags, summary, and suggested folder:

bash

obsidian-curator process
obsidian-curator process --limit 5 --dry-run
obsidian-curator process --force   # re-process already-processed notes

File notes (AI required)

Route processed notes to canonical vault folders:

bash

obsidian-curator file
obsidian-curator file --dry-run --min-confidence 0.8

Audit (no AI needed)

Check vault structure against configured canonical folders:

bash

obsidian-curator audit

Tidy (AI optional)

Find duplicates, structure violations, dead notes. With AI, ambiguous cases are triaged automatically:

bash

obsidian-curator tidy --dry-run
obsidian-curator tidy --checks dupes,stubs

Tasks (no AI needed)

bash

obsidian-curator tasks                          # list open tasks
obsidian-curator tasks --project Work --priority high
obsidian-curator task "call dentist next Tuesday"   # create task (parses dates, priority, project)
obsidian-curator done "dentist"                     # mark done by partial title match

Config

bash

obsidian-curator config show
obsidian-curator config set ai.provider ollama
obsidian-curator config set vault.host 192.168.1.100

Programmatic API

js

const { VaultClient, Curator, createAIAdapter, loadConfig } = require('obsidian-curator');

const config = loadConfig();
const vault = new VaultClient(config.vault);
await vault.ping();
const ai = createAIAdapter(config);
const curator = new Curator({ vault, ai, config });

await curator.capture('Quick thought');
await curator.process({ limit: 5 });
await curator.file({ dryRun: true });
await curator.audit();
await curator.tidy({ checks: ['dupes', 'stubs'], dryRun: true });

const tasks = await curator.tasks({ status: 'open', project: 'Work' });
await curator.createTask('call Alice next Friday');
await curator.taskBrief();  // markdown summary

AI Providers

Provider	Cost	Privacy	Setup
none	Free	Local	Default — rule-based features only
ollama	Free	Local	config set ai.provider ollama + model name
openai	Pay-per-use	Cloud	config set ai.provider openai + API key
anthropic	Pay-per-use	Cloud	config set ai.provider anthropic + API key
Custom/OpenRouter	Varies	Varies	Use openai provider with custom baseUrl

Vault Structure Presets

• PARA: inbox → Projects / Areas / Resources / Archives
• Zettelkasten: inbox → Slipbox / References / Projects / Archives
• Johnny Decimal: inbox → numbered category folders (00-09, 10-19, ...)
• Flat: inbox only, no enforced structure
• Custom: define your own canonical folders