🚀 Getting Started
- Connect Your Channel — Click Sign In with Google on the home page and authorise the required permissions.
- Complete the Setup Wizard — New accounts are guided through EULA acceptance, prompt configuration, and core settings automatically. New
- Start in Simulation Mode — Keep Simulation Mode ON while you review AI replies in the Logs tab. No comments will be posted.
- Go Live — When you're satisfied with reply quality, disable Simulation Mode and enable Auto-Reply to start posting.
- Monitor & Tune — Use the Analytics panel and AI Insight card on the Dashboard to optimise over time.
📋 Onboarding Wizard New — April 2025
First-time users are automatically redirected to a 3-step setup wizard after connecting their Google account.
New Account Flow
- Step 1 — Terms of Service: Read and accept the EULA. Your acceptance is recorded with IP address, user-agent, and timestamp for compliance.
- Step 2 — System Prompt: Write your own prompt or use Magic Generate to have Gemini analyse your channel and create a tailored persona automatically.
- Step 3 — AI Settings: Configure Auto-Reply, Simulation Mode, Top Commenter Engagement, and Video Recommendations in one place.
Existing Account Flow
Accounts that existed before the wizard was deployed see a Verify Your Setup variant — the EULA step is skipped (your prior acceptance is shown), and Steps 2 & 3 let you validate and update your current settings before marking the wizard complete.
🛡 Safety Gates
Comments pass through a layered gate pipeline before any AI reply is generated or posted. Gates run in order; the first gate to trip ends processing for that comment.
GATE 0Self-Reply ProtectionPrevents infinite loops by ignoring comments from your own channel ID.
GATE 0.5Hold / Away ModeIf Hold Mode is active, all processing is paused. Comments are not lost — they will be processed when Hold Mode is turned off.
GATE 0.7Spam & Phishing DetectionScans comment text for known spam patterns (prize scams, URL harvesting, phishing). Configurable. Optional auto-block.
GATE 0.8Manual Reply DetectionBefore claiming a comment, the bot checks the YouTube reply thread for any existing reply from the channel owner. If the tenant already replied manually on YouTube, the AI silently skips the comment — preventing a double-reply. Uses inline reply data (free, no extra API call) for threads up to 20 replies; makes one additional comments.list call for deeper threads.
GATE 1DeduplicationEach unique comment ID is claimed atomically (ON CONFLICT DO NOTHING) across all workers. Prevents double-posting in multi-server deployments.
GATE 1.5Daily User CapEach commenter is limited to 3 AI replies per 24-hour window to prevent over-engagement.
GATE 1.6Conversation Depth LimitLimits how many times the AI replies to the same user on the same video. Default: 3. Configurable in Settings.
GATE 2Short FilterSkips comments under 4 words. Low-effort comments like “nice” rarely benefit from an AI reply.
GATE 2.1Cross-Talk GateSkips comments addressed to another user (e.g. “@John great point!”). Prevents the AI from interrupting side conversations. Configurable.
GATE BLVideo BlacklistIf a video ID is on the Reserved Videos list, comments on that video are skipped for manual reply.
GATE FLFriends Listskip_ai: reserves comment for manual reply. simulate_only: generates an AI draft but does not post (used for subscribed channels).
GATE 3.1Human EmulationRandomly skips ~20% of eligible comments to mimic natural human behaviour.
GATE 3.2Human DelayWaits 30–60 seconds (default) or a custom profile before posting. Configurable via Response Speed Override.
GATE 4AI Safety FilterGemini's safety settings block generation of toxic, hateful, or dangerous content. Replies containing NO_REPLY are suppressed.
GATE 5Circuit BreakerHard stop at 1,000 replies per day across the entire account to protect API quota.
⚡ Core Switches
🤖 Enable Auto-Reply
The master power switch. When OFF, the polling loop skips this channel entirely — no comments are read, no replies generated. When ON, the channel participates in every polling cycle (every 5 minutes).
🧪 Simulation Mode
When ON, the AI generates replies and saves them to Logs with status simulated, but never posts to YouTube. Use this to preview reply quality before going live. You can manually approve and post individual replies from the Logs page.
🏖 Hold / Away Mode
Temporarily pauses all AI replies without disabling the bot. Ideal when you're travelling or unavailable. The timestamp when Hold was activated is displayed in the toggle. All incoming comments queue silently and will be processed when Hold Mode is turned off.
Hold Mode is logged as gate_skipped in your Logs with reason “GATE 0.5 — Hold Mode”.
✍ System Prompt
Defines your AI's personality, tone, and rules. Injected into every reply generation call alongside three live context variables:
{context_str} — the video title and description (tells the AI what the video is about){others_saying_str} — a sample of recent comments on this video (sets the room vibe){comment} — the specific comment being replied to
Example — Tech Channel:
“You are a knowledgeable tech reviewer for {context_str}. The community is saying: {others_saying_str}. Reply to: {comment}. Be helpful, enthusiastic, and mention specs when relevant. Under 35 words.”
✨ Magic Generate
Calls Gemini to analyse your channel title, description, and 5 most recent video titles, then writes a tailored system prompt with all three required variables pre-populated. Available in both the Wizard and the Settings page.
🧪 A/B Prompt Testing
When enabled, each incoming comment randomly uses Prompt A (your main prompt) or Prompt B (a second variant). The prompt_variant column in Logs shows which was used, letting you compare engagement and quality between the two.
🎭 Reply Tone
Appends a tone modifier to your prompt on every call. Options:
- Auto — no modifier; the prompt alone determines tone
- Professional — polished, brand-appropriate
- Casual — relaxed, contractions, conversational
- Enthusiastic — energetic, genuine excitement
- Empathetic — leads with acknowledgement of the person's feelings
- Concise — one or two sentences maximum, no filler
✨ AI Features
🎬 Video Recommendations New — April 2025
When enabled, the AI appends a natural recommendation for one of your other top-performing videos at the end of its reply. The recommended video is selected by finding the most-commented active video in your channel that is not the video being commented on.
First Comment Only (sub-option)
When enabled (default), the recommendation is only added the very first time the AI replies to a given commenter. Returning commenters who have already received a recommendation will not see it again — preventing the suggestion from feeling repetitive.
The recommendation is formatted as a casual inline suggestion (e.g. “You might also enjoy my video on [title]: youtube.com/watch?v=...”) and is logged at the console with a 🎬 prefix.
🧹 Bot-Tell Scrubbing & Reply Naturalness New — April 2025
A two-layer defense against AI replies that publicly signal the account is run by a bot.
Layer 1 — Prompt Hardening
A _ANTI_BOT_PROMPT_INJECTION block is prepended to every Gemini prompt before any other instructions. It explicitly forbids the model from using sycophantic openers (Absolutely!, Great question!, Certainly!), helper-bot phrases (I'd be happy to, Feel free to, Don't hesitate), and self-identifying language (As an AI). The model sees this as a hard constraint, not a suggestion.
Layer 2 — Post-Generation Regex Scrubber
Even if the model slips through (rare but possible), scrub_bot_tells() runs a regex pass on every generated reply before it is stored or posted. Matched phrases are either removed or replaced with natural equivalents. Scrubbed replies are tracked with bot_tell_scrubbed=1 in history and counted in the Analytics Reply Naturalness card.
Reply Naturalness Analytics Card
The Analytics page shows a Reply Naturalness & Edit Rate card that tracks:
- Edit Rate — % of AI-posted replies that the tenant manually changed before posting. Computed by comparing the posted text against the original AI draft.
- Tiers — <15% (Great), 15–30% (Review Recommended), >30% (Action Required) with inline recommendations for each tier.
- Bot-Tells Scrubbed — total count of phrases automatically cleaned before posting.
🧬 Viral Intelligence
A nightly job (3 AM UTC) scans your recent videos and harvests the comments with the highest like counts from your community. These top-liked comments are stored in the viral_vault_yt table and injected as style examples at the top of every AI prompt — teaching the AI your community's tone, vocabulary, and energy without any manual curation.
- Use Preview Harvested Examples in Settings to see what the AI is learning from
- Use Harvest Now to force an immediate refresh outside the nightly cycle
- The toggle in Settings enables or disables injection; the vault itself is always updated
⏱ Response Speed Override
By default the bot waits a random 30–60 seconds before posting (Gate 3.2 human emulation). The Speed Override replaces this with a named profile:
Conservative20–30 min delay. Appears most human. Best for sensitive niches.
Moderate10–20 min delay. Good balance.
Fast5–10 min delay. Higher engagement velocity.
Aggressive1–2 min delay. Maximum speed. Use with caution.
When the override is disabled, the default 30–60 second randomised delay applies.
📅 Scheduling
Restrict bot activity to specific hours and days. When a comment arrives outside the active window it is not processed — it will be picked up in the next polling cycle that falls within the window.
- Fixed — replies only between the exact start and end times you specify
- Randomised (넰30 min) — shifts your start and end times by a random offset each day to avoid detectable patterns
- Active Days — restrict to specific days of the week (Mon–Sun)
- Timezone — all times are interpreted in your chosen timezone
Comments that arrive outside the schedule window are not queued — the polling loop will attempt to process them again on its next run if they fall within the window. Very old comments (beyond the YouTube API's response window) may be missed.
👥 Friends List & Subscriptions
Manage how the AI handles comments from specific users. Each entry has an Action:
skip_aiThe comment is reserved for your manual reply. No AI draft is generated. Appears in Logs as friend_reserved.
simulate_onlyAn AI draft is generated but never auto-posted. You review and approve it from the Logs page via Post Reply. Used automatically for your subscribed channels.
Subscription Sync
Click Sync Subscriptions to import all channels you subscribe to on YouTube. They are added with simulate_only action and source=subscription. Re-syncing updates existing subscription rows without touching manually-added friends.
🔧 Advanced Settings
🔒 Reserved Videos (Video Blacklist)
Enter YouTube video IDs (one per line or comma-separated) to exclude from AI automation. The AI will skip all comments on these videos — they appear in Logs as video_reserved for your manual reply. Useful for sensitive uploads, sponsor videos, or pinned announcements.
🎯 Lead Trigger Words
Comma-separated keywords. When a comment contains any of these words, the AI still replies normally, but the comment is flagged as a 🎯 Lead in Logs so you can follow up personally. Useful for purchase intent signals like price, buy, how much, link, order.
💬 Conversation Depth Limit
Sets how many AI replies are allowed per user per video before Gate 1.6 kicks in. Default is 3. Range: 1–10. Lower values conserve daily credits; higher values support deeper community conversations.
🐟 Spam & Phishing Detection
Gate 0.7 scans each comment for known spam signals: giveaway scams, prize claim language, suspicious shortened URLs, and contact harvesting patterns. When triggered:
- The comment is silently skipped (no pending history row created)
- If Auto-block offenders is enabled, the user is added to
spam_moderation and all future comments from them are ignored
💬 Cross-Talk Gate (Gate 2.1)
Skips comments that open with an @mention directed at another commenter. Prevents the AI from interjecting into side conversations between your viewers.
💳 Billing & Plans
| Plan | Daily Replies | Price |
|---|
| Free / Trial | 30 | Free (14-day trial) |
| Basic | 30 | $99 / mo |
| Enhanced | 50 | $199 / mo |
| Enterprise | 80 | $299 / mo |
Bonus Credits
One-time credit packs add to your daily limit for that day. Credits burn before your plan limit. Available in 10, 20, and 30 reply increments from the Dashboard.
Coupons
Redeem coupon codes from the Dashboard. Each code grants bonus reply credits and is single-use.
🔧 Troubleshooting
Check in order: (1) Simulation Mode is ON — replies are generated but not posted. (2) Hold Mode is active. (3) Auto-Reply or Comment Replies toggle is OFF. (4) A Schedule is set and you're outside the active window. (5) Your daily plan limit has been reached. (6) The EULA has not been accepted — live posting requires acceptance.
This was a known issue with FOR UPDATE NOWAIT lock releases during mid-loop commits and has been resolved. The current system uses an atomic INSERT ... ON CONFLICT DO NOTHING claim pattern ensuring only one worker across all servers can process a given comment ID.
Click the Re-authenticate button in the Dashboard status card. This clears your session and takes you back through the Google OAuth flow to refresh your credentials. Your settings and logs are preserved.
Magic Generate requires a valid YouTube connection to read your channel description and recent video titles. Ensure your credentials are valid first. If the issue persists, write a prompt manually — the three required variables ({context_str}, {others_saying_str}, {comment}) must all be present for full context injection.
The feature requires at least two active videos in your poll state with recorded comment history. Check Settings → Video Recommendations is enabled. If First Comment Only is on, the recommendation will only appear for users the bot hasn't previously replied to.
This is resolved by Gate 0.8 (Manual Reply Detection) — deployed April 2025. Before claiming any comment, the bot now checks the live YouTube reply thread for an existing reply from your channel. If one is found, the comment is silently skipped. If you're still seeing this, ensure your deployment is running the latest version. Note: Gate 0.8 only catches replies to that specific comment thread — if you replied to a different comment on the same video, the bot may still reply to the original unreplied comment.
📋 Changelog
Apr 2025Bot-Tell Scrubbing & Reply Naturalness — Two-layer anti-bot defense: hardened prompt injection + post-generation regex scrubber. Analytics Reply Naturalness card with edit-rate gauge, tiered recommendations, and bot-tell scrub counter. Tenant edit tracking (edited_by_tenant, original_ai_reply) added to history.
Apr 2025Gate 0.8 — Manual Reply Detection — Bot now checks live YouTube reply threads before claiming a comment; silently skips any thread the tenant already replied to manually, preventing AI double-replies on top of manual responses.
Apr 2025Onboarding Wizard — 3-step guided setup for new and existing accounts; EULA acceptance stamped with IP/UA/version; existing users see settings-validation flow.
Apr 2025Top Commenter Engagement — AI injects personalised instructions for top-25 commenters; collapsible ranked table in Settings; /api/top_commenters endpoint.
Apr 2025Video Recommendations — AI appends top-performing video suggestion to replies; First Comment Only sub-option; per-user dedup query.
Mar 2025AI Insight Cache — Gemini insights pre-warmed twice daily (6 AM & 6 PM UTC); proactive background refresh for stale channels.
Mar 2025Spam & Phishing Detection (Gate 0.7) — pattern-based gate with optional auto-block; Cross-Talk Gate (Gate 2.1) added.
Feb 2025Friends List Pagination — search, pagination, and edit/remove controls; Subscription Sync with simulate_only action.
Feb 2025Fernet Credential Encryption — all OAuth tokens encrypted at rest; transparent legacy plaintext migration on next credential refresh.
Jan 2025Multi-worker Atomic Claim Pipeline — ON CONFLICT DO NOTHING dedup closes triple-posting race window across all workers and servers.
Jan 2025Viral Intelligence Engine — nightly harvest of top-liked comments injected as style examples into every prompt.
Dec 2024A/B Prompt Testing, Reply Tone picker, Conversation Depth Limit, Lead Trigger Words, Reserved Videos added.
Nov 2024Hold / Away Mode, Response Speed Override, Scheduling (fixed & randomised) added.
Oct 2024Initial release — YouTube comment polling, Gemini AI reply generation, Simulation Mode, PayPal billing, daily usage caps.