English · 简体中文

Reading Compass

Reading Compass is a local, long-lived AI reading companion for WeRead. It turns verified book metadata, table of contents, reading progress, highlights, and personal notes into spoiler-aware preview maps, post-reading reviews, persistent book conversations, and personalized reading routes.

Capabilities

• A local bookshelf with create, search, edit, and delete workflows
• Spoiler-aware first-read maps that explain structure without revealing the ending
• Post-reading review mode with overview, concepts, argument structure, and critical boundaries
• Persistent AI conversations scoped to each book
• Discussion synthesis, recommendations, connections, unresolved questions, reading order, and close-reading suggestions
• Modern chat controls: copy, edit and resend, retry, stop, and delete
• Local persistence across app rebuilds and computer logins

Requirements

• macOS
• Node.js 20 or later
• Codex desktop or Codex CLI
• The official WeRead skill (weread-skills)
• A WeRead API key beginning with wrk-

Installation

1. Install the official WeRead skill

Recommended CLI installation:

npx skills add gandli/weread-skills

Official package alternative:

Ask Codex to download and install https://cdn.weread.qq.com/skills/weread-skills.zip.

2. Get a WeRead API key

Open the official WeRead Skill page, sign in, and copy the wrk-... API key.

Do not paste the key into a public chat, commit, screenshot, or repository.

3. Install Reading Compass

Install the Skill directly from this repository:

npx skills add Unmoored-Lab/reading-compass

Then ask Codex:

Install this Reading Compass skill, install its local website, and run the health check.

After Codex reloads the skill, the website is available at:

http://127.0.0.1:43127/library.html

4. Connect WeRead

Click Connect WeRead on the bookshelf page and paste the API key there. The app validates the key and stores it in the current macOS user's Keychain.

Privacy

The distributable contains application code, empty data structures, and documentation only. It does not contain the author's bookshelf, highlights, notes, conversations, generated profiles, logs, cookies, or API keys.

User data is stored at:

~/Library/Application Support/Reading Compass/data

Reinstallation updates runtime files without replacing that data directory.

New-user testing sandbox

The Skill includes an isolated same-Mac sandbox for release testing:

/bin/zsh scripts/start-new-user-sandbox.sh

It uses a separate port, app directory, LaunchAgent, simulated Home, and Keychain item. It intentionally starts with an empty bookshelf, no sandbox WeRead skill, and no sandbox API key. Follow references/new-user-testing.md, then remove the environment with scripts/reset-new-user-sandbox.sh.

For final release acceptance, repeat the workflow in a fresh macOS standard account or macOS virtual machine. Containers cannot accurately test LaunchAgent, Keychain, and Codex desktop integration.

Repository contents

• SKILL.md — Codex workflow and triggering rules
• scripts/ — portable macOS installer and health check
• references/ — installation, privacy, troubleshooting, and new-user testing guides
• app/ — sanitized local web runtime with an empty initial store
• evals/ — realistic installation and repair test prompts

Example invocation

Install Reading Compass, guide me through the WeRead dependency and API key setup, then help me add my first book.

License

This repository is released under the MIT License. See LICENSE.