logseq-zotero-sync

name: logseq-zotero-sync version: 1.1.0 description: Sync Logseq pages tagged with #zotero to Zotero by adding 'in_logseq' tag. Uses batch checking for efficiency. Claude Code only.

Logseq to Zotero Sync Skill

Automatically synchronize Logseq literature notes with Zotero by tagging referenced items with in_logseq.

When to Use This Skill

Use this skill when the user wants to:

Tag Zotero items that are referenced in Logseq
Maintain sync between Logseq #zotero pages and Zotero library
Identify which Zotero items have been added to their Logseq knowledge base
Periodically update the in_logseq tag for new literature notes

Keywords: logseq, zotero, sync, tagging, literature notes, bibliography, knowledge management

Overview

This skill syncs Logseq pages tagged with #zotero to Zotero by:

Query Logseq: Uses Logseq CLI to find all pages with #zotero tag and Zotero URL property
Extract Keys: Parses Zotero URLs to get item keys (e.g., "M2QGSQA9")
Batch Check: Queries Zotero for items already tagged with in_logseq
Smart Diff: Compares lists to find only items that need tagging
Tag: Adds in_logseq tag to items that don't have it

Key Feature: Idempotent batch processing - safe to run repeatedly, only tags what's needed.

Requirements

System Requirements

Logseq Desktop app with its bundled logseq CLI on your PATH (ships with current Logseq.app; no npm install needed)
Python 3.10+
macOS (for Keychain credential storage)

Python Dependencies

pip3 install pyzotero keyring

Credentials

Shares credentials with zotero-tag-automation skill via macOS Keychain (service: zotero-tag-automation).

If credentials aren't set up yet (or Zotero returns 403 Invalid key), run the included setup script. It stores the Library ID and API key in the Keychain and verifies the key against Zotero (warning if it lacks write access):

python setup_credentials.py

Usage

Basic Command

cd /Users/niyaro/Documents/Code/logseq-zotero-sync
python sync_logseq_to_zotero.py

Auto-detects the most recent Logseq DB graph.

Specify Graph

python sync_logseq_to_zotero.py "2025-10-26 Logseq DB"

How It Works

Batch Check Approach (Efficient)

Instead of checking each item individually, this script:

Gets all Logseq items with Zotero URLs in one query
Gets all Zotero items with in_logseq tag in one query
Compares the two sets to find the difference
Only makes API calls to tag items that need it

This is much more efficient than checking each item one-by-one, especially as the library grows.

Logseq CLI Query

The script uses the Logseq.app-bundled CLI with these commands:

Graph listing: logseq graph list --output json
Query: logseq query --graph "NAME" --query 'EDN' --output json

The CLI always exits 0 (even on error), so the script checks the JSON status field (must equal "ok"). A harmless Electron codesign line is printed to stderr on every call — the script ignores stderr entirely and only parses stdout.

The datalog query used:

[:find (pull ?b [:block/title {:user.property/ZoteroURL-om1JHnZv [:block/title]}])
 :where [?b :user.property/ZoteroURL-om1JHnZv]]

This finds all pages/blocks with the Zotero URL property and extracts the URLs.

URL Parsing

Zotero URLs have the format:

zotero://select/library/items/M2QGSQA9

The script extracts the item key (M2QGSQA9) using regex pattern matching.

Zotero API

Uses pyzotero to:

Query items by tag: zot.items(tag='in_logseq')
Get item data: zot.item(item_key)
Update tags: zot.update_item(item)

Claude Code Integration

When the user asks to sync Logseq to Zotero or tag items in Zotero based on Logseq:

Verify credentials exist (check keychain or prompt user to run setup)
Identify the graph (ask user or auto-detect)
Run the script using Bash tool
Report results to user with summary

Example Workflow

User: "Tag all my Logseq literature notes in Zotero"

Claude:
1. Checks if credentials are set up
2. Lists available Logseq graphs
3. Asks user to confirm graph name
4. Runs: python sync_logseq_to_zotero.py "GraphName"
5. Shows summary of tagged items

Idempotency

The script is idempotent - running it multiple times has no negative effects:

Items already tagged are skipped (with ⊙ symbol)
Only new items get tagged
No duplicate tags
Safe to run daily/weekly as part of workflow

Output Format

==============================================================
Logseq to Zotero Sync
==============================================================

Querying Logseq graph: 2025-10-26 Logseq DB
Found 14 items in Logseq with Zotero URLs
Querying Zotero for items with 'in_logseq' tag...
Found 10 items already tagged with 'in_logseq'

Found 4 items that need tagging:
  - AA8CFB7Y
  - DUF7Q2B6
  - M2QGSQA9
  - ZTSWUK3C

Tagging 4 items with 'in_logseq'...

[1/4] ✓ AA8CFB7Y: Here we are together
[2/4] ✓ DUF7Q2B6: Reflections on Orthography
[3/4] ✓ M2QGSQA9: Taiwan Archaeology
[4/4] ✓ ZTSWUK3C: Who owns "the culture"

==============================================================
Summary:
  Successful: 4/4
  Failed: 0/4
  Tag: in_logseq
==============================================================

Troubleshooting

"Graph not found"

Problem: Logseq CLI can't find the graph Solutions:

User is using browser version (CLI only works with Desktop)
Run logseq graph list --output json to see available graphs
Make sure Logseq Desktop app is installed

"Credentials not found" or `403 Invalid key`

Problem: No credentials in Keychain, or the stored API key was revoked/regenerated (Zotero returns 403 Invalid key) Solution: Run the setup script to store or replace the credentials (it also verifies the key against Zotero):

python setup_credentials.py

"Command not found: logseq"

Problem: Logseq Desktop app not installed or logseq CLI not on PATH Solution:

Install Logseq Desktop app — the bundled logseq CLI ships with current Logseq.app
Verify: logseq --version

Empty Results from Logseq

Problem: Query returns 0 items but user says items exist Possible causes:

Property name changed (check actual property name in Logseq)
Wrong graph selected
Items are blocks not pages (query targets pages)
Graph is file-based not DB-based (different query needed)

File Structure

/Users/niyaro/Documents/Code/logseq-zotero-sync/
├── sync_logseq_to_zotero.py    # Main script
├── requirements.txt             # Python dependencies
├── README.md                    # User documentation
├── SKILL.md                     # This file (skill documentation)
└── .gitignore                   # Git ignore rules

Related Skills

logseq-cli: Interface with Logseq DB graphs
zotero-tag-automation: Tag items after search
zotero-mcp: Semantic search in Zotero
zotero-mcp-agents: Autonomous Zotero search agents

Use Cases

Weekly Sync: Run script weekly to tag new literature notes
After Import: Run after importing items to Logseq
Curation: Use in_logseq tag in Zotero to see which items are in knowledge base
Workflow Integration: Part of literature review workflow

Future Enhancements

Potential improvements:

Bidirectional sync (remove tag if removed from Logseq)
Support multiple Logseq graphs
Sync other metadata (notes, highlights)
Web interface for manual sync
Scheduled automatic sync

Security

Credentials stored in macOS Keychain (encrypted)
Shares keychain service with zotero-tag-automation
No credentials in code or config files
API key never displayed in output

Notes

Claude Code only: This skill requires CLI access and Python execution
Desktop only: Logseq browser version not supported by CLI
Batch efficient: Uses smart diffing to minimize API calls
Idempotent: Safe to run repeatedly without side effects