How ZotLit connects to Zotero

ZotLit reads your library from the Zotero database. ZotLit Companion, the Zotero add-on, keeps recent changes available and connects Zotero actions to Obsidian. Live updates provide an optional third connection.

ZotLit supports Zotero 9 or later and requires the Companion.

Reading the Zotero database

Zotero can keep recent changes in a separate database file while it is running. ZotLit uses a read mode to access your library without interfering with Zotero.

The default Auto setting picks the best available mode. It attempts a Reflink clone on macOS and Linux. Auto uses the clone on APFS, Btrfs, and reflink-enabled XFS filesystems. On Windows and other filesystems, such as ext4, Auto falls back to Immutable source. You can override this in Settings.

Reflink clone creates a fast, lightweight snapshot of the database. It sees recent edits, and it is what Auto uses on any macOS or Linux filesystem that supports cloning.

Immutable source reads the database file directly without creating a copy. It is what Auto uses when cloning is unavailable. This mode reads only the main database file. Recent edits can stay in Zotero's separate write-ahead log until Zotero writes them to the main file.

The Companion keeps the main database file current by writing recent changes into it. Its Keep the database file up to date for Obsidian setting is enabled by default. This database checkpoint works without live updates.

Full copy works on any filesystem and sees recent edits. It copies the entire database each time, so it is slower and uses more disk space, especially with large Zotero libraries. Auto never selects this mode; choose it manually if other modes are unavailable.

See the Settings reference for the full option list and descriptions.

Per-device path resolution

The profile directory and data directory are absolute filesystem paths that differ between computers. ZotLit resolves them per device: on each machine, it auto-detects the default Zotero profile (from profiles.ini) and data directory. If Zotero is in a non-default location, you set a Device Override on that device only. The override is stored locally (per vault, per device) and never syncs through the vault, so one computer's path cannot overwrite another's.

For step-by-step instructions, see Use ZotLit on multiple devices.

ZotLit Companion

The Companion adds context-menu actions inside Zotero. These actions open, update, and import notes. The Companion can also push live events to Obsidian.

The Companion keeps the main Zotero database file current for ZotLit. Zotero uses a write-ahead log, or WAL, to hold recent database changes before it writes them to the main file. The Companion tells Zotero to write those changes to the main file after Zotero updates your library. This behavior is enabled by default and works without a server.

The Companion does not run a background server. Its context-menu actions construct obsidian://zotlit/... protocol links and hand them to the operating system, which routes them to Obsidian. This works without any server or network listener enabled in Obsidian.

Protocol links versus live updates

ZotLit uses two transport mechanisms between Zotero and Obsidian. They serve different purposes and can operate independently.

Protocol links (no server required)

When you right-click an item in Zotero and choose a ZotLit action (open note, update note, import), the Companion builds an obsidian://zotlit/... URL and opens it. Obsidian receives the URL and ZotLit handles the action.

Protocol links work out of the box after you install ZotLit and the Companion. They carry a source identifier so ZotLit only processes links originating from the expected Zotero install.

Live updates (server required)

Live updates are a push channel. The Companion sends HTTP notifications to Obsidian as you read and annotate in the Zotero PDF reader, powering the annotation view's reader-following mode. After the Companion finishes its work on the main database file, it also sends a payload-free signal telling ZotLit to refresh, so changes appear right away.

The database checkpoint that writes those changes into the main file works independently of live updates. Live updates only add the signal that tells ZotLit when to refresh.

Live updates require two things enabled:

• In Obsidian: the ZotLit server (a local HTTP listener on port 9091 by default).
• In Zotero: the Companion's notify preference, pointed at the same address.

Both sides carry a source identifier and a protocol version. The server discards requests from unrecognized Zotero installs (source mismatch) and rejects requests with an incompatible protocol version.

How the pieces fit together

ZotLit can read the database while Zotero is closed. Install the Companion in Zotero to keep data current after changes. Protocol links and live updates also depend on the Companion.

See also