bookmark-research

Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.

Packages

Package details

skill

Install bookmark-research from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:bookmark-research

Package: bookmark-research
Version: 0.5.0-beta.3
Published: Sep 29, 2026
Downloads: 156/mo · 156/wk
Author: kwenxu
License: GPL-3.0-only
Types: skill
Size: 1.7 MB
Dependencies: 0 dependencies · 0 peers

Pi manifest JSON

{
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Bookmark Research

English · 中文

Research your bookmarks with verified web sources. Give it a list of bookmark URLs or a Bookmark Canvas package; it checks every link, searches and reads the web, and writes a cited report you can resume.

Works in Codex, Claude Code, Pi and DSH (DeepSeek Harness).

Installation guide · User guide · Details · npm · Releases

[!NOTE] 0.5.0 is a beta. Report problems on GitHub Issues.

Requirements

Python 3.9+ with SQLite FTS5 (check with bookmark-research doctor)
The CLI of at least one client: Codex, Claude Code, Pi or DSH (DSH also needs pnpm)
Node 18+ for the bookmark-research command; optional on macOS/Linux
No API key is needed to install or to query bookmarks locally

Install

Interactive (macOS, Linux, Windows):

npx bookmark-research install

Pick clients with the arrow keys and Space, confirm the summary, then choose search services and enter API keys. Start a new client session afterwards.

For a permanent bookmark-research command: npm install -g bookmark-research. Without Node (macOS/Linux/WSL): curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash.

One client, no prompts:

Client	Command	Registers with
Codex	`npx bookmark-research install codex --non-interactive`	`codex plugin add`
Claude Code	`npx bookmark-research install claude --scope user --non-interactive`	`claude plugin install`
Pi	`npx bookmark-research install pi --non-interactive`	`pi install`
DSH	`npx bookmark-research install dsh --profile web --non-interactive`	`dsh plugin add`

Windows: the installer writes the detected Python path into each client's MCP config, because Windows often has no working python3. Install Codex with bookmark-research install codex rather than adding the repository to Codex directly. bookmark-research status shows the interpreter in use.

Several at once: npx bookmark-research install claude dsh --profile web --non-interactive. Project scope: --scope project --project /path/to/project (Claude Code, Pi). All options: installation guide.

Ask your agent to install it. Paste this into Codex, Claude Code, Pi or DSH:

Install the Bookmark Research plugin into the client you are running in.

1. Identify your own client: codex, claude, pi or dsh.
2. Run: npx bookmark-research install <client> --non-interactive
   - Claude Code or Pi: add --scope user (or --scope project --project <dir>).
   - DSH: add --profile <profile>; ask me for the profile name.
3. The command prints JSON. Confirm "verified": true and report any "error".
4. Do not ask me for API keys in chat. Tell me to run `bookmark-research setup`
   (or `npx bookmark-research setup`) in my terminal to enter them.
5. Tell me to start a new session so the Skill and MCP tools load.

Configure and API keys

No reinstall is needed. Settings and keys apply to every installed client; start a new client session after changing them.

Task	Command
Menu: configure, check, install, update	`bookmark-research`
Preferences and API keys	`bookmark-research setup`
Installed clients, preferences, storage locations, recent research, key status	`bookmark-research status`
Script preferences	`bookmark-research config show` · `bookmark-research config set --input prefs.json`
Update or verify all clients	`bookmark-research update` · `bookmark-research verify`

Use npx bookmark-research … if the command is not installed globally.

API keys are optional. Enter them in bookmark-research setup (hidden input, checked immediately, saved in a private local file) or set environment variables, which take precedence. Keys are never accepted in chat, command arguments or JSON files.

Variable	Service	Without it
`EXA_API_KEY`	Exa search and page reading	Anonymous use where Exa allows it
`PARALLEL_API_KEY`	Parallel search and page reading	Free anonymous use with lower limits
`TAVILY_API_KEY`	Tavily search fallback and extraction	Keyless mode
`JINA_API_KEY`	Jina search	Jina Reader still reads pages anonymously
`OPENAI_API_KEY`	Optional OpenAI Deep Research runs	Feature off; host-led research still works

Setup also asks where research reports and evidence go: a central folder (default <data dir>/research, path changeable) or beside the bookmark file or folder (falls back to the central folder when that is not possible). This affects new research only; existing tasks stay where they are. It then asks whether finished research should update the Wiki: suggest pages and ask first (default), automatic, or off.

Preferences (research depth, answer language, providers, archiving, output location, Wiki follow-up) can also be changed by asking the agent in a client session; it uses the update_settings tool.

Where data is stored

Nothing is written into your bookmark files or the plugin. The data directory is $BOOKMARK_RESEARCH_DATA_DIR, or ${XDG_DATA_HOME:-~/.local/share}/bookmark-research.

Location	Contents
`research/` (or `<input>.bookmark-research/` beside the input)	One folder per research task: report, sources, evidence, and `work/` for the agent's intermediate files
`research-locations.json`	Where every task folder is, so tasks stay listed after the location setting changes
`knowledge/`	Saved page reads: `sources/` per fetch, `pages/` with each distinct text stored once
`wiki/`	Reviewed knowledge pages and revisions; `index.md` catalog and `log.md` timeline
`index.sqlite3`, `index.sqlite3.sources/`	Bookmark search index and managed snapshots of imported packages
`raw-library.sqlite3`	Rebuildable full-text index for `search_archive`
`${XDG_CONFIG_HOME:-~/.config}/bookmark-research/`	`settings.json` and `credentials.json` (private, owner-only)

What's inside

A bundle of one Skill, one local MCP server, and the remote MCPs and services that server connects to. The client registers only the local MCP.

Layer	Component	Runs as	Setup
Skill	`bookmark-research` and 11 method references, each with a Chinese copy	Loaded by the client	None
Local MCP	`bookmark-research`, 37 tools (below)	Python process started by the client	Installed for you
Remote MCPs, called by the local MCP	Exa (search, page reading), Parallel (search, fallback reading), Tavily (search fallback)	HTTPS, no local process	Optional API keys
HTTP service, called by the local MCP	Jina Reader (fallback reading; search with a key)	HTTPS	Optional `JINA_API_KEY`
Optional client MCPs	Exa Agent, Parallel Task MCP, Tavily Research	Added to your client by you	`bookmark-research setup` shows the steps

Local MCP tools:

Group	Tools
Bookmarks	`sync_package`, `index_status`, `source_history`, `search_bookmarks`, `get_context`
Web	`search_web`, `fetch_web`, `search_archive`, `search_providers`
Research	`research_readiness`, `research_start`, `research_status`, `research_search`, `research_fetch`, `research_source`, `research_record`, `research_inventory`, `research_coverage`, `research_import_evidence`, `research_finish`, `research_route`
Research services (optional)	`research_services`, `research_service_prepare`, `_start`, `_status`, `_result`, `_cancel`, `_attach`, `_import`
Settings	`get_settings`, `update_settings`
Wiki and evaluation	`wiki_write`, `wiki_get`, `wiki_list`, `wiki_search`, `wiki_lint`, `evaluate_research`

Tool descriptions: details.

Installation guide: all install options, updates, ZIP downloads
User guide: first use, the three research modes, languages
Details: data model, research modes, settings, export formats, development checks
Architecture (Chinese)

Originally developed in Bookmark Canvas. License: GPL-3.0.