viraloop
OpenClaw AI agent skill for automated TikTok and Instagram carousel growth. Pass any website URL to analyze brand, competitors, colors, value proposition. Generates 6 visually coherent slides and auto-publishes with trending music via upload-post API. Built-in analytics and learning loop. Free tier, no credit card. Larry alternative.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/upload-post--viraloop)HTML
<a href="/listings/upload-post--viraloop"><img src="/api/listings/upload-post--viraloop/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 1. Analyze website node scripts/analyze-web.js https://your-product.com # 2. Generate slides GEMINI_API_KEY="..." bash scripts/generate-slides.sh # 3. Publish UPLOADPOST_TOKEN="..." bash scripts/publish-carousel.sh # 4. Check analytics UPLOADPOST_TOKEN="..." bash scripts/check-analytics.sh 7
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 340 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: viraloop
- description: OpenClaw AI agent skill for automated TikTok and Instagram carousel growth. Analyzes any website URL to extract brand, competitors, value proposition, then generates viral slides with auto-publishing and trending music via upload-post API. Built-in analytics feedback loop.
- metadata: {"clawdbot":{"emoji":"🔄","requires":{"env":["GEMINI_API_KEY","UPLOADPOST_TOKEN"],"bins":["node","jq","uv"]}}}
- ---
- # Viraloop
- Analyze any website and generate a 6-slide carousel for TikTok/Instagram with visual coherence. Posts directly to your feed (no drafts) with auto trending music. Both APIs (Gemini + upload-post.com) have free plans — no credit card needed to start.
- ## Philosophy: Daily Iteration Loop
- The key to growth is **consistency + learning**:
- 1. **Post 1 carousel per day** - Consistency beats virality
- 2. **Track everything** - Every post generates data
- 3. **Learn from data** - What hooks work? What times? What visuals?
- 4. **Iterate and improve** - Each carousel is better than the last
- ```
- Day 1: Post → Analyze → Learn
- Day 2: Post (improved) → Analyze → Learn
- Day 3: Post (better) → Analyze → Learn
- ...
- Day 30: You have 30 data points and a refined strategy
- ```
- The skill maintains a `learnings.json` that accumulates insights across all posts:
- - Best performing hooks
- - Optimal posting times
- - Visual styles that work
- - CTAs that convert
- **This is not a one-shot tool. It's a growth engine.**
- ## Quick Start
- ```bash
- # 1. Full business research
- node {baseDir}/scripts/analyze-web.js https://your-website.com
- # 2. Generate 3 hook variants (SHOCK, CURIOSITY, CONTRADICTION)
- GEMINI_API_KEY="your-key" bash {baseDir}/scripts/generate-hooks.sh
- # 3. Review hooks with vision, pick the best one
- # 4. Generate slides using selected hook type
- GEMINI_API_KEY="your-key" bash {baseDir}/scripts/generate-slides.sh [shock|curiosity|contradiction]
- # 5. Review slides (agent verifies text and quality)
- # Agent uses vision to check each slide
- # 6. Publish to TikTok + Instagram
- UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/publish-carousel.sh
- # 7. Check analytics (after 24-48h)
- UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/check-analytics.sh 7
- # 8. Learn from data for next carousels
- node {baseDir}/scripts/learn-from-analytics.js
- ```
- ## Hook Categories (Visual Novelty System)
- The key to breaking the 1000 views ceiling is **visual novelty in the first slide**. We generate 3 hook types:
- | Type | Goal | Visual Style |
- |------|------|--------------|
- | **SHOCK** | Stop the scroll with impossible/absurd | Surreal, chaotic, "wait what?" |
- | **CURIOSITY** | Create information gap | Mysterious, secrets being revealed |
- | **CONTRADICTION** | Show impossible combination | Relaxed + intense, "how is that possible?" |
- ### Anti-Stock Filter
- All hooks include anti-stock prompting to avoid:
- - Generic stock photo aesthetics
- - Shocked pretty girl trope
- - Typical influencer poses
- - Overused laptop-coffee setups
- - Corporate handshake scenes
- ### Hook Testing Workflow
- 1. Generate 3 variants with `generate-hooks.sh`
- 2. Review with vision, score each 1-5 on novelty
- 3. Kill anything that looks familiar
- 4. Use best hook for carousel
- 5. Track which hook TYPE performs best over time
- ## Image Model
- Uses **gemini-3.1-flash-image-preview** to generate slides.
- - Local script: `{baseDir}/scripts/generate_image.py`
- - Supports image-to-image for visual coherence between slides
- ## Step 1: Full Research (`analyze-web.js`)
- Performs COMPLETE business investigation:
- ### 1. Brand Analysis
- - Brand name (from domain or title)
- - Logo (URL or SVG)
- - CSS colors (background, primary, links, headings)
- - Typography (body font, heading font)
- - Favicon
- ### 2. Content Analysis
- - Headline and tagline
- - All headings (page structure)
- - Features/benefits (title + description)
- - Pricing/plans
- - Testimonials
- - Stats/metrics
- - CTAs
- - Meta tags (title, description, og:image)
- ### 3. Internal Pages
- - Navigates pricing, features, about, testimonials
- - Extracts additional content from each page
- ### 4. Competitor Detection
- - Searches for known competitor mentions in content
- - List of 20+ known SaaS competitors (Buffer, Hootsuite, Later, etc.)
- - Detects "vs", "alternative", "compare" sections
- - No external searches required - all from the website itself
- ### 5. Storytelling
- - Detects business type (SaaS, ecommerce, app)
- - Detects niche (social-media-tools, developer-tools, etc.)
- - Generates hooks based on customer pain points
- - Defines pain points from features
- - Creates transformation narrative (before → after)
- ### 6. Visual Context
- - Brand colors in CSS format
- - Color description for prompts
- - Typography for slides
- - Image themes based on niche
- - Style guide for coherence
- **Output:** `/tmp/carousel/analysis.json`
- ## Step 2: Generate Slides (`generate-slides.sh`)
- Generates 6 slides with visual coherence using image-to-image:
- | Slide | Type | Content |
- |-------|------|---------|
- | 1 | **HOOK** | Question/problem that hooks. Establishes ALL visual style. |
- | 2 | **Problem** | Agitate the pain. "You upload to TikTok... then Instagram..." |
- | 3 | **Agitation** | Competition advancing. Urgency. |
- | 4 | **Solution** | Present the product with its value proposition. |
- | 5 | **Feature** | Main benefit. |
- | 6 | **CTA** | "Link in bio 👆" + call to action. |
- ### Visual Coherence
- - Slide 1 generates the base style (colors, typography, mood)
- - Slides 2-6 use image-to-image with slide 1 as reference
- - Maintains same color palette, fonts, and aesthetic
- ### Prompts per Slide
- Each slide has:
- - **Text:** The main message
- - **Scene:** Detailed visual description for background
- - **Style:** Based on brand analysis
- **Output:**
- - `/tmp/carousel/slide-{1-6}.jpg`
- - `/tmp/carousel/caption.txt`
- ## Step 3: Review with Vision
- After generating, the agent MUST review each slide:
- - ✓ Text is legible and correct
- - ✓ Words are not cut off
- - ✓ Correct spelling
- - ✓ Visual coherence between slides
- - ✓ Acceptable image quality
- If there are errors, regenerate the specific slide.
- ## Image Format
- - **Resolution:** 768x1376 (9:16 vertical ratio)
- - **Format:** JPG (TikTok does NOT accept PNG)
- - **Text:** Large, bold, with shadow for readability
- - **Background:** Scene relevant to the business, not just solid colors
- ## Step 4: Publish to TikTok + Instagram (`publish-carousel.sh`)
- Publishes the carousel to TikTok and Instagram using Upload-Post API.
- ```bash
- UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/publish-carousel.sh
- ```
- **Endpoint:** `POST /api/upload_photos`
- - Docs: https://docs.upload-post.com/api/upload-photo
- **Parameters sent:**
- - `platform[]=tiktok` + `platform[]=instagram`
- - `auto_add_music=true` - Adds music on TikTok automatically
- - `tiktok_title` - Short title (max 90 chars) + hashtags
- - `title` - Full caption for Instagram
- - `privacy_level=PUBLIC_TO_EVERYONE`
- - `media_type=IMAGE` - Photo carousel on Instagram
- - `async_upload=true` - Process in background
- - `photos[]` - The 6 slides JPG
- **⚠️ IMPORTANT Instagram:**
- After publishing, user must go to Instagram and add viral music manually:
- 1. Open Instagram → Profile → The post
- 2. Edit → Add music
- 3. Search for trending/viral song
- **Output:** Saves `request_id` in `post-info.json` for tracking.
- ## Step 5: Analyze Performance (`check-analytics.sh`)
- Gets TikTok and Instagram analytics to see what works.
- ```bash
- UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/check-analytics.sh 7
- ```
- **Endpoints used:**
- 1. **Profile analytics:**
- ```
- GET /api/analytics/{user}?platforms=tiktok
- ```
- → Followers, likes, comments, shares, impressions
- 2. **Total impressions:**
- ```
- GET /api/uploadposts/total-impressions/{user}?platform=tiktok&breakdown=true
- ```
- → Total views per day
- 3. **Per-post analytics:**
- ```
- GET /api/uploadposts/post-analytics/{request_id}
- ```
- → Views, likes, comments for the specific carousel (TikTok + Instagram)
- Docs: https://docs.upload-post.com/api/get-analytics
- ## Step 6: Learn and Improve (`learn-from-analytics.js`)
- Analyzes data and saves learnings for future carousels.
- ```bash
- node {baseDir}/scripts/learn-from-analytics.js
- ```
- **Generates:**
- - `learnings.json` - Accumulated knowledge base
- - Best hooks (those generating most views)
- - Optimal posting times
- - Recommendations for next carousel
- ## Full Flow
- ```bash
- # 1. Research business
- node {baseDir}/scripts/analyze-web.js https://my-product.com
- # 2. Generate slides
- GEMINI_API_KEY="..." bash {baseDir}/scripts/generate-slides.sh
- # 3. Review with vision (agent verifies text)
- # Agent checks each slide image
- # 4. Publish
- UPLOADPOST_TOKEN="..." UPLOADPOST_USER="myuser" bash {baseDir}/scripts/publish-carousel.sh
- # 5. (After a few hours/days) Analyze
- UPLOADPOST_TOKEN="..." UPLOADPOST_USER="myuser" bash {baseDir}/scripts/check-analytics.sh 7
- # 6. Learn for next carousels
- node {baseDir}/scripts/learn-from-analytics.js
- ```
- ## Files
- ```
- {baseDir}/
- ├── SKILL.md # This documentation
- └── scripts/
- ├── analyze-web.js # Full business research
- ├── generate-slides.sh # Generate 6 slides with coherence
- ├── generate_image.py # Gemini 3.1 flash image
- ├── review-slides.js # Prepare slides for review
- ├── publish-carousel.sh # Publish via Upload-Post API
- ├── check-analytics.sh # Get analytics (TikTok + Instagram)
- ├── learn-from-analytics.js # Learn from data
- └── search-competitors.js # Optional external search
- ```
- ## Environment Variables
- | Variable | Description |
- |----------|-------------|
- | `GEMINI_API_KEY` | Google API key for image generation |
- | `UPLOADPOST_TOKEN` | Upload-Post token for publishing and analytics |
- | `UPLOADPOST_USER` | Upload-Post username (required) |
- ## Hook Examples by Niche
- | Niche | Hook Example |
- |-------|--------------|
- | Social Media Tools | "Still posting to social media ONE BY ONE? 😩" |
- | SaaS General | "Still doing this MANUALLY?" |
- | Ecommerce | "The product TikTok won't stop recommending" |
- | App | "The app I wish I'd discovered sooner" |
- | Developer Tools | "The API that's going to change your code" |
- ## Why Viraloop?
- | | Viraloop | Other skills |
- |-|----------|-------|
- | Publishing | Direct to feed | Drafts only |
- | Music | Auto trending music | Manual |
- | Platforms | TikTok + Instagram | Single platform |
- | Research | Auto URL analysis | Manual description |
- | Image coherence | Image-to-image reference | Independent slides |
- | Image gen | Gemini (free tier) | Paid providers |
- | Posting | upload-post.com (free, no CC) | Paid or self-hosted |
- | Text overlay | AI-native (Gemini renders) | External scripts |
- | Prompts | Structured templates | Free-form |
- | Setup | 3 env vars | Complex multi-tool setup |
- ## Notes
- - Analysis extracts competitors from the website content itself (20+ known SaaS)
- - Image-to-image maintains coherence but takes ~20s per slide
- - Generated caption includes niche-relevant hashtags
- - Always review slide text - sometimes it gets cut off
- - `auto_add_music` on TikTok improves engagement
- - Check analytics after 24-48h for meaningful data
- - Learnings accumulate and improve with each published carousel
- - TikTok title max 90 characters (auto-truncated with hashtags)
README.md · README · 127 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Viraloop 🔄
- Generate viral TikTok/Instagram carousel slides from any website automatically.
- ## Philosophy: Daily Iteration
- **Post 1 carousel per day. Learn. Iterate. Grow.**
- ```
- Day 1: Post → Analyze → Learn
- Day 7: 7 data points, patterns emerging
- Day 30: Refined strategy, proven hooks, optimal timing
- ```
- The skill accumulates insights across ALL your posts in `learnings.json`.
- ## Features
- - 🔍 **Full Business Research** - Analyzes brand, features, competitors from any URL
- - 🎨 **AI Image Generation** - Creates 6 visually coherent slides with Gemini (free plan available, no credit card)
- - 📱 **Direct Publishing** - Posts straight to your TikTok feed with auto trending music + Instagram simultaneously. No drafts, no manual steps
- - 💰 **100% Free to Start** - Both APIs (Gemini and [upload-post.com](https://upload-post.com)) have free plans, no credit card required
- - 📊 **Analytics Tracking** - Monitors performance across all posts
- - 🔄 **Learning Loop** - Accumulates insights: best hooks, times, days, styles
- ## Quick Start
- ```bash
- # 1. Analyze website
- node scripts/analyze-web.js https://your-product.com
- # 2. Generate slides
- GEMINI_API_KEY="..." bash scripts/generate-slides.sh
- # 3. Publish
- UPLOADPOST_TOKEN="..." bash scripts/publish-carousel.sh
- # 4. Check analytics
- UPLOADPOST_TOKEN="..." bash scripts/check-analytics.sh 7
- ```
- ## Requirements
- - Node.js 18+
- - Playwright (`npm install playwright && npx playwright install chromium`)
- - uv (Python package runner)
- - jq
- ## Environment Variables
- | Variable | Description |
- |----------|-------------|
- | `GEMINI_API_KEY` | Google API key for Gemini image generation |
- | `UPLOADPOST_TOKEN` | Upload-Post API token |
- | `UPLOADPOST_USER` | Upload-Post username |
- ## Slide Structure
- 1. **Hook** - Attention-grabbing question/problem
- 2. **Problem** - Agitate the pain point
- 3. **Agitation** - Show competition advancing
- 4. **Solution** - Reveal your product
- 5. **Feature** - Key benefit
- 6. **CTA** - Call to action (Link in bio)
- ## Credentials & Security
- ### Required Credentials
- | Credential | Type | Where to Get |
- |------------|------|--------------|
- | `GEMINI_API_KEY` | Environment variable | [Google AI Studio](https://aistudio.google.com/app/apikey) |
- | `UPLOADPOST_TOKEN` | Environment variable | [upload-post.com](https://upload-post.com) → Dashboard → API Keys |
- ### Optional
- | Credential | Type | Description |
- |------------|------|-------------|
- | `UPLOADPOST_USER` | Environment variable | Upload-Post username (not sensitive) |
- ### Security Notes
- - ✅ All credentials are read from environment variables, not stored in files
- - ✅ No API keys are hardcoded in any scripts
- - ✅ Website analysis only reads public web pages (no authentication scraping)
- - ✅ All generated data stays local in `/tmp/carousel/`
- ### Data Flow
- 1. **Website URL** → Analyzed by Playwright (local browser) → `analysis.json`
- 2. **Analysis** → Sent to Gemini API → Returns generated images
- 3. **Images + Caption** → Sent to Upload-Post API → Published to TikTok/Instagram
- 4. **Analytics** → Fetched from Upload-Post API → Stored locally in `learnings.json`
- ### External Services Used
- | Service | Purpose | Data Sent |
- |---------|---------|-----------|
- | Gemini API | Image generation | Text prompts describing slides |
- | Upload-Post API | Publishing + analytics | Images, captions, profile username |
- No sensitive user data is transmitted. Only the content you're publishing.
- ## Why Viraloop?
- Most carousel automation skills post to drafts and require manual publishing. Viraloop is different:
- | Feature | Viraloop | Other skills |
- |---------|----------|-------|
- | Publishing | **Direct to feed** — posts go live instantly | Drafts only — you publish manually |
- | Music | **Auto trending music** via `auto_add_music` | Manual — you add it yourself |
- | Platforms | **TikTok + Instagram in one call** | Single platform, manual cross-post |
- | Research | **Auto-analyzes any URL** — brand, competitors, pricing, features | Manual — you describe your product |
- | Image coherence | **Image-to-image** — slides 2-6 reference slide 1 | Each slide generated independently |
- | Image gen | **Gemini** (free tier available) | Paid image providers required |
- | Posting service | **upload-post.com** — free plan, no credit card | Paid or self-hosted alternatives |
- | Text on images | **AI-native** — text rendered directly | External scripts for text overlay |
- | Prompt quality | **Structured templates** — explicit fields for consistency | Free-form prompts |
- | Setup | **3 env vars** and you're posting | Complex multi-tool setup |
- ## Documentation
- See [SKILL.md](./SKILL.md) for full documentation.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.