X Bookmarks Digest

Workflow — Step by Step

Step 1: Check Rate Limit

Read the state file to check when the last run was:

cat {baseDir}/state.json 2>/dev/null || echo '{"last_bookmark_id": null, "last_run_ts": null, "processed_count": 0}'

If last_run_ts is less than 1 hour ago, warn the user:

"Last digest was run at {time}. Free tier allows max 1 run/hour. Use --force to override."

Only proceed if:

• No previous run exists, OR
• More than 1 hour has elapsed, OR
• User explicitly says to force/override

Step 2: Fetch Bookmarks

Run the fetch script to get new bookmarks:

python3 {baseDir}/scripts/fetch_bookmarks.py --count 50

Options:

• --count N — number of bookmarks to fetch (default 50, max 100)
• --force — skip rate limit check
• --all — fetch all (ignore last-checked ID, reprocess everything)

Output: JSON array of bookmark objects to stdout. Side effect: Updates {baseDir}/state.json with new watermark.

If the output is empty or [], report: "No new bookmarks since last check."

Step 3: Analyse Bookmarks

Pipe the fetched bookmarks through the analyser:

python3 {baseDir}/scripts/fetch_bookmarks.py --count 50 | python3 {baseDir}/scripts/analyse_bookmarks.py

Or if you saved fetch output to a variable, pass it via file:

python3 {baseDir}/scripts/analyse_bookmarks.py --file /tmp/bookmarks.json

Output: Structured JSON with categories and relevance scores:

{
  "summary": {"total": 50, "new": 12, "high": 4, "medium": 5, "low": 3},
  "bookmarks": [
    {
      "id": "123",
      "text": "...",
      "author": "@user",
      "category": "tool",
      "relevance": 5,
      "urls": ["https://github.com/..."],
      "github_repos": ["user/repo"],
      "keywords": ["python", "cli"]
    }
  ]
}

Step 4: Generate Digest

Using the structured analysis output, write a digest following this format:

# X Bookmarks Digest — {date}

## Summary
- {total} bookmarks checked, {new} new since last run
- {high} high-value, {medium} medium, {low} low

## High Value (relevance 4-5)

### [{category}] {title or key topic}
@{author}: "{first 100 chars of text}..."
- URL: {extracted url}
- Why: {1-line explanation of value}
- Action: {specific next step}

## Medium Value (relevance 3)
{same format, briefer}

## Proposed Actions
1. [ ] {action 1}
2. [ ] {action 2}
...

Step 5: Decide on Actions

For each high-value bookmark, decide:

Ask the user which actions to execute. Do not auto-execute without confirmation.

Step 6: Update State

After successful digest, verify state was updated:

cat {baseDir}/state.json

Should show updated last_bookmark_id and last_run_ts.

Error Handling

Test Commands

Quick test (dry run, no state update):

# Test xurl auth
xurl whoami

# Test fetch (small batch)
python3 {baseDir}/scripts/fetch_bookmarks.py --count 5 --force

# Test analyse (with sample data)
echo '[{"id":"1","text":"Check out this amazing CLI tool https://github.com/user/repo","author_username":"devuser","created_at":"2026-03-19T10:00:00Z"}]' | python3 {baseDir}/scripts/analyse_bookmarks.py

# Full pipeline test
python3 {baseDir}/scripts/fetch_bookmarks.py --count 10 --force | python3 {baseDir}/scripts/analyse_bookmarks.py

Or just say: "digest x bookmarks" to run the full workflow.

Configuration

All config is in {baseDir}/state.json:

• last_bookmark_id — watermark for incremental fetches
• last_run_ts — rate limit enforcement
• processed_count — running total of processed bookmarks

No additional configuration files needed. xurl manages its own auth.