How ZotLit connects to Zotero

ZotLit reads your Zotero data through three channels: a direct database read, companion protocol links, and an optional HTTP connection for live updates. ZotLit supports Zotero 9 or later with the ZotLit companion installed.

Reading the Zotero database

While Zotero is running, it holds the database file open exclusively. ZotLit uses a read mode to access it without interfering.

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 may stay in Zotero's write-ahead log and remain hidden from ZotLit.

The companion keeps the main database file current by copying recent writes 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.

The companion

The ZotLit companion is a Zotero add-on that adds context-menu actions inside Zotero. These actions open, update, and import notes. The companion can also push live events to Obsidian. It requires Zotero 9 or later.

The companion keeps the main Zotero database file current for ZotLit. It copies recent changes from the write-ahead log into the main file after Zotero writes data. 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 with no additional configuration beyond installing both plugins. 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

The direct database read needs only the Zotero data directory. It does not require Zotero or the companion to be running. The companion keeps this data current for Immutable source reads. Protocol links and live updates also depend on the companion.

See also