SkillAgentSearch skills...

Smaug

Archive your Twitter/X bookmarks to markdown with AI-powered analysis. Supports Claude Code and OpenCode for multi-model flexibility. Like a dragon hoarding treasure, Smaug collects the valuable things you bookmark.

GenerateConvertImprove

Install / Use

/learn @alexknowshtml/Smaug
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Claude Desktop

README

Smaug 🐉

Archive your Twitter/X bookmarks (and/or optionally, likes) to markdown. Automatically.

Like a dragon hoarding treasure, Smaug collects the valuable things you bookmark and like.

Multi-model support: Smaug works with Claude Code (default) and OpenCode, giving you access to a wide range of AI models. Results may vary depending on the model you choose — test carefully and find what works best for your workflow. See AI CLI Integration for setup details.

Contents

  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥
       _____ __  __   _   _   _  ____
      / ____|  \/  | / \ | | | |/ ___|
      \___ \| |\/| |/ _ \| | | | |  _
       ___) | |  | / ___ \ |_| | |_| |
      |____/|_|  |_/_/  \_\___/ \____|

   🐉 The dragon stirs... treasures to hoard!

Quick Start (5 minutes)

# 1. Install bird CLI (Twitter API wrapper)
# See https://github.com/steipete/bird for installation

# 2. Clone and install Smaug
git clone https://github.com/alexknowshtml/smaug
cd smaug
npm install

# 3. Run the setup wizard
npx smaug setup

# 4. Run the full job (fetch + process with Claude)
npx smaug run

The setup wizard will:

  • Create required directories
  • Guide you through getting Twitter credentials
  • Create your config file

Manually Getting Twitter Credentials

Smaug uses the bird CLI which needs your Twitter session cookies.

If you don't want to use the wizard to make it easy, you can manually put your session info into the config.

  1. Copy the example config: 
    cp smaug.config.example.json smaug.config.json
  2. Open Twitter/X in your browser
  3. Open Developer Tools → Application → Cookies
  4. Find and copy these values:
    • auth_token
    • ct0
  5. Add them to your smaug.config.json:
{
  "twitter": {
    "authToken": "your_auth_token_here",
    "ct0": "your_ct0_here"
  }
}

Note: smaug.config.json is gitignored to prevent accidentally committing credentials. The example file is tracked instead.

What Smaug Actually Does

  1. Fetches bookmarks from Twitter/X using the bird CLI (can also fetch likes, or both)
  2. Expands t.co links to reveal actual URLs
  3. Extracts content from linked pages:
    • GitHub repos (via API: stars, description, README)
    • External articles (title, author, content)
    • X/Twitter long-form articles (full content via bird CLI)
    • Quote tweets and reply threads (full context)
  4. Invokes Claude Code to analyze and categorize each tweet
  5. Saves to markdown organized by date with rich context
  6. Files to knowledge library - GitHub repos to knowledge/tools/, articles to knowledge/articles/

Running Manually

# Full job (fetch + process with Claude)
npx smaug run

# Fetch from bookmarks (default)
npx smaug fetch 20

# Fetch ALL bookmarks (paginated - requires bird CLI from git)
npx smaug fetch --all
npx smaug fetch --all --max-pages 5  # Limit to 5 pages

# Fetch from likes instead
npx smaug fetch --source likes

# Fetch from both bookmarks AND likes
npx smaug fetch --source both

# Process already-fetched tweets
npx smaug process

# Force re-process (ignore duplicates)
npx smaug process --force

# Check what's pending
node -e "console.log(require('./.state/pending-bookmarks.json').count)"

Fetching All Bookmarks

By default, Twitter's API returns ~50-70 bookmarks per request. To fetch more, use the --all flag which enables pagination:

npx smaug fetch --all              # Fetch all (up to 10 pages)
npx smaug fetch --all --max-pages 20  # Fetch up to 20 pages

Note: This requires bird CLI built from git (not the npm release). See Troubleshooting for installation instructions.

Cost warning: Processing large bookmark backlogs can consume significant Claude tokens. Each bookmark with content-heavy links (long articles, GitHub READMEs, etc.) adds to the context. Process in batches to control costs:

npx smaug run --limit 50 -t    # Process 50 at a time with token tracking

Use the -t flag to monitor usage. See Token Usage Tracking for cost estimates by model.

Categories

Categories define how different bookmark types are handled. Smaug comes with sensible defaults, but you can customize them in smaug.config.json.

Default Categories

| Category | Matches | Action | Destination | |----------|---------|--------|-------------| | github | github.com | file | ./knowledge/tools/ | | article | medium.com, substack.com, dev.to, blogs | file | ./knowledge/articles/ | | x-article | x.com/i/article/* | file | ./knowledge/articles/ | | tweet | (fallback) | capture | bookmarks.md only |

🔜 Note: Transcription is flagged but not yet automated. PRs welcome!

X/Twitter Long-Form Articles

X articles (x.com/i/article/*) are Twitter's native long-form content format. Smaug extracts the full article text using bird CLI:

  1. Direct extraction: If the bookmarked tweet is the article author's original post, content is extracted directly
  2. Search fallback: If you bookmark someone sharing/quoting an article, Smaug searches for the original author's tweet and extracts the full content from there
  3. Metadata fallback: If search fails, basic metadata (title, description) is captured

Example X article bookmark:

## @joaomdmoura - Lessons From 2 Billion Agentic Workflows
> [Full article content extracted]

- **Tweet:** https://x.com/joaomdmoura/status/123456789
- **Link:** https://x.com/i/article/987654321
- **Filed:** [lessons-from-2-billion-agentic-workflows.md](./knowledge/articles/lessons-from-2-billion-agentic-workflows.md)
- **What:** Deep dive into patterns from scaling CrewAI to billions of agent executions.

Actions

  • file: Create a separate markdown file with rich metadata
  • capture: Add to bookmarks.md only (no separate file)
  • transcribe: Flag for future transcription (auto-transcription coming soon! PRs welcome)

Custom Categories

Add your own categories in smaug.config.json:

{
  "categories": {
    "research": {
      "match": ["arxiv.org", "papers.", "scholar.google"],
      "action": "file",
      "folder": "./knowledge/research",
      "template": "article",
      "description": "Academic papers"
    },
    "newsletter": {
      "match": ["buttondown.email", "beehiiv.com"],
      "action": "file",
      "folder": "./knowledge/newsletters",
      "template": "article",
      "description": "Newsletter issues"
    }
  }
}

Your custom categories merge with the defaults. To override a default, use the same key (e.g., github, article).

Bookmark Folders

If you've organized your Twitter bookmarks into folders, Smaug can preserve that organization as tags. Configure folder IDs mapped to tag names:

{
  "folders": {
    "1234567890": "ai-tools",
    "0987654321": "articles-to-read",
    "1122334455": "research"
  }
}

How to find folder IDs:

  1. Open Twitter/X and go to your bookmarks
  2. Click on a folder
  3. The URL will be https://x.com/i/bookmarks/1234567890 - the number is the folder ID

When folders are configured:

  • Smaug fetches from each folder separately
  • Each bookmark gets tagged with its folder name
  • Tags appear in bookmarks.md entries and knowledge file frontmatter

Note: Twitter's API doesn't return folder membership when fetching all bookmarks at once, so Smaug must fetch each folder individually.

Automation

Run Smaug automatically every 30 minutes:

Option A: PM2 (recommended)

npm install -g pm2
pm2 start "npx smaug run" --cron "*/30 * * * *" --name smaug
pm2 save
pm2 startup    # Start on boot

Option B: Cron

crontab -e
# Add:
*/30 * * * * cd /path/to/smaug && npx smaug run >> smaug.log 2>&1

Option C: systemd

# Create /etc/systemd/system/smaug.service
# See docs/systemd-setup.md for details

Output

bookmarks.md

Your bookmarks organized by date:

# Thursday, January 2, 2026

## @simonw - Gist Host Fork for Rendering GitHub Gists
> I forked the wonderful gistpreview.github.io to create gisthost.github.io

- **Tweet:** https://x.com/simonw/status/123456789
- **Link:** https://gisthost.github.io/
- **Filed:** [gisthost-gist-rendering.md](./knowledge/articles/gisthost-gist-rendering.md)
- **What:** Free GitHub Pages-hosted tool that renders HTML files from Gists.

---

## @tom_doerr - Whisper-Flow Real-time Transcription
> This is amazing - real-time transcription with Whisper

- **Tweet:** https://x.com/tom_doerr/status/987654321
- **Link:** https://github.com/dimastatz/whisper-flow
- **Filed:** [whisper-flow.md](./knowledge/tools/whisper-flow.md)
- **What:** Real-time speech-to-text using OpenAI Whisper with streaming support.

knowledge/tools/*.md

GitHub repos get their own files:

---
title: "whisper-flow"
type: tool
date_added: 2026-01-02
source: "https://github.com/dimastatz/whisper-flow"
tags: [ai, transcription, whisper, streaming]
via: "Twitter bookmark from @tom_doerr"
---

Real-time speech-to-text transcription using OpenAI Whisper...

## Key Features
- Streaming audio input
- Multiple language support
- Low latency output

## Links
- [GitHub](https://github.com/dimastatz/whisper-flow)
- [Original Tweet](https://x.com/tom_doerr/status/987654321)

Configuration

Copy the example config and customize:

cp smaug.config.example.json smaug.config.json

Example `sm

alexknowshtml

View profile

View on GitHub
GitHub Stars783
CategoryCustomer
Updated13h ago
Forks77
alexknowshtml/smaug

Languages

JavaScript

Security Score

95/100

Audited on Mar 30, 2026

No findings