deso-research

Research and analyze content across decentralized social networks using deso-ag.

deso-ag is a CLI tool that aggregates posts from Farcaster, Lens, Nostr, and Bluesky. It provides search, trending, term extraction, and channel browsing — with a compact output format designed specifically for AI agent consumption.

Prerequisites

Check Installation

which deso-ag || echo "deso-ag not found — install with: npm install -g deso-ag"

If deso-ag is missing, install it:

npm install -g deso-ag

API Keys (Optional)

deso-ag works without any keys — Lens, Nostr, and Bluesky trending all function keyless. For full functionality, these environment variables unlock additional networks:

| Variable | Unlocks | How to Get | |----------|---------|------------| | NEYNAR_API_KEY | Farcaster search + trending | Free at neynar.com | | BLUESKY_IDENTIFIER | Bluesky search | Your handle (e.g. user.bsky.social) | | BLUESKY_APP_PASSWORD | Bluesky search | bsky.app/settings/app-passwords |

Without a key, that network is silently skipped. Everything else works normally.

Check which networks are available before running commands:

echo "Neynar: ${NEYNAR_API_KEY:+set}"
echo "Bluesky ID: ${BLUESKY_IDENTIFIER:+set}"
echo "Bluesky PW: ${BLUESKY_APP_PASSWORD:+set}"

Inform the user which networks will be included based on available keys.

Core Workflows

1. Search for Content

Use search to find posts about a topic. Always use --format compact for agent consumption.

# Basic search across all available networks
deso-ag search "ethereum" --format compact --limit 20

# Multi-word AND search (all terms must match)
deso-ag search "AI crypto" --format compact --limit 15

# Network-specific search
deso-ag search "NFT" --sources farcaster --format compact

# Channel-specific (Farcaster only)
deso-ag search --channel dev --sources farcaster --format compact

# Sort by recency for latest discussions
deso-ag search "base chain" --sort recent --format compact --limit 10

2. Get Trending Content

Use trending to see what's popular right now.

# Trending across all networks
deso-ag trending --format compact --limit 20

# Trending on specific networks
deso-ag trending --sources farcaster,lens --format compact

# Trending over the past week
deso-ag trending --timeframe week --format compact

3. Extract Discussion Terms

Use terms to discover the most-discussed topics, weighted by engagement.

# Top 3 terms per platform, last 24h
deso-ag terms --format json

# Top 5 terms from Farcaster this week
deso-ag terms --top 5 --sources farcaster --timeframe week --format json

# Terms across specific networks
deso-ag terms --top 5 --sources farcaster,nostr --format json

4. Browse Farcaster Channels

deso-ag channels --limit 20

Output Handling

Always use --format compact for search and trending commands. The compact format returns a single JSON object optimized for agent analysis:

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

The score field is pre-computed: likes + reposts×2 + replies. Use it for ranking.

For terms, use --format json which returns structured term frequency data.

Analysis Guidelines

After gathering data, synthesize findings into insights. Never just dump raw JSON to the user.

Summarize the landscape: How many posts found, across which networks, what timeframe
Highlight top content: Surface the highest-engagement posts with author, source, and brief summary
Identify themes: Group related posts and extract common threads
Provide engagement context: What content resonates most and why
Link to originals: Include post URLs so the user can engage directly

Only compare activity across networks if the user specifically asks for a cross-network comparison.

Example Analysis Output

Pulled 42 posts about "AI agents" from Farcaster (15), Lens (12), and Nostr (15) over the last 24h.

**The dominant conversation** is around autonomous agents that can transact onchain
without human approval. @dwr's post (score: 523) kicked this off by demoing an agent
that autonomously allocated funds across DeFi protocols based on real-time yield data.
The replies are split — builders are excited about composability (agents calling other
agents via onchain messages), while others are raising concerns about liability when
an agent makes a bad trade. @jessepollak responded pointing to Base's account
abstraction work as a potential guardrail layer.

**A second thread** is forming around agent-to-agent communication standards. Several
posts reference a draft spec for a messaging protocol between onchain agents. @stani
on Lens (score: 312) argued that without a shared standard, we'll end up with walled
agent ecosystems that can't interoperate — drawing a parallel to early social media
APIs. There's skepticism in the replies about whether standardization is premature
given how fast the space is moving.

**Smaller but notable:** 3-4 posts on Nostr are discussing privacy-preserving agents
that use zk proofs to verify actions without revealing the agent's strategy or
holdings. Early stage but worth watching.

**Key voices to follow on this topic:**
- @dwr (Farcaster) — actively building and demoing agent infra
- @jessepollak (Farcaster) — connecting this to Base ecosystem work
- @stani (Lens) — framing the standards/interop conversation

**Source posts:**
- [dwr's agent demo](https://...) — score: 523
- [stani on agent standards](https://...) — score: 312
- [jessepollak on account abstraction](https://...) — score: 287

Quick Command Reference

| Command | Purpose | Default Sort | Default Format | |---------|---------|-------------|----------------| | search [query] | Find posts about a topic | relevance | markdown | | trending | Popular content right now | engagement | summary | | terms | Top discussion terms | — | — | | channels | Browse Farcaster channels | — | — |

Common Options

| Option | Short | Values | Default | |--------|-------|--------|---------| | --sources | -s | farcaster,lens,nostr,bluesky | all | | --timeframe | -t | 24h, 48h, week | 24h | | --format | -f | json, markdown, summary, compact | varies | | --limit | -l | any positive integer | 25 | | --sort | -o | engagement, recent, relevance | varies | | --channel | -c | channel ID (Farcaster only) | none | | --top | -n | any positive integer (terms only) | 3 |

For the full command reference with output schemas and library usage, see references/command-reference.md.

Error Handling

If deso-ag is not found, install it: npm install -g deso-ag
If no results return for a network, that network's API key is likely missing — inform the user
Nostr can be slow or inconsistent — retry once if it times out
If you hit rate limit errors, let the user know and suggest they run their own infrastructure for heavy usage