| name | bookmark-sync |
| description | Use when Kenneth mentions bookmarks, research queue, bookmark reports, triage, deep dives, or the bookmark pipeline. Trigger phrases include "bookmark sync", "check bookmarks", "review bookmarks", "triage bookmarks", "deep dive", "run bookmark pipeline", "what's pending", "latest reports", "set up bookmarks". Also triggers on references to specific bookmark report files or the bookmarks/ directory. |
Bookmark Sync
Research pipeline that turns X bookmarks into ranked, analyzed research briefs. Supports both automated (daily launchd) and interactive (in-session) workflows.
Powered by the Bookmark Research Engine (bre CLI) — a self-contained Python package that fetches and enriches bookmarks without external CLI dependencies.
Modes
Status
Check pipeline health and pending work. Use this first when Kenneth mentions bookmarks.
Run the status script:
bash {SKILL_DIR}/scripts/status.sh
Then report: last sync date, any errors, pending count, latest triage/report dates.
Fetch
Pull new bookmarks from X into the pending queue. Runs automatically at 5pm daily, but can be triggered manually.
bre fetch -n 50
Or with a specific folder:
bre fetch -n 50 --folder research
Then check what came in and summarize — authors, topics, link count.
Triage
Rank pending bookmarks against Kenneth's research interests. Two sub-modes:
Interactive triage (preferred when Kenneth is present):
- List all pending bookmarks:
bash {SKILL_DIR}/scripts/list-pending.sh
- Rank them by relevance to the research arc (Helm, Sigmund, multi-agent control, RL training, research automation, behavioral measurement, novel architectures, agent tooling)
- Present ranked list in tiers: Tier 1 (deep dive), Tier 2 (skim), Tier 3 (skip)
- Get Kenneth's confirmation or adjustments
- Write approval file to
shoshin-codex/bookmarks/triage/YYYY-MM-DD-approved.md
Automated triage (for unattended runs):
Follow the full triage prompt at automations/bookmark-sync/TRIAGE_PROMPT.md. Read the guidance doc at shoshin-codex/bookmarks/bookmark-review-guidance.md for category definitions and tier heuristics.
Ranking heuristics (from guidance doc):
- 7 categories: multi-agent-orchestration, rl-training-methods, ai-safety-alignment-monitoring, behavioral-measurement-llm-psychology, ai-research-automation, novel-architectures-paradigms, agent-tooling-developer-experience
- Cross-category items get bumped up one tier
- Empirical results > theoretical frameworks
- Novel learning loops > hyperparameter tuning
- Surprising findings > confirmatory results
Deep Dive
Spawn parallel research agents for approved bookmarks. This is the core value — turning bookmarks into analyzed research briefs.
- Read the approval file from
shoshin-codex/bookmarks/triage/
- Read research guidance from
shoshin-codex/bookmarks/bookmark-review-guidance.md
- Check existing reports in
shoshin-codex/bookmarks/reports/ — skip duplicates
- For each approved item, spawn a background Agent with:
- The bookmark source material (tweet text, expanded URLs, fetched content from pending JSON)
- Matched research categories and context from the guidance doc
- Instructions to investigate — prefer arxiv MCP tools for papers (see below)
- Report destination:
shoshin-codex/bookmarks/reports/{slug}.md
Agent prompt template — see references/deepdive-agent-prompt.md for the full template. Key: include pre-fetched content from the pending JSON to save agents a fetch, and paste only the matched category descriptions from the guidance doc (not all 7).
arxiv MCP tools — available as mcp__arxiv__search_papers, mcp__arxiv__download_paper, mcp__arxiv__read_paper:
- When a bookmark links to an arxiv paper, agents should use
download_paper (by arxiv ID) then read_paper to get the full markdown content — much better than WebFetch on arxiv HTML
- When a bookmark mentions a paper without a direct link, use
search_papers with query + category filters to find it
- Papers are cached at
~/.arxiv-mcp-server/papers/ — subsequent reads are instant
- Also available:
mcp__arxiv-latex__ tools for raw LaTeX source when needed
Report format — see references/report-format.md for the full template.
Parallelism: Up to 7 agents concurrently. Use run_in_background=true on all Agent calls.
- As agents complete, summarize findings to Kenneth
- Mark approval file as processed (append
processed: true)
Review
Discuss completed reports and connect findings to active projects.
- Read recent reports from
shoshin-codex/bookmarks/reports/
- Summarize key findings, cross-cutting themes, and project implications
- If Kenneth wants a research queue note for a project, write one to the relevant project's vault directory or repo docs
Setup
Guide through initial setup of the bookmark research engine.
bre setup
This interactively prompts for X cookies, tests authentication, and writes the config file. See references/setup-guide.md for the full walkthrough.
Paths
All vault paths are configurable in bre.yaml under vault_root + vault.*. Defaults shown.
| What | Where | Config key |
|---|
| BRE CLI | bre (installed via uv pip install -e .) | — |
| BRE config | ~/.config/bre/config.yaml | — |
| Pipeline scripts | automations/bookmark-sync/ | — |
| Pending bookmarks | projects/reference/smaug/.state/pending-bookmarks.json | pending_file |
| Vault root | shoshin-codex/ | vault_root |
| Inbox | shoshin-codex/bookmarks/inbox.md | vault.inbox |
| Research guidance | shoshin-codex/bookmarks/bookmark-review-guidance.md | vault.guidance |
| Triage reports | shoshin-codex/bookmarks/triage/ | vault.triage_dir |
| Triage log | shoshin-codex/bookmarks/triage-log.md | vault.triage_log |
| Deep dive reports | shoshin-codex/bookmarks/reports/ | vault.reports_dir |
| Engagement log | shoshin-codex/bookmarks/engagement-log.md | vault.engagement_log |
| Feedback reports | shoshin-codex/bookmarks/feedback/ | vault.feedback_dir |
| Sync log | automations/bookmark-sync/sync.log | |
Rules
- Never write to
garden/ unless Kenneth explicitly says to
- Always use
date command for timestamps — never guess
- Update engagement log when reading reports:
- **read**: \reports/{filename}.md` — {context}`
- Mark approval files as processed after deep dive completes
- Reports use slugified filenames: lowercase, hyphens, no special characters
Gotchas
- X cookie expiry:
auth_token and ct0 rotate periodically. If fetch returns 0 new bookmarks unexpectedly, re-extract cookies from browser DevTools. Run bre setup to update them.
- Query ID rotation: X rotates GraphQL query IDs. If
bre fetch returns 404 errors, run bre refresh-ids to discover current IDs from X's JS bundles.
- Pending JSON path: The state file is at
projects/reference/smaug/.state/pending-bookmarks.json. The reference/ prefix matters.
- WebFetch failures in agents: Some sources (especially X/Twitter) block scraping. Agents should fall back to WebSearch when WebFetch fails. The pre-fetched content from the pending JSON is often sufficient — always include it in the agent prompt to avoid redundant fetches.
- Deep dive agent count: 7 concurrent agents works fine. Don't go much higher — diminishing returns and rate limit risk.
- Approval file format: Must end with
processed: true on its own line to be skipped by subsequent runs. Append it, don't rewrite the file.
- Triage log staleness: If
triage-log.md has an old last_processed date, triage will try to process a large backlog. Check it before running triage on accumulated bookmarks.
- arxiv MCP availability: The arxiv MCP servers (
arxiv, arxiv-latex) are configured in the plugin's .mcp.json but may not be connected in every session. If mcp__arxiv__ tools aren't available, fall back to WebFetch on arxiv abstract pages. The MCP gives full paper text; WebFetch only gets the abstract page HTML.
File Structure
bookmark-sync/
├── SKILL.md # This file
├── scripts/
│ ├── status.sh # Quick pipeline health check
│ └── list-pending.sh # Parse and display pending items
├── references/
│ ├── report-format.md # Deep dive report template
│ ├── deepdive-agent-prompt.md # Agent prompt template
│ ├── pending-json-schema.md # Pending JSON structure
│ └── setup-guide.md # First-time setup walkthrough
└── examples/
└── approval-file.md # Example triage approval
