deso-ag

Decentralized Social Aggregator - A CLI tool and library for aggregating posts from decentralized social protocols.

Search and view content across Farcaster, Lens, Nostr, and Bluesky from your terminal or programmatically from your agent.

Installation

npm install deso-ag

Or to use as a CLI globally:

npm install -g deso-ag

From Source

git clone https://github.com/mtple/deso-ag
cd deso-ag
pnpm install

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | NEYNAR_API_KEY | For Farcaster | None — Farcaster is skipped | Neynar API key. Get one free at neynar.com | | BLUESKY_IDENTIFIER | For Bluesky search | None — Bluesky search is skipped, trending still works | Your Bluesky handle (e.g. user.bsky.social) | | BLUESKY_APP_PASSWORD | For Bluesky search | None — Bluesky search is skipped, trending still works | App password from bsky.app/settings/app-passwords |

Lens, Nostr, and Bluesky trending work without any keys. Bluesky search requires authentication.

Add keys to your shell profile so they persist across sessions:

# Add to ~/.zshrc or ~/.bashrc
export NEYNAR_API_KEY=your-key-here
export BLUESKY_IDENTIFIER=your-handle.bsky.social
export BLUESKY_APP_PASSWORD=your-app-password

Without a key, the respective source/feature is skipped and everything else still works normally.

Commands

search [query]

Search for posts across networks.

deso-ag search "ethereum"
deso-ag search "AI" --sources nostr
deso-ag search --channel dev --sources farcaster

Multi-word queries use AND semantics (all terms must match):

deso-ag search "AI crypto"       # posts must contain both "AI" and "crypto"
deso-ag search "ethereum layer2"

trending

Get trending posts from all networks.

deso-ag trending
deso-ag trending --sources farcaster,lens
deso-ag trending --format json --limit 50

terms

Extract top discussion terms from posts via engagement-weighted frequency analysis.

deso-ag terms                              # top 3 terms per platform, last 24h
deso-ag terms -n 5 -s farcaster -t week    # top 5, Farcaster only, last week
deso-ag terms -f json                      # machine-readable output

channels

Browse popular Farcaster channels.

deso-ag channels
deso-ag channels --limit 50

Options

All commands accept the following options (except where noted):

| Option | Description | Values | Default | |--------|-------------|--------|---------| | -s, --sources | Networks to query | farcaster, lens, nostr, bluesky (comma-separated) | farcaster,lens,nostr,bluesky (all) | | -t, --timeframe | Time range for posts | 24h, 48h, week | 24h | | -c, --channel | Filter by channel | Any channel ID (Farcaster only) | none | | -f, --format | Output format | json, markdown, summary, compact | markdown (search), summary (trending) | | -l, --limit | Max posts per source | Any positive integer | 25 | | -o, --sort | Sort order | engagement, recent, relevance | relevance (search), engagement (trending) | | -n, --top | Top terms per source | Any positive integer (terms command only) | 3 |

Output Formats

• markdown - Human-readable with headers, author info, and engagement stats. Default for search.
• summary - Condensed overview with post counts and top content. Default for trending.
• json - Raw JSON array of post objects. Good for piping to other tools.
• compact - Single JSON object with metadata envelope, engagement scores, and full content. Designed for AI agents.

Sort Orders

• engagement - By score (likes + reposts*2 + replies). Best for discovering high-signal content. Default for trending.
• recent - By timestamp descending. Best for monitoring.
• relevance - Query-matching posts first, then by engagement. Default for search.

Agent Usage

deso-ag is designed for consumption by AI agents doing research across decentralized social networks.

Compact Output Format

The compact format returns a single JSON object with a metadata envelope, pre-computed engagement scores, full untruncated content, and source health info:

deso-ag trending -f compact -l 10
deso-ag search "AI agents" -f compact -l 10

Output shape:

{
  "meta": {
    "query": "AI agents",
    "totalPosts": 42,
    "sources": [
      {"name": "farcaster", "count": 15},
      {"name": "lens", "count": 12},
      {"name": "nostr", "count": 15}
    ],
    "timeframe": "24h",
    "fetchedAt": "2025-01-01T00:00:00.000Z"
  },
  "posts": [
    {
      "id": "...",
      "source": "farcaster",
      "author": "dwr",
      "content": "full untruncated content...",
      "timestamp": "2025-01-01T00:00:00.000Z",
      "url": "https://...",
      "score": 523,
      "engagement": {"likes": 400, "reposts": 50, "replies": 23},
      "tags": []
    }
  ]
}

Library Import

For agents that run in Node.js, import aggregate() directly instead of shelling out:

import { aggregate } from 'deso-ag';

const result = await aggregate({
  sources: ['farcaster', 'lens', 'nostr', 'bluesky'],
  timeframe: '24h',
  query: 'AI agents',
  limit: 20,
  sort: 'relevance',
});

console.log(result.meta.totalPosts);
for (const post of result.posts) {
  console.log(`[${post.source}] @${post.author.username}: ${post.content.slice(0, 100)}`);
}

The terms() function extracts top discussion terms:

import { terms } from 'deso-ag';

const result = await terms({
  sources: ['farcaster', 'nostr'],
  timeframe: '24h',
  limit: 20,
}, 5); // top 5 terms

for (const st of result.bySource) {
  console.log(`${st.source}: ${st.terms.map(t => t.token).join(', ')}`);
}

Individual fetchers and utilities are also exported:

import { fetchFarcaster, fetchLens, fetchNostr, fetchBluesky, computeEngagementScore, matchesQuery, extractTerms } from 'deso-ag';

Examples

# Get a quick summary of trending content
deso-ag trending -f summary -l 20

# Agent-optimized compact output sorted by engagement
deso-ag trending -f compact -o engagement -l 10

# Search for AI discussions on Lens only
deso-ag search "AI" -s lens -f json

# Multi-word search with compact output
deso-ag search "AI crypto" -f compact -l 10

# Browse the /dev channel on Farcaster
deso-ag search --channel dev -s farcaster

# Export trending Nostr posts as JSON
deso-ag trending -s nostr -f json > nostr-trending.json

# Search Bluesky for discussions
deso-ag search "ethereum" -s bluesky -l 5

# Trending on Bluesky
deso-ag trending -s bluesky -f summary

# Sort search results by recency
deso-ag search "ethereum" -o recent -f json -l 5

# Top 5 terms across all networks this week
deso-ag terms -n 5 -t week

# Terms from Farcaster and Nostr as JSON
deso-ag terms -f json -s farcaster,nostr -l 10

Supported Networks

| Network | API | Auth | |---------|-----|------| | Farcaster | Neynar API - trending feed and full-text search | NEYNAR_API_KEY required | | Lens | Lens V3 GraphQL API - server-side search, recent posts | None | | Nostr | nostr.wine trending API + public relays (relay.damus.io, nos.lol, relay.snort.social) | None | | Bluesky | AT Protocol API - public "What's Hot" feed for trending, authenticated search via app.bsky.feed.searchPosts | None (trending), BLUESKY_IDENTIFIER + BLUESKY_APP_PASSWORD (search) |

All networks return engagement stats (likes, reposts, replies) and support timeframe filtering.

Limitations

• Farcaster: Requires NEYNAR_API_KEY. Without it, Farcaster is skipped.
• Nostr: Relay responses can be slow or inconsistent depending on network conditions.
• Rate limits: All APIs have rate limits. For heavy usage, consider running your own infrastructure.

Development

pnpm build    # Build for production
pnpm test     # Run tests

Tech Stack

• TypeScript
• Commander.js for CLI
• nostr-tools for Nostr protocol
• Native fetch for HTTP requests

License

MIT

Author

Matt Lee