edwinhu Readwise
EVERY READWISE OPERATION MUST GO THROUGH LIBRARIAN. This is not negotiable.
Main chat MUST NOT:
- Run
readwiseCLI commands directly - Run
readwise-customCLI commands directly - "Just quickly check" highlights
If you're about to do anything Readwise in main chat, STOP. Spawn a librarian sub-agent instead.
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
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! │
└──────────────────────────────────┘
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,updatedAftersemantics, document fields) for cases the CLI doesn't cover
Scripts
scripts/readwise_to_nlm.py- Export Readwise documents into a NotebookLM notebookscripts/readwise_prune.py- Direct-API pruning implementation. The sanctioned path isreadwise-custom prune(see/readwise-prune), which exposes the same flags; keep this only for API-level work the CLI doesn't expose.