marketing-agent
An agent that learns which TikTok formats earn organic views and turns them into product videos.
Three modules in one repo, one SQLite store, one CLI (mkt):
| module | what it does | status |
|---|
research/ | Concept radar. Scrapes public TikTok hashtag pages in a real Chrome (no login, no API key), stores every video and its stats over time, ranks by an early-traction score, clusters videos into reusable concepts with an LLM. Polls any public video URL for views/likes/shares (scoreboard input). | working |
classifier/ | Watches a video (frames every 3s + transcript + caption + sound) and returns strict JSON tags: hook type and text, visual style, pacing, concept, product-by-5s, demo score. gpt-5.4 by default (gpt-5.4-mini flips labels between runs). | working |
video/ | Remixes a concept to a product (10-20 scripts, 1-3s hook, product on screen by 5s, scored for demoability), generates clips with Seedance 2.5 on fal.ai (Seedance 2.0 fast on Replicate as the cheap fallback), and cuts a captioned 1080x1920 H.264 with ffmpeg. --provider stub renders colour cards so the pipeline runs with no key. | working, needs FAL_KEY for real clips |
Not in scope by design: automated account warming, bot-run posting accounts, posting via API. Real
each clip is posted from a real account only after a person presses Post on it; the agent runs
everything around that.
Two kinds of video
Every video in the store is in exactly one of two groups, and they are never pooled:
- Reference: other people's videos scraped from niche hashtags for research. They feed the
radar, concept clustering, the cohort panel and the controlled findings: what the market
rewards right now.
- Ours: posts from our registered accounts (
mkt own add, including their older posts, which
set the baseline). They feed the picker's observed reward, the "our posts" section of the
script prompt and the throttled-account check. mkt own research downloads and classifies them so we know which hook and style each
one actually used.
mkt scoreboard prints both, --group reference|ours prints one. The daily report has a section
for each.
Setup
uv venv && . .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env # fill in OPENAI_API_KEY, FAL_KEY
The scraper drives an existing Chrome over CDP (CDP_URL, default http://localhost:29229). Start
Chrome with --remote-debugging-port=29229 or point it at any CDP endpoint. ffmpeg must be on PATH.
Daily loop
mkt run tanning tanning selftanner --product "Glow, an app that previews your tan before you book"
which is the same as:
mkt scrape tanning selftanner # ~30 videos per hashtag per scroll, newest first
mkt radar --max-age-h 72 # rank by early score (views/h, discounted by follower count)
mkt download --top 8 # fetch the top videos through the browser
mkt classify # tag them (hook, style, concept, demo score)
mkt classify --niche tanning --limit 40 # tag the scored research panel instead, newest first
mkt concepts tanning # cluster into 3-8 reusable formats, flag early ones
mkt scripts <concept_id> "Glow, ..." # 12 scripts, keep demo_score >= 3
mkt render <script_id> --duration 10 # Seedance clip + captions -> data/renders/s<id>.mp4
mkt poll <url> ... # record stats for posted videos
mkt scoreboard # reward per video, hooks/concepts ranked, throttled accounts
mkt compare # our posts vs the market: each hook/style/concept side by side
mkt dashboard tanning # static HTML (data/site/index.html) with clips copied next to it
Scoreboard
mkt scoreboard turns raw views into a reward: log10(views+1), winsorized at the 95th percentile,
minus the account's own median (or the niche median for accounts with under 3 videos). +1 means 10x
what that account normally gets. Hook types, concepts and visual styles are ranked by mean reward
with n, standard error and win rate, so a hook that won once on a huge account does not outrank one
that wins consistently. Videos under 24 h old are listed but not scored. Accounts whose last 3+
posts all sit under 1k views are flagged as possibly throttled.
Feedback loop
mkt run ... --product X no longer scripts the concept with the highest early score. policy.pick_concept
samples a score per concept from the radar prior plus what has been learned about it (noise shrinks
with n). "Learned" is (SHRINK_K * trait bonus + sum of its own posts' rewards) / (SHRINK_K + n):
each concept is a bundle of traits (hook type, visual style, product on screen by 5s, pace, the
majority over its classified member videos), and every trait value keeps a running, shrunk score
from our posts (plus a quarter-weight one from the niche's reference videos). So a concept we never
posted inherits what similar ones taught us, a concept that comes back under a new name after the
next research run keeps its lessons, and with no data at all it follows the radar. mkt scripts
passes the scoreboard's winning and losing hooks, concepts and styles into the prompt.
mkt policy <niche> shows what the loop has learned.
Known limits
One-account login and feedback
# Supply TIKTOK_POST_HANDLE and TIKTOK_POST_PASSWORD through protected secrets, not CLI arguments.
# TIKTOK_POST_EMAIL / TIKTOK_POST_EMAIL_PASSWORD: the Gmail inbox on the TikTok account, read only
# for TikTok's email verification codes.
mkt own login
mkt own add @youraccount --product "your product"
mkt own sync # niche and hashtags from campaign.toml
mkt own list
This is the beginning of the README. Read the rest at the original. Read the full README ↗
