aidenlx/zotlit / .agents/skills/obsidian-debug
obsidian-debug
VerifiedDrive the running Obsidian instance to verify plugin changes — build, reload, eval, screenshot. Use after editing plugin UI or behavior to confirm the change works in the real app, when debugging why something looks wrong at runtime, or when another skill says "verify in Obsidian." Also use when the user asks to test, check, run, or screenshot the plugin, or to inspect desktop Obsidian with CDP, iOS with Safari Web Inspector, or Android with adb and CDP.
Debug Loop
Drive the running Obsidian app to verify plugin changes against real rendered state. The DOM is the source of truth.
iOS — for a real iPhone, follow ios.md to attach to the active Obsidian WebView and run probes from the Mac.
Android — follow android.md to set up a standalone emulator or attach to Obsidian on a USB device, then run WebView probes from the Mac.
On desktop, make every Obsidian CLI call through packages/scripts/scripts/obsidian-cli.ts (written
obsidian-cli.ts below), run from the repo root. It takes the obsidian binary's arguments
and prints its output, and it always sees the end of a reply — the binary can miss it on macOS
and wait until killed.
DevTools — when the CLI cannot show it (DOM and CSS internals, network, profiles, breakpoints, popout or settings windows, the main process), follow devtools.md.
Vault setup, once per worktree
- Run
packages/scripts/scripts/obsidian-cli.ts version. It must print Obsidian's version. Readobsidian-cli.ts --helpfor its arguments, timeout, and exit codes. - Run
packages/scripts/scripts/obsidian-vault.ts --help. - Before you use a vault command, read its
<command> --helpoutput. - Run
packages/scripts/scripts/obsidian-vault.ts check. Vault setup is complete when the command succeeds. Follow its recovery instructions when it fails. - Build the plugin, then use the live
opencommand to prepare this worktree's Development Vault:
pnpm exec turbo run build --filter='@zotlit/obsidian^...'
pnpm --filter @zotlit/obsidian build:dev
The first command rebuilds the workspace packages the plugin bundles from
their dist, such as @zotlit/workbench. The second builds the plugin and
copies it into the vault.
Editing the Fixture Spec or its committed vault-page assets changes the next
Fixture build, not the open Development Vault. Use the live open command
before you look for those changes.
Teardown
When the check is done, close what the check opened, in this order:
pnpm fixture stop— closes a Paired Zotero thatpnpm fixture openleft running.packages/scripts/scripts/obsidian-vault.ts remove --purge— removes the Development Vault.
Commands
| Command | What it does |
|---|---|
obsidian-cli.ts vault=<id> plugin:reload id=zotlit | Reload the plugin after a build |
obsidian-cli.ts vault=<id> commands filter=zotlit | List available plugin commands |
obsidian-cli.ts vault=<id> command id=zotlit:<cmd> | Run a command |
obsidian-cli.ts --code '<js>' vault=<id> | Run JS in the app, returns the value |
obsidian-cli.ts --js <file.js> vault=<id> | Run a JS file in the app; use it for multi-line probes |
obsidian-cli.ts --shot <file> --selector <css> vault=<id> | Capture one element; --sample x,y reads a pixel's colour |
obsidian-cli.ts vault=<id> dev:screenshot path=<abs> | Capture the window (absolute path required) |
obsidian-cli.ts vault=<id> dev:errors | Captured errors |
obsidian-cli.ts vault=<id> dev:console | Console output |
Read the output text: => prefixes a result, and command failures come back as Error: … or
Vault not found.
Write each call as one plain command with literal values: <id> is the vault ID
obsidian-vault.ts id prints, typed out, and JS goes through --code or --js.
Loop
Hold a Desktop Slot for the walk: wrap it in pnpm desktop-slot run --for <duration> -- … (a script of the walk, or sleep <seconds> in the background while you make the calls). Exit 75 means blocked by the holder it names, not a failure.
- Build — the two build commands from Vault setup step 5. The second copies the
bundle into this worktree's Development Vault; prefix it with
ZT_VAULT_CASE=<case>to copy into a Vault Case vault, such as theupgradervault. - Reload —
obsidian-cli.ts vault=<id> plugin:reload id=zotlit. A leaf or embed open across the reload keeps the old build's DOM: runleaf.rebuildView()on each ZotLit leaf, or the note holding the embed, or open a fresh one, before you probe. - Open —
obsidian-cli.ts vault=<id> command id=zotlit:<cmd>, or--codeto mount a view in a specific split. - Probe —
obsidian-cli.ts --code '…' vault=<id>withgetComputedStyle(el)/el.getBoundingClientRect()to assert what actually rendered. A computed-style assertion is worth more than eyeballing a screenshot, and it is the only way to catch a state that expires on its own — a flash class is gone by the time the capture lands. - Screenshot —
obsidian-cli.ts --shot <file> --selector <css> vault=<id>for the surface under test;dev:screenshotwhen the whole window matters. Save inside the workspace. A colour question — a fade, a blend, a border — is answered by--sample, not by eye.obsidian-cli.ts --helphas the options. - Errors —
obsidian-cli.ts vault=<id> dev:errors/dev:console.
Driving state
Values change through code, and DOM ops check how the UI looks and behaves.
| Target | Expression |
|---|---|
| Obsidian app config | app.vault.setConfig(key, value) |
| Fixture database write | Fork the built data, save zoteroPref.dataDirOverride, call zoteroPref.setDataDir(<fork>), write to the fork, restore the saved override, then remove the fork. Follow Write to a data fork. |
| ZotLit setting | app.plugins.plugins.zotlit.settingTab.setControlValue("citation.at-trigger", false) |
setControlValue runs the same SettingsService path the rendered control does and persists to
the plugin's data.json; getControlValue reads the effective value back. Read the value first
and put it back when you are done.
Gotchas
Settings land in their own window
app.setting.open() renders into a separate Electron window by default since 1.13.4, and --code,
dev:dom, and dev:screenshot all address the main one — so settings read as never opened. Run
/obsidian-settings → "Verifying on screen" for the config that brings the modal back into the
main window, and for reaching the separate window when its own chrome is the thing under test.
Async work in --code
Code run through --code or --js runs in a non-async wrapper — top-level await is a syntax error. Return the
promise from an async IIFE; the CLI awaits it and prints the settled value. Hold the leaf from getLeaf(...)
and revealLeaf(it) in the same call rather than re-querying getLeavesOfType(...) after an
async setViewState (races, returns []).
Trusted input
el.click() and dispatchEvent(new KeyboardEvent(…)) send untrusted events. The browser
skips its own handling for them: Escape and a click outside never close a popover="auto",
and close watchers group stacked popovers as one, so one Escape closes both. When the
browser's handling is the thing under test — popover light-dismiss, close watchers, user
activation — send trusted input through the window's webContents, no CDP needed:
const wc = require("@electron/remote").getCurrentWebContents();
wc.sendInputEvent({ type: "keyDown", keyCode: "Escape" });
wc.sendInputEvent({ type: "keyUp", keyCode: "Escape" });
Use mouseDown/mouseUp with x, y, button: "left", clickCount: 1 for a click at a
point. The window must hold focus, document.hasFocus() true, or the input and every focus
event go nowhere while activeElement still moves; pass --no-throttle, which warns when
the window lacks focus. Call getCurrentWindow().focus() first; when the user is working in
another app, the window may not keep it, and the check waits for them.
A pop-out is a window of its own: send its input through its own webContents, from
require("@electron/remote").BrowserWindow.getAllWindows(), and focus that window first.
Edit-menu shortcuts — Cmd+Z, Cmd+Shift+Z, Cmd+C, Cmd+V — reach the page as a trusted
keydown but never run the menu's own action, even in a plain <input>. Check that the
keydown arrives unprevented and goes where it should, then run the action as the menu
does: webContents.undo(), .redo(), .copy(), .paste().
Menus bind their keys late
A Menu binds its keys a timer after it shows
(keyboard-scope.md has why that orders
its Scope). A menu closed before that timer fires leaves its keys bound, and they swallow
the next Enter. Between seeing a menu and pressing one of its items, wait one
timer; E2E cases evaluate MENU_READY from packages/e2e/src/page-gestures.ts.
CodeMirror editors
Reach an editor's EditorView from its content element: el.querySelector('.cm-content').cmTile.root.view.
Drive it with view.dispatch({changes, userEvent: 'input.type'}) and read view.state.doc.toString().
A pane mounts its editor after the click that opens it, and a row that holds fixed text has no editor —
poll until the editor exists before you drive it, as annotationEditor in
packages/e2e/src/end-to-end.e2e.ts does.
Stale screenshots
A capture taken right after reload or revealLeaf may show old DOM while the change is already
live. Cross-check against a --code DOM/computed-style query — if they disagree, the DOM query
wins. Re-shoot. A DevTools window open over Obsidian can also steal the capture — close it first.
Confirm which vault answered
A command without a leading vault= goes to the vault that holds the current folder, else to
the focused window — either may belong to another worktree. Pass
vault=<id> as the first argument, and confirm with --code 'app.vault.adapter.basePath' — it must print the
Development Vault path reported by obsidian-vault.ts --help for the worktree you build
from. data.json edits target that same path.
Hidden window
A hidden, minimized, or covered window is throttled: requestAnimationFrame never fires, so a
probe that awaits one never answers; scroll events never dispatch; and screenshots lag one frame
behind the DOM. Pass --no-throttle to every call that probes, scrolls, or captures: it lifts
throttling from the main window and its popouts for that call and puts it back after.
document.visibilityState can still read hidden — judge by frames and events.
Full-scale Fixture data
Build a Stress Build with pnpm fixture stress. Read the current Device Override before you
change it:
packages/scripts/scripts/obsidian-cli.ts \
--code 'app.plugins.plugins.zotlit.services.zoteroPref.dataDirOverride' vault=<id>
Point the live plugin at the absolute .scratch/acceptance-fixture/zotero-data path:
packages/scripts/scripts/obsidian-cli.ts \
--code 'app.plugins.plugins.zotlit.services.zoteroPref.setDataDir("<absolute path>")' vault=<id>
Afterwards, call setDataDir again with the previous value, or null when it was empty. This
restores the vault-scoped Device Override and reconnects the database service.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |