logseq-zotero-sync

name	logseq-zotero-sync
version	1.1.0
description	Sync Logseq pages tagged with

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:

1. Query Logseq: Uses Logseq CLI to find all pages with #zotero tag and Zotero URL property
2. Extract Keys: Parses Zotero URLs to get item keys (e.g., "M2QGSQA9")
3. Batch Check: Queries Zotero for items already tagged with in_logseq
4. Smart Diff: Compares lists to find only items that need tagging
5. 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:

1. Gets all Logseq items with Zotero URLs in one query
2. Gets all Zotero items with in_logseq tag in one query
3. Compares the two sets to find the difference
4. 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:

1. Verify credentials exist (check keychain or prompt user to run setup)
2. Identify the graph (ask user or auto-detect)
3. Run the script using Bash tool
4. 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

1. Weekly Sync: Run script weekly to tag new literature notes
2. After Import: Run after importing items to Logseq
3. Curation: Use in_logseq tag in Zotero to see which items are in knowledge base
4. 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