╔══════════════════════════════════════════════════════════════════╗
║                                                                  ║
║    ██████╗ ███████╗███████╗██████╗ ███████╗██████╗               ║
║    ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██╔══██╗              ║
║    ██████╔╝█████╗  █████╗  ██████╔╝█████╗  ██████╔╝              ║
║    ██╔══██╗██╔══╝  ██╔══╝  ██╔═══╝ ██╔══╝  ██╔══██╗              ║
║    ██████╔╝███████╗███████╗██║     ███████╗██║  ██║              ║
║    ╚═════╝ ╚══════╝╚══════╝╚═╝     ╚══════╝╚═╝  ╚═╝              ║
║                                                                  ║
║    ███████╗ ██████╗ ██████╗ ██╗   ██╗████████╗                   ║
║    ██╔════╝██╔════╝██╔═══██╗██║   ██║╚══██╔══╝                   ║
║    ███████╗██║     ██║   ██║██║   ██║   ██║                      ║
║    ╚════██║██║     ██║   ██║██║   ██║   ██║                      ║
║    ███████║╚██████╗╚██████╔╝╚██████╔╝   ██║                      ║
║    ╚══════╝ ╚═════╝ ╚═════╝  ╚═════╝    ╚═╝                      ║
║                                                                  ║
║    Automated scouting for the Beeper ecosystem                   ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

Overview

Beeper Scout is an automated scouting system that collects findings from multiple sources (Matrix rooms, GitHub, Reddit), stores them in an organized structure, generates reports, and provides discovery/analysis tools.

Key Features

• Multi-Source Collection - Matrix rooms via Beeper MCP, GitHub repos/issues, Reddit posts
• Three Operational Modes - CLI, Claude Code skill, or background daemon
• AI-Powered Analysis - Claude API for categorization and enrichment
• Hybrid Storage - Source-based archives with aggregated cross-source views
• Automated Reports - Weekly/monthly digests in Markdown and JSON

Quick Start

# Install dependencies
pnpm install

# Check configured sources
pnpm run sources

# Run scouting operation
pnpm run scout

# Generate report
pnpm run report

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     BEEPER SCOUT MODES                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   DIRECT CLI    │  │  CLAUDE CODE    │  │   BACKGROUND    │ │
│  │                 │  │     SKILL       │  │     DAEMON      │ │
│  ├─────────────────┤  ├─────────────────┤  ├─────────────────┤ │
│  │ • Manual runs   │  │ • /scout slash  │  │ • systemd svc   │ │
│  │ • Scripts       │  │ • Interactive   │  │ • Scheduled     │ │
│  │ • CI/CD         │  │ • Context-aware │  │ • Continuous    │ │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘ │
│           │                    │                    │          │
│           └────────────────────┼────────────────────┘          │
│                                ▼                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   CORE SCOUT ENGINE                      │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │   │
│  │  │ Source   │  │ Analysis │  │ Storage  │  │ Report   │ │   │
│  │  │ Adapters │→ │ Engine   │→ │ Layer    │→ │Generator │ │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘ │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Source Priority

Priority	Source	Description
1	Beeper MCP	Matrix rooms via Desktop API (localhost:23373)
2	GitHub	Repos, issues, releases for beeper/, beeper-community/
3	Reddit	r/beeper and related subreddits
4	Additional Rooms	Beeper Self-Hosted Bridges, Beeper SDK

CLI Commands

# Scout Operations
beeper-scout scout                    # Run all sources
beeper-scout scout --source matrix    # Single source
beeper-scout scout --room <id>        # Specific room
beeper-scout scout --deep             # Full historical scan

# Analysis
beeper-scout analyze                  # Run analysis on collected data
beeper-scout analyze --topic <name>   # Topic-specific analysis
beeper-scout trends                   # Show trending topics

# Reports
beeper-scout report                   # Generate all reports
beeper-scout report weekly            # Weekly summary
beeper-scout status                   # Show collection status

# Data Management
beeper-scout sources                  # List configured sources
beeper-scout export --format csv      # Export data
beeper-scout publish                  # Push to GitHub

Claude Code Integration

Use the /scout skill in Claude Code for conversational scouting:

/scout                          # Scout all configured sources
/scout beeper-dev-community     # Scout specific room
/scout trends                   # Show trending topics

See skills/scout/SKILL.md for full documentation.

Project Structure

beeper-scout/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── daemon.ts           # Background daemon
│   ├── adapters/           # Source adapters
│   │   ├── types.ts        # Common interfaces
│   │   ├── beeper-mcp.ts   # Beeper Desktop API
│   │   ├── github.ts       # GitHub adapter
│   │   └── reddit.ts       # Reddit adapter
│   ├── analysis/           # Analysis engine
│   ├── storage/            # Storage layer
│   └── reports/            # Report generators
├── config/
│   ├── default.json        # Main configuration
│   └── rooms.json          # Matrix room definitions
├── data/
│   ├── sources/            # Source-based archives
│   │   └── beeper-dev-community/
│   ├── aggregated/         # Cross-source views
│   └── reports/            # Generated reports
├── skills/
│   └── scout/              # Claude Code skill
│       └── SKILL.md
└── docs/
    └── plans/              # Design documents

Configuration

Main Configuration (config/default.json)

{
  "sources": {
    "beeper-mcp": {
      "enabled": true,
      "baseUrl": "http://localhost:23373",
      "priority": 1
    },
    "github": {
      "enabled": true,
      "priority": 2,
      "repos": ["beeper/*", "beeper-community/*"]
    },
    "reddit": {
      "enabled": true,
      "priority": 3,
      "subreddits": ["beeper"]
    }
  }
}

Room Configuration (config/rooms.json)

{
  "rooms": [
    {
      "id": "!VRvJRVNZDbRuKAsKvK:beeper.com",
      "name": "Beeper Developer Community",
      "priority": 1,
      "topics": ["api", "mcp", "bridges"]
    }
  ]
}

Beeper Ecosystem

Repository	Description
beeper-pulse	Real-time ecosystem metrics and health monitoring
beeper-scout	Discovery and curation automation (this repo)
awesome-beeper	Curated list of Beeper resources
update-beeper	Arch Linux Beeper updater

Latest Scout Reports

See the data/ directory for the latest findings:

• Beeper Developer Community - Summary
• Beeper Developer Community - Full Report

Development

Prerequisites

• Node.js 20+
• pnpm 8+
• Beeper Desktop (for MCP source)

Setup

# Install dependencies
pnpm install

# Run type checking
pnpm typecheck

# Build
pnpm build

# Run tests
pnpm test

Environment Variables

Variable	Description	Required
GITHUB_TOKEN	GitHub personal access token	For GitHub source
ANTHROPIC_API_KEY	Claude API key for AI analysis	For AI features

License

MIT

---

Built with 🔍 by the Beeper community