Readwise
<EXTREMELY-IMPORTANT>
IRON LAW: Main Chat NEVER Calls Readwise CLI
EVERY READWISE OPERATION MUST GO THROUGH LIBRARIAN. This is not negotiable.
Main chat MUST NOT:
- Run
readwise CLI commands directly
- Run
readwise-custom CLI commands directly
- "Just quickly check" highlights
If you're about to do anything Readwise in main chat, STOP. Spawn a librarian sub-agent instead. </EXTREMELY-IMPORTANT>
Permission Model
| Context |
Readwise CLI |
readwise-custom CLI |
| Main chat |
FORBIDDEN |
FORBIDDEN |
| Librarian sub-agent |
ALLOWED |
ALLOWED |
Red Flag Detection
STOP if you catch yourself thinking:
- "Let me quickly search Readwise..."
- "I'll just run readwise reader-search-documents..."
- "I'll just run readwise-custom search..."
These thoughts in MAIN CHAT = VIOLATION. Delegate instead.
Correct Pattern
User: "Search my Readwise for proxy advisor articles"
MAIN CHAT RESPONSE:
Task(subagent_type="workflows:librarian", prompt="Search Readwise for proxy advisor articles and summarize findings", run_in_background=false)
# Blocking: the answer to the user IS the agent's result, so dispatch synchronously.
NEVER IN MAIN CHAT:
readwise readwise-search-highlights --vector-search-term "proxy advisors"
readwise-custom search "proxy advisors"
Two CLIs
| CLI |
Binary |
Use for |
Official (@readwise/cli) |
readwise |
Search, list, get, save, move, tags, highlights CRUD, export, daily review |
Custom (~/projects/readwise-cli/) |
readwise-custom |
Chat/RAG, ghostreader, file upload (PDF/EPUB), prune, keyword highlight search |
Tag-Based Workflow
<EXTREMELY-IMPORTANT> When user mentions items were added by tag, NEVER use semantic search.
Trigger Phrases
- "we added items tagged X"
- "I thought we added X to NLM"
- "items tagged [tag]"
- "documents with tag [tag]"
Required Workflow
User mentions tagged items or NLM content
│
▼
┌──────────────────────────────────┐
│ 1. CHECK NLM FIRST │ ← MANDATORY
│ nlm list │
│ nlm chat <id> │
└──────────────────────────────────┘
│
Not in NLM?
▼
┌──────────────────────────────────┐
│ 2. USE readwise for tagged items │
│ readwise reader-list-documents│
│ --tag "X" │
│ NOT search! │
└──────────────────────────────────┘
</EXTREMELY-IMPORTANT>
Quick Reference
Official CLI (readwise)
| Need |
Command |
| Semantic search highlights |
readwise readwise-search-highlights --vector-search-term "query" |
| Search documents (hybrid) |
readwise reader-search-documents --query "query" |
| Documents by tag |
readwise reader-list-documents --tag "X" |
| Full document (markdown) |
readwise reader-get-document-details --document-id <id> |
| List all tags |
readwise reader-list-tags |
| Save URL |
readwise reader-create-document --url <url> |
| Move documents |
readwise reader-move-documents --document-ids <id> --location archive |
| Bulk edit metadata |
readwise reader-bulk-edit-document-metadata --documents '[...]' |
| Export library |
readwise reader-export-documents |
| Daily review |
readwise readwise-get-daily-review |
Add --json to any command for machine-readable output.
Custom CLI (readwise-custom)
| Need |
Command |
| RAG chat over highlights |
readwise-custom chat "question" |
| Keyword search highlights |
readwise-custom highlights --search "term" |
| Prune stale docs |
readwise-custom prune |
| Upload PDF/EPUB |
readwise-custom upload <file> |
| Ghostreader |
readwise-custom ghostread summarize <id> |
| Full document (HTML) |
readwise-custom get <id> --html |
Sub-skills with detailed reference:
| Skill |
Purpose |
readwise-search |
Vector + fulltext highlight search |
readwise-docs |
Document CRUD (list, get, save, move, bulk edit, export) |
readwise-chat |
GPT-5.1 RAG chat over highlights (fallback — prefer search + Claude synthesis) |
readwise-prune |
Two-pass stale document cleanup |
Batch Add to NLM (by tag)
uv run python3 "${CLAUDE_SKILL_DIR}"/scripts/readwise_to_nlm.py \
--tag "proxy advisors" --tag "disclosure" \
--notebook <notebook-id>
Add --dry-run to preview. Add --verbose for detailed output.
Anti-Pattern: Never Fetch from Source URL
WRONG: Search Readwise, find document, fetch from original URL (fails for paywalled content).
RIGHT: Search Readwise, get full text FROM READWISE using readwise reader-get-document-details --document-id <id>.
If a document is in Readwise, the full text is already there. Never go back to the source URL.
Additional Resources
Reference Files
references/reader-api.md - Reader API reference (endpoints, pagination, updatedAfter semantics, document fields) for cases the CLI doesn't cover
Scripts
scripts/readwisetonlm.py - Export Readwise documents into a NotebookLM notebookscripts/readwise_prune.py - Direct-API pruning implementation. The sanctioned path is readwise-custom prune (see /readwise-prune), which exposes the same flags; keep this only for API-level work the CLI doesn't expose.
