reddit-agent

Fast, local-first, multi-account Agentic Reddit Operator built in Rust with Model Context Protocol (MCP) support.

Built in public · Community contributions welcome · Self-hosted · Local-first · Source Available · Commercial resale restricted.

Important Notice: Source-Available Classification

This project is source-available software.

It is not OSI-approved Open Source software.

The source may be viewed, used, modified, forked, and contributed to under the repository license, but commercial resale of the software itself or a substantially equivalent derived offering is restricted.

For full details on permitted personal and business uses, please review LICENSE and LICENSE-FAQ.md.

Related MCP server: reddit_mcp

Highlights

• Multi-Account Isolation: Register, manage, and switch between multiple Reddit profiles with strict data and browser separation.

• Secure Keychain Storage: Authentication tokens and refresh credentials are encrypted via native OS keychains (macOS Keychain, Linux Secret Service, Windows Credential Manager).

• Hybrid Driver Architecture:

  • API Driver: Ultra-fast async HTTP/OAuth2 driver with strict rate-limit backoff and jitter.

  • Browser Driver: Chrome DevTools Protocol (CDP) driver with isolated browser profiles for human-in-the-loop 2FA/login and Reddit UI interaction.

• Fail-Closed Safety & Dry-Run by Default: All mutating actions default to --dry-run and generate cryptographically signed (SHA-256) action plans requiring explicit approval before execution.

• Autonomous Agent Workers:

  • Opportunity Hunter: Scans subreddits for relevant discussions, computes opportunity scores ($0-100$), and drafts disclosure-compliant responses.

  • Community Builder: Evaluates subreddit engagement against healthy community ratios (90/10 content-to-promotion rule) and monitors sentiment.

  • Issue Diagnostician: Analyzes post rejections, shadowbans, and CAPTCHA/security challenges with actionable remediation steps.

• Model Context Protocol (MCP) Server: Connects directly to AI platforms like Claude Desktop, Cursor, and custom agentic frameworks over standard JSON-RPC.

Architecture Overview

                      ┌────────────────────────────────────────┐
                      │             AI Client / LLM            │
                      │  (Claude Desktop, Cursor, Custom Agent)│
                      └──────────────────┬─────────────────────┘
                                         │ JSON-RPC (MCP)
                                         ▼
                      ┌────────────────────────────────────────┐
                      │           reddit-agent (MCP)           │
                      └──────────────────┬─────────────────────┘
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 ▼                                               ▼
    ┌───────────────────────────┐                 ┌───────────────────────────┐
    │     Fast API Driver       │                 │   Isolated Browser Driver │
    │   (OAuth2 / Rustls / HTTP)│                 │   (CDP / Chrome Profiles) │
    └────────────┬──────────────┘                 └─────────────┬─────────────┘
                 │                                              │
                 ▼                                              ▼
    ┌─────────────────────────────────────────────────────────────────────────┐
    │                       Reddit Platform API & Web                         │
    └─────────────────────────────────────────────────────────────────────────┘

Prerequisites

• Rust: 1.80+ (edition 2021)

• Bun: 1.1+ (for TypeScript CLI wrapper and tests)

• Google Chrome / Chromium: For the browser driver

Quickstart

1. Build and Test

# Clone the repository
git clone https://github.com/imMamdouhaboammar/reddit-agent.git
cd reddit-agent

# Run tests
cargo test
bun test

# Build release binary
cargo build --release

2. Configure Environment

Copy the example environment file:

cp .env.example .env

Configure your Reddit API credentials and ensure DRY_RUN=true during initial testing.

3. Usage Examples

# List registered accounts
cargo run -- account list

# Scan for relevant opportunities in a subreddit (dry-run)
cargo run -- agent opportunity --subreddit rust --keywords "web framework"

# Start the Model Context Protocol (MCP) server
cargo run -- mcp

Community & Contributions

Community contributions are welcome! You can report bugs, suggest features, optimize performance, or add new drivers.

• Read CONTRIBUTING.md for local setup, linting, and testing instructions.

• All contributions are made under the Contributor License Agreement (CLA.md). Contributors retain their copyright ownership while granting the project owner a non-exclusive license to maintain and distribute the work.

• Please review our CODE_OF_CONDUCT.md.

Commercial Licensing

Organizations that wish to use reddit-agent beyond the permissions of the public source-available license (e.g., OEM bundling, white-label distribution, or offering a paid hosted managed service) can request a separate commercial license agreement.

Please see COMMERCIAL-LICENSE.md or open an inquiry using the Commercial Licensing Issue Template.

Security

Security vulnerabilities and credential exposure risks should be disclosed privately. Please refer to SECURITY.md for reporting procedures.

Trademarks

The project name reddit-agent, reddit-agentic-cli, logos, and official release identities are protected marks. See TRADEMARKS.md for our trademark policy and permitted factual statements.

License

This project is source-available under Apache License 2.0 with the Commons Clause License Condition v1.0.

You may use, study, modify, fork, and contribute to the software under those terms, including personal and internal business use.

Commercial resale, white-label resale, or offering substantially the same software as a paid product or managed service is restricted.

See:

• LICENSE

• LICENSE-FAQ.md

• COMMERCIAL-LICENSE.md

• THIRD_PARTY_NOTICES.md