ii-outreach

Agent-first Reddit and X outreach scaffolding.
Turn a product brief into saved guidance, auth, and reviewable action queues.

ii-outreach is an open-source, agent-first outreach engine for Codex and Claude Code. It turns a product brief into reusable Reddit and X strategy, project-scoped auth, and review-first action queues instead of one-off scripts or prompt dumps.

Quick Start • Commands • Community • Contributing

What You Get

• A symmetric Reddit + X codebase that agents can navigate quickly
• Gitignored per-project runtime state under projects/<slug>/
• Review-first action queues instead of direct-post-by-default automation
• Starter assets and guidance that can be copied into new projects cleanly

Overview

Outreach keeps the tracked repo reusable and pushes live operator state into gitignored projects/<slug>/.

The repo now has a symmetric platform model:

• Reddit code lives under src/reddit/
• X code lives under src/x/
• Starter assets live under starter-assets/
• Per-project runtime state lives under projects/<slug>/reddit/ and projects/<slug>/x/

Why This Exists

• Outreach work should be review-first, not “LLM says post this now.”
• Product context should live in durable project state, not vanish into chat.
• Platform auth, run logs, and staged actions should stay local and isolated per project.
• Codex and Claude Code should be able to understand the repo shape quickly and operate it safely.

Community

• Discord: Intelligent Iterations Discord
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: SECURITY.md

Project Model

Each product gets one gitignored project folder:

projects/<slug>/
  workspace/
  research/
  reddit/
    config.json
    templates.json
    guidance/
    auth/
    output/
      actions/
      logs/
    tracking/
  x/
    config.json
    auth/
    output/
      actions/
      logs/
    tracking/

Use workspace/ for durable product context and research/ for niche notes. Use platform folders for platform-specific config, auth, tracking, and action state.

Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/reddit.txt
pip install -r requirements/x.txt

Bootstrap a project:

export OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics"

mkdir -p \
  "$OUTREACH_PROJECT_DIR/workspace" \
  "$OUTREACH_PROJECT_DIR/research" \
  "$OUTREACH_PROJECT_DIR/reddit/auth" \
  "$OUTREACH_PROJECT_DIR/reddit/guidance" \
  "$OUTREACH_PROJECT_DIR/reddit/output/actions" \
  "$OUTREACH_PROJECT_DIR/reddit/output/logs" \
  "$OUTREACH_PROJECT_DIR/reddit/tracking" \
  "$OUTREACH_PROJECT_DIR/x/auth" \
  "$OUTREACH_PROJECT_DIR/x/output/actions" \
  "$OUTREACH_PROJECT_DIR/x/output/logs" \
  "$OUTREACH_PROJECT_DIR/x/tracking"

cp starter-assets/reddit/config.example.json "$OUTREACH_PROJECT_DIR/reddit/config.json"
cp starter-assets/reddit/templates.example.json "$OUTREACH_PROJECT_DIR/reddit/templates.json"
cp -R starter-assets/reddit/guidance/. "$OUTREACH_PROJECT_DIR/reddit/guidance/"
cp starter-assets/x/config.example.json "$OUTREACH_PROJECT_DIR/x/config.json"
cp starter-assets/x/.env.example "$OUTREACH_PROJECT_DIR/x/.env"

Or start from the tracked scaffold:

cp -R projects/_template/. "$OUTREACH_PROJECT_DIR"

Then ask the operator agent for a real setup, for example:

My product is an ingredient-checking app for health-conscious shoppers.
Target audience is people comparing Yuka, Think Dirty, and clean beauty tools.
Voice should be helpful, specific, low-pressure, and honest that I built it.
Turn this into a Reddit + X outreach setup and stage reviewable actions.

Commands

Reddit:

OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.reddit.setup_auth
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.reddit.main
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.reddit.actions summary
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.reddit.review_ui

X:

OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.x.setup_auth
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.x.main --headless
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.x.actions summary
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.x.main --dispatch-approved

Default runs are review-first. They stage artifacts instead of posting immediately.

Action Queues

Canonical action roots:

• Reddit: projects/<slug>/reddit/output/actions/
• X: projects/<slug>/x/output/actions/

Canonical layout:

output/actions/
  by_status/
    pending_review/
    approved/
    scheduled/
    rejected/
    dispatching/
    dispatched/
    failed/
  by_run/
    <run-id>/
      manifest.json

Use the CLI to inspect queues:

OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.reddit.actions list --status approved
OUTREACH_PROJECT_DIR="$PWD/projects/acme-analytics" python -m src.x.actions list --status approved

Repo Layout

starter-assets/
  reddit/
  x/

requirements/
  reddit.txt
  x.txt

src/
  reddit/
  x/

tests/
  x/

See projects/README.md, AGENTS.md, and docs/platforms/x.md for the repo contract.

Open Source

• License: MIT
• Contributing: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md