Reddit Automation Agent
Hephix-eu/reddit-automation
Aquecimento autônomo de contas Reddit com Claude, Multilogin e Playwright
Ver no GitHubAgent autônomo que aquece contas Reddit seguindo um plano de 14 dias (lurk → comment → post). Integra Claude Code, Multilogin anti-detect, Playwright e SQLite para executar ações humanizadas agendadas via cron, com controle fino por conta.
Instalação
npx convez-ai Hephix-eu/reddit-automation1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Aquecimento gradual de contas Reddit antes de campanhas
- Automação de interações humanizadas em redes sociais
- Gerenciamento de múltiplas contas com estados persistidos em SQLite
Veredito

Solução robusta e sofisticada para automação de contas Reddit, com arquitetura em três camadas (cron → wrapper bash → agent LLM) que otimiza custos e evita spawns desnecessários. Exige conhecimento profundo de DevOps, APIs e orquestração; não é trivial de manter ou adaptar.
README
A tradução para o português deste README ainda está na fila.
reddit-automation
Per-account autonomous Reddit warmup. Each account follows a 14-day plan (lurk → comment → post). A scheduled task fires Claude Code headlessly once per session; the agent drives a Multilogin anti-detect browser via Playwright, performs humanlike actions, logs to SQLite, and reschedules itself.
scheduler (schtasks/at)
│
▼
cli.py run <username>
│
▼ claude -p --append-system-prompt-file AGENT_PROMPT.md
┌────────────────────┐
│ autonomous claude │
│ session (~15 min) │
└────────────────────┘
│
┌────────┴────────┐
▼ ▼
Multilogin API SQLite state
(cloud + launcher) (per-account)
│
▼
Playwright over CDP
│
▼
Reddit (anti-detect Chrome)
Architecture — three layers
The deployment on hephix has three layers, dumb-to-smart:
[cron] → [wrapper.sh] → [docker container running the agent]
dumb gatekeeper smart (LLM)
timer bash Claude
Cron (/etc/cron.d/reddit-agent) fires scripts/run-on-host.sh --all every 15 minutes. It knows nothing about accounts, Reddit, or scheduling — it just rings the bell.
Wrapper (scripts/run-on-host.sh) is the cheap pre-flight check between cron and the agent. Every cron tick, it iterates accounts/*/ and for each account walks a sequence of yes/no checks before deciding to spawn the (expensive) docker container:
- Is
lockpresent and < 45 min old? → skip (currently running). Else stale-lock recovery: force-release the MLX cloud profile lock, then continue. - Is
banned.jsonpresent? → skip - Is
manual.jsonpresent? → skip - Is
pausefile present? → skip - Is
graduated.jsonpresent? → skip - Is
next_run.json.next_run_utcin the past (or file absent)? → spawn. Else skip.
It also self-heals the docker image: if redditagent-image is missing, it rebuilds from Dockerfile.agent and Telegrams a notice.
When all checks pass, the wrapper runs the docker command shown under Sidecar deployment below.
Agent (Claude Code inside the docker container) is the smart, expensive layer. Once spawned, it reads plan.md, queries state.db for the current day, performs the Reddit session via Multilogin + Playwright, writes results back to SQLite, and writes next_run.json with the next scheduled run time.
Why this split? Cron can only fire on a schedule — no per-account intelligence. The agent is expensive to start (~10 s docker overhead + Claude API tokens per session). The wrapper is the cheap (~100 ms bash) gatekeeper that prevents wasted agent spawns when accounts are paused, banned, graduated, or just not due yet.
File layout
cli.py start | run | pause | resume | status | stop | reject | list
AGENT_PROMPT.md system prompt fed to every scheduled session
plan.md canonical 14-day warmup plan (copied per-account)
config.template.json template config for new accounts
lib/
db.py per-account SQLite — one table for sessions/drafts/actions/errors
multilogin.py thin facade over working-with-multilogin skill
browse.py human_scroll() + dwell() — no constant-rhythm loops anywhere
creepjs.py stealth verification (disabled by default — see Known issues)
jitter.py next-session timing: active hours, skip-day, no round minutes
scheduler.py Task Scheduler (Windows) + `at` (Linux) wrappers
tests/
test_creepjs_extract.py regex unit tests
test_browser_integration.py Phase 2: Multilogin→Playwright→Reddit→SQLite, no claude
login_to_reddit.py one-time Reddit login into a fresh profile (manual onboarding)
dismiss_cookies.py one-time cookie consent dismissal
debug_creepjs.py diagnostic for the CreepJS hang issue
accounts/<username>/ (gitignored — per-machine state)
config.json profile_id, folder_id, paths, start_date, etc.
.env MULTILOGIN_EMAIL, MULTILOGIN_PASSWORD, REDDIT_USERNAME, REDDIT_PASSWORD
plan.md working copy of the canonical plan
state.db SQLite — every action ever taken
lock present while a session is running
pause user creates this to halt; agent honors at next wake
screenshots/, recordings/ visual record
Lifecycle in one paragraph
cli start <user> bootstraps an account: prompts for Multilogin email/password/anchor sub, creates a fresh Multilogin profile via API (no proxy, default Mimic desktop flags), writes accounts/<user>/{config.json, .env, plan.md}. You then manually log into Reddit once (tests/login_to_reddit.py <user>) so cookies persist in the profile. After that, every cli run <user> invocation (manual or scheduler-triggered) spawns claude headlessly with AGENT_PROMPT.md as the system prompt. The agent: acquires a lock, computes today's plan day from start_date, opens the Multilogin profile, connects Playwright over CDP, performs humanlike browsing/upvoting/commenting per the plan, writes every action to SQLite as it goes, computes the next-run time via lib/jitter.py, registers a one-shot scheduled task for that time, stops the Multilogin profile via API (never browser.close()), releases the lock, and exits. The pattern is stateless between runs — Notion-style external state is unnecessary because SQLite + Multilogin's notes field carry everything.
Quick start
# 0. Prereqs: Python 3.12+, playwright (+chromium), Multilogin X account, Claude Code CLI
pip install playwright requests
playwright install chromium
# 1. Bootstrap a new account (creates Multilogin profile via API)
python cli.py start HovercraftWeary8654
# 2. One-time onboarding — log into Reddit so cookies persist in the Multilogin profile
python tests/login_to_reddit.py HovercraftWeary8654
python tests/dismiss_cookies.py HovercraftWeary8654 # reject cookie dialog once
# 3. Manual first run so you can watch the agent work
python cli.py run HovercraftWeary8654
# 4. Status / monitoring
python cli.py status HovercraftWeary8654
sqlite3 accounts/HovercraftWeary8654/state.db \
"SELECT executed_at, type, action_type, subreddit FROM actions_log ORDER BY executed_at DESC LIMIT 20"
# 5. After step 3, the agent self-schedules subsequent runs. You don't need to do anything.
Commands
| Command | Effect |
|---|---|
cli.py start <user> | Create Multilogin profile + account folder. Refuses if folder exists. |
cli.py run <user> | Invoke claude headlessly to execute one session. Used by scheduler; also runnable manually. |
cli.py status <user> | Show start date, day, lock/pause state, total karma, pending drafts. |
cli.py pause <user> | Touch pause flag. Agent honors at next wake, reschedules +6h. |
cli.py resume <user> | Remove pause flag. Next scheduled run executes normally. |
cli.py reject <draft_id> | Mark a pending Draft rejected so the agent skips it. 8-char prefix works. |
cli.py stop <user> | Cancel the scheduled task. Account folder + data preserved. |
cli.py list | All accounts present. |
SQLite schema
One table, actions_log, with columns:
id UUID PRIMARY KEY
type Session | Draft | Action | StateSnapshot | Error
status scheduled | pending_review | approved | rejected | submitted | failed | done
day 1-14
action_type browse | upvote | comment | post | reconnaissance | subscribe | save | …
subreddit r/dotnet, …
target_url thread / post URL
draft_content agent's drafted text (for review window)
submitted_content what was actually posted
reasoning why the agent chose this action — debugging gold
session_id groups rows from same browsing session
scheduled_for ISO8601 UTC, for next-run rows
executed_at ISO8601 UTC, auto-filled by helpers
result outcome string (e.g. "karma=+3 url=...")
profile_id Multilogin profile id
name human-readable label
Design choices
- One row per action: chronological audit trail, no joins. ~50-200 rows per 14-day account.
- Inverted approval: drafts default
approvedwith a 30-min submission delay. Override viacli reject. Agent self-flagspending_reviewonly when its own confidence is low (NSFW, off-tone, etc.). - Self-rescheduling: each session writes its own next-run scheduled-task entry, then exits. No daemons.
- Profile per account, no proxy by default: Latvia user → Latvia IP → coherent geo. Add
gate.multilogin.comproxy later if you need a country switch. lib/browse.pyis mandatory: every scroll goes throughhuman_scroll()to avoid the periodic scroll-velocity histogram that anti-bot fingerprints. Inlinefor _ in range: page.mouse.wheel; time.sleepis forbidden.- CLAUDE.md 1-3-1 override: AGENT_PROMPT.md explicitly suspends user-config rules that require human confirmation, since autonomous spawns have no human to ask.
Known issues / gotchas
- CreepJS hangs at "Computing..." on no-proxy profiles — one of Multilogin's stealth patches blocks an API CreepJS awaits. Verification is disabled by default in
config.template.json; re-enable after switching togate.multilogin.comproxy or substituting another verifier (e.g. bot.sannysoft.com). - First profile start downloads the browser core (~30–90s, HTTP 500
CORE_DOWNLOADING_STARTEDuntil done). Retry once after waiting. - Multilogin password is MD5'd before signin —
lib/multilogin.pyhandles this; never send the plain password. - NEVER call
browser.close()from Playwright — it corrupts the Multilogin cookie store. Let thewith sync_playwright()block exit naturally, then call the launcherstopendpoint via API. The facade inlib/multilogin.pydoes this in itsfinally. schtasks /Deletefrom Git Bash fails — Bash mangles/Deleteinto a path. Always go throughlib/scheduler.cancel()which uses Python subprocess (no shell mangling).ls -larequired for any agent listing of account dirs — plainlshides.envand the agent reads its absence as a blocker. Encoded in AGENT_PROMPT.md.- Quota check counts failed sessions — if a session crashes immediately on Day N, the agent won't retry that day. Treats it as a "gap day," plan adapts.
Testing phases
| Phase | What it covers | Run |
|---|---|---|
| 1 | CreepJS regex extraction against synthetic text | python tests/test_creepjs_extract.py |
| 2 | Full middle layer (Multilogin→Playwright→Reddit→SQLite) without claude | python tests/test_browser_integration.py <user> |
| 3 | Agent boot sequence with claude, no Reddit footprint (dry-run) | hand-craft user message overriding actions |
| 4 | Real Day 1 lurk session | python cli.py run <user> |
| 5 | Multi-day observation | inspect SQLite + visit posts logged-out |
Sidecar deployment (hephix / any Linux box running Multilogin in Docker)
When Multilogin runs as a Docker container in bridge mode, its dynamic CDP ports aren't reachable from the host. The agent runs in a sidecar container that shares the network namespace with multilogin:
docker build -f Dockerfile.agent -t redditagent-image .
docker run --rm \
--network container:multilogin \
-v /root/reddit-automation/accounts:/app/accounts \
-v /root/reddit-automation/.env:/app/.env:ro \
-v /root/.claude:/root/.claude \
-e IS_SANDBOX=1 \
redditagent-image \
python3 cli.py run <username>
The --network container:multilogin flag puts the sidecar in multilogin's netns, so 127.0.0.1:<random-cdp-port> resolves directly. No port-forwarding, no --network host (which breaks Mimic's Xvfb via abstract Unix sockets), no host-port-range publishing (which OOMs small boxes with thousands of docker-proxy workers).
/root/.claude is bind-mounted to inherit OAuth credentials. accounts/ is bind-mounted so SQLite state persists. .docker-skill/ is a vendored copy of the working-with-multilogin skill's mlx_client.py — Dockerfile.agent stages it at /root/skills/user/working-with-multilogin/scripts inside the container so lib/multilogin.py's skill discovery resolves.
systemd-run doesn't work in containers (no PID-1 systemd) — the agent falls back to Claude Code's CronCreate for self-rescheduling. A host-side cron that does docker run per scheduled session is the cleaner long-term shape.
Dependencies
- Python 3.12+
playwright(with chromium installed),requestsworking-with-multiloginskill — currently local-only at~/.claude/skills/user/working-with-multilogin(Windows:C:\Users\<u>\Documents\skills\user\working-with-multilogin).lib/multilogin.pyimportsmlx_client.Clientfrom it viasys.path. To run on a fresh machine, copy or rsync the skill folder there.- Multilogin X v12+ (locally during dev; Linux server eventually)
- Claude Code CLI (uses
claude -p --dangerously-skip-permissions --append-system-prompt-file) - SQLite (bundled with Python)
- Windows Task Scheduler (auto) or Linux
at(auto) for self-scheduling