Turn a plain-language request into a plugin change that works in the running app and passes community review. One loop does it: spec → explore → prototype → implement → build, reload, verify → review. Code written against what is actually in the live app beats code written from memory of the API, because Obsidian's DOM and private internals move between releases.
obsidian.d.ts in node_modules/obsidian/ is the source of truth for every public signature.
Read it rather than guessing. Docs: https://docs.obsidian.md.
Step 0: find the runtime backend
The loop needs six capabilities. Work out which backend gives them before writing code.
- An Obsidian MCP server. List the connected tools and match on purpose, not exact names.
Names differ between servers (
obsidian_eval,obsidian_execute_js, …). - The official Obsidian CLI (installer 1.12.7+, Settings → General → Command line
interface). Check with
obsidian versionin Bash. It covers every capability itself, and the best-maintained MCP server is a thin wrapper around it. - Neither. Build, then ask the user to reload the plugin and paste the console output (and a screenshot if the change is visual). Say which checks you could not run yourself.
| Capability | Typical MCP tool | CLI command |
|---|---|---|
| Eval JS | *_eval, *_execute_js |
obsidian eval code="…" |
| Read console and errors | *_console, *_errors |
obsidian dev:console [level=error] [clear], obsidian dev:errors |
| Query DOM and CSS | *_dom, *_css, *_dom_query |
obsidian dev:dom selector=… [text] [all], obsidian dev:css selector=… |
| Screenshot | *_screenshot |
obsidian dev:screenshot path=<file> |
| Reload or enable a plugin | *_plugin_reload, *_enable_plugin |
obsidian plugin:reload id=<id> |
| List or run commands | *_commands, *_command |
obsidian commands filter=<id>, obsidian command id=<id> |
CDP-based servers need Obsidian started with the debug port, after quitting any running instance:
/Applications/Obsidian.app/Contents/MacOS/Obsidian --remote-debugging-port=9222. CLI-based
servers need the CLI setting on. Setup for either, plus CLI gotchas: references/runtime-inspection.md.
Safety. Prefer a dedicated test vault. Exploration evals must be read-only. Ask before any eval that writes, renames, moves or deletes vault files or changes another plugin's settings. The user's vault is not a sandbox.
The loop
1. Clarify the spec
Restate the request as three short lists before touching code:
- Behaviours: what the user sees or can do, including when it updates.
- API surfaces: which classes and events (see
references/api-map.md). - Done when: the observable checks you will run in step 5, such as "view lists 3 notes in the test vault", "no errors in console after reload", "command appears in palette".
Ask only if a behaviour is ambiguous in a way that changes the code. Otherwise state your assumption and go.
2. Explore before writing
Inspect the live app so the code targets what is there:
- the DOM and CSS classes of the UI you will touch or sit beside
- existing views and leaves, registered commands, enabled plugins
- the metadata cache for real notes the feature reads
- the plugin's own loaded state (
app.plugins.plugins["<id>"])
Snippets: references/runtime-inspection.md. Check signatures in obsidian.d.ts. If the only way
to do something is an undocumented app.* internal, say so to the user, isolate it behind one
function, and guard it so a missing property degrades instead of throwing.
3. Prototype in the runtime
Try the core logic with eval against the live app first, for example the query that collects the
data, or the DOM structure you plan to render. One eval answers in seconds what a
build-reload cycle answers in a minute. Return plain projections ({path, fm}), not TFile or
App, which cannot be serialised.
4. Implement
Write it into the plugin project using references/patterns.md and
references/lifecycle-and-cleanup.md. main.ts only wires things up. Each view, modal, settings
tab and editor extension lives in its own module. No project yet: references/project-setup.md.
5. Build, reload, verify
npm run build. Fix type errors before anything else.- Deploy and reload. Use
scripts/deploy.sh <vault-path>when the project is outside the vault, orplugin:reloadwhen it already lives in<vault>/.obsidian/plugins/<id>/. - Clear the console, exercise the feature (run the command or open the view via eval), then read the console. Any error from the plugin is a failure.
- Query the DOM for the elements the spec promised, and screenshot the affected UI.
- Check the "done when" list item by item. Loop until each one passes.
Report what you verified and how. If a check could not run, say so and why.
6. Review
Run npx eslint . from the repo root (not eslint src, which skips manifest.json and
LICENSE), then walk references/review-checklist.md. Fix every error. Treat warnings as
blockers too, since they count against the plugin in review.
Rules that matter most
Each one maps to a review rejection or a real bug.
- Register everything.
registerEvent,registerDomEvent,registerInterval,addCommand,registerView,registerEditorExtension. Thenonunloadhas nothing to do. Never detach leaves inonunload. - Never hold a view reference on the plugin. Find views with
workspace.getLeavesOfType(TYPE). - Defer startup work to
this.app.workspace.onLayoutReady(...).onloadmust stay fast. - Files through the Vault and FileManager APIs. Use
vault.processfor background edits,fileManager.processFrontMatterfor frontmatter, theEditorfor the open note, andfileManager.trashFilefor deletes. Look files up withvault.getFileByPath, never by looping all files. Pass user paths throughnormalizePath. Usevault.adapteronly for files outside the vault index. - Active view via
workspace.getActiveViewOfType(MarkdownView)orworkspace.activeEditor?.editor, neverworkspace.activeLeaf. - Build DOM with
createEl,createDivandcreateSpan, and clear withel.empty(). Never useinnerHTML,outerHTMLorinsertAdjacentHTML, and never inline styles. Style with classes instyles.cssusing Obsidian CSS variables. - Narrow types, never cast.
if (f instanceof TFile). Strict TypeScript, noany. - Network via
requestUrl, notfetch. It works on mobile and avoids CORS. - Mobile by default. No Node or Electron imports unless
isDesktopOnly: true. UsePlatformto branch. No regex lookbehind, which breaks older iOS. - UI text in sentence case. Settings headings via
new Setting(el).setName(…).setHeading(), and only when there is more than one section. No default hotkeys. Command ids and names must not repeat the plugin id or name, since Obsidian prefixes them.
Where to look
| When you need… | Read |
|---|---|
| Which API for a job: Vault vs Adapter vs FileManager, Workspace and leaves, MetadataCache, Editor vs CM6, events | references/api-map.md |
| Code shape for a view, modal, suggest, settings tab (incl. 1.13 declarative settings), command, ribbon, status bar, editor extension, post-processor | references/patterns.md |
onload/onunload, the register* family, leaks, onLayoutReady, multi-window |
references/lifecycle-and-cleanup.md |
| Eval snippets, backend setup, CLI gotchas, debugging "renders blank" or "no effect" | references/runtime-inspection.md |
| Pre-submission: guidelines, eslint-plugin-obsidianmd rules, manifest, release | references/review-checklist.md |
| New plugin, build config, hot reload, version bump, releases | references/project-setup.md |
Output
Keep replies short: the spec lists, what you changed (files), what you verified and how, and anything unverified or using private API. Show code only when the user needs to see it.