Social posts and creator videos, reviewed like a release

Drafts for ten platforms and briefs for AI creators in the repo, reviewed in the pull request, sent after the merge and measured like any change.

Then ask your agent: “Set up Appeeky Spec for this app.”

A post is a file

A post is a YAML file in appeeky/social/drafts/: the accounts it goes to, the text, when, the media, and why it is worth posting. It goes out through the accounts you connected in Appeeky: X, Instagram, TikTok, LinkedIn, Pinterest, Reddit, YouTube, Threads, Facebook and Bluesky.

One draft, several accounts

One file can go to accounts on several platforms. Without when it goes out as soon as it is sent; with it, it is scheduled. media takes public URLs, and the type is read from the file extension.

A platform that needs more than text gets its own block. Here TikTok is told the post promotes your own app and goes to the creator's inbox, so the AI-generated label can be added in the app, and Reddit gets its subreddit and title.

appeeky/social/drafts/2026-11-19-offline.yaml
accounts: [x, tiktok:@sleepysounds, reddit:u/sleepdev]
text: |
Every sound now plays offline. Turn on
airplane mode and sleep.
when: "2026-11-19T16:00:00Z"
media: ["https://…/offline.mp4"]
tiktok:
disclosure: own_brand
inbox_draft: true
reddit:
subreddit: SideProject
title: "I made my rain sounds app work fully offline"
why: "Offline was asked for in 11 reviews; it shipped in 3.3."

Naming the accounts

  • Or an id from accounts.yaml: that exact account.

accounts: [instagram]

connected in Appeeky · appeeky/social/accounts.yaml

  • x Sleep Sounds✓
  • tiktok @sleepysounds✓
  • tiktok @rainlab✓
  • instagram @sleepysounds✓
  • reddit u/sleepdev✓
  • youtube Sleep Sounds✓

✓ goes to 1 account

✗ social check: tiktok matches @sleepysounds, @rainlab

✓ goes to 2 accounts

✓ goes to 1 account

✓ goes to 1 account

Blocks for the platforms that need them

  • TikTokevery key optional

    tiktok:  # or friends, followers, only_me  privacy: public  # or none, paid_partnership  disclosure: own_brand  # lands in the inbox, to finish in the app  inbox_draft: true  # turns them off  comments: false  # video cover frame; photos: title, cover_index  cover_time_ms: 1200
  • YouTubeevery key optional

    youtube:  # up to 100; default: the first line  title: "…"  # or public, private  visibility: unlisted  # true when made for children  made_for_kids: false  # AI-generated or altered  synthetic_media: true
  • Redditrequired for Reddit

    reddit:  # required, with or without r/  subreddit: SideProject  # up to 300; default: the first line  title: "…"  # makes it a link post  link: https://…  # when the subreddit requires one  flair_id: "…"

From a file to a post, and back

Posts go the same way as a listing change. Nothing is public until a person merges, and nothing goes out twice.

  1. 01

    Draft

    Your agent, or you, writes the post as a file in appeeky/social/drafts/.

  2. 02

    Check

    social check reads it per account: length, media and each platform's own rules.

  3. 03

    Review

    Drafts and UGC briefs share the pull request with the listing change. Its check lists what the merge sends.

  4. 04

    Send

    The push workflow from init --ci, or the docker push routine, runs social push --yes. The draft gets status: sent, its post id and the time, and is committed.

  5. 05

    Measure

    The next social pull brings back views, likes, comments and shares.

What each platform takes

social check runs on every pull request and fails a draft that a platform would refuse, before anyone merges it.

  • X

    280 characters

    optional

  • Threads

    500 characters

    up to 20 images and 10 videos

  • Bluesky

    300 characters

    up to 4 images or one video, not both

  • Facebook

    63,206 characters

    up to 10 images or one video, not both

  • Instagram

    2,200 characters

    at least one image or video

  • TikTok

    2,200 characters

    at least one; at most 35 images; never images and a video

  • Pinterest

    500 characters

    at least one image or video

  • YouTube

    5,000 characters, the description

    exactly one video

  • Reddit

    40,000 characters, the body

    optional; a subreddit is required

One text, measured per platform

The same draft can be fine on Instagram and refused on X. The check measures the text against every account it goes to, and the draft fails if one of them would refuse it.

$ appeeky-spec social checktext: 340 chars

$ appeeky-spec social check · also fails a draft on

  • media: []✗ Instagram needs an image or a video
  • media: [a.jpg, b.mp4]✗ Bluesky: images or one video, not both
  • accounts: [linkedin]✗ not connected in Appeeky
  • accounts: [tiktok]✗ matches two TikTok accounts
  • when: "2026-11-01T09:00:00Z"✗ a time already in the past
  • privacy: only_me + disclosure✗ only as an inbox draft
  • title: 91 characters✗ TikTok photo titles stop at 90
  • title: 101 characters✗ YouTube titles stop at 100
  • reddit: { title: … }✗ no subreddit; a title over 300

Every post measured, every comment seen

The numbers and the conversation come back into the repo, for you and for your agent.

Posts from Appeeky and from the apps

social pull writes the connected accounts, each post's views, likes, comments and shares, the posts you made in each platform's own app with the same numbers, recent comments and followers per account.

summary.md has the last 30 days per platform and account, and what did best across all posts. The daily workflow runs it, so it is always current.

zsh
$ npx @appeeky/spec social pull
Accounts x (Sleep Sounds), tiktok (sleepysounds), reddit (sleepdev)
Posts 38 through Appeeky · 36 published · 112 made in the apps
Comments 214
Written to appeeky/social/: accounts.yaml, posts.jsonl,
native-posts.jsonl, comments.jsonl, insights.yaml, summary.md.

Answered by you, drafted by the agent

social comments --unanswered lists what people asked under your posts, newest first, with the id to act on. --account, --post and --limit narrow it, and --json says whether each can be replied to, hidden, liked or deleted.

The social specialist writes a reply for each as a social reply command. It never sends one, and the weekly routines deny these commands to the agent. You run the ones you agree with.

zsh
$ npx @appeeky/spec social comments --unanswered
91ab… tiktok @sleepysounds 2026-11-20 09:12
mara.k: does it work on a plane??
6f1c… reddit u/sleepdev 2026-11-20 07:40
nightowl: Does it drain the battery overnight?
Reply with: appeeky-spec social reply <id> "<message>"

Creator videos from a brief

A creator video starts as a brief in appeeky/ugc/briefs/, for one of your creator personas. After the merge the clip is made the way Appeeky UGC makes it: a still of the persona in the scene, then a talking video in their voice.

A brief per video

ugc pull writes your personas from Appeeky to personas.yaml, with whether each is ready, and the clips made so far to clips.jsonl. A persona needs a look, its reference images, before it can make clips.

The script is what the persona says out loud: one clip is about eight seconds of speech.

appeeky/ugc/briefs/2026-11-19-plane.yaml
persona: Mia
script: "I fell asleep on a plane for the first time. No wifi, just rain."
scene: window seat at night, phone on the tray table
caption: "works in airplane mode"
durationSec: 8
aspectRatio: "9:16"
why: "Offline hooks did best on TikTok last month (summary.md)."

See the cost before anything is made

ugc generate makes a clip from each draft brief with Appeeky media credits. --dry-run shows what each costs and makes nothing. The push workflow runs ugc generate --yes after a merge and marks each brief generating, so it is made once.

zsh
$ npx @appeeky/spec ugc generate --dry-run
appeeky/ugc/briefs/2026-11-19-plane.yaml Mia · 40 credits
40 credits in all. Nothing was made.

Or render on your own fal key

--local runs the same pipeline where Spec runs, on your own FAL_KEY. fal bills your account and no Appeeky credits are used. The dry run shows the cost in dollars.

The clip is saved to .appeeky/media/ and the brief records clipFile, fal's videoUrl for a draft's media:, and costUsd. Set FAL_KEY as a secret and the push workflow renders locally too.

The persona can be one from Appeeky (its cover image is the look) or appeeky/ugc/personas/mia.yaml with its look images.

zsh
$ npx @appeeky/spec ugc generate --local --dry-run
appeeky/ugc/briefs/2026-11-19-plane.yaml
Mia · 8s 9:16 · veo-3.1-fast · about $1.24 on fal
About $1.24 on your fal account in all. Nothing was made.

The social and UGC specialists

Two of the six specialists work on this. They only read: the co-founder review turns what they return into drafts and briefs in the same pull request as the week's listing change.

reads

  • posts.jsonl · native-posts.jsonl: which hooks did best per account
  • comments.jsonl: the unanswered ones
  • what shipped and won, the next What's New, review words
  • the channels and smart links that bring installs
appeeky-social

returns

a post per connected account, within its limit

x · 63/280 · Thu 16:00

tiktok · video · own_brand · link …/l/ab12xy

replies, as commands for you to run

social reply 91ab… "Yes, fully offline."

and comments a person may want to hide

reads

  • personas.yaml: which personas are ready
  • clips.jsonl and the briefs already waiting
  • UGC experiments: smart link installs and revenue
  • the personas in the spec, the words in reviews
appeeky-ugc

returns

what won, by link installs or revenue

before/after hooks · 52 link installs · target 40

the next video, as a brief

Mia · script under 25 words · 8s · 9:16

one variable changed per experiment

  • why: "Offline was asked for in 11 reviews; it shipped in 3.3."
      ↳ appeeky/reviews/summary.md, no names

    Only what the app does today, from the repo. No made-up numbers or quotes.

  • tiktok:
      disclosure: own_brand
      inbox_draft: true
    youtube:
      synthetic_media: true

    Posts about the app are disclosed. AI-generated media goes as a TikTok inbox draft.

  • $ social check  ✓
    $ ugc generate --dry-run
      40 credits in all. Nothing was made.

    The co-founder only checks. Sending and making stay with the merge.

The commands

social pull
Accounts, posts from Appeeky and the apps, comments, followers and a 30-day summary into appeeky/social/.
social check
Check the drafts: accounts, length, media, TikTok, YouTube and Reddit rules, time.
social push
Send the drafts, now or at their when. --yes in the push workflow.
social comments
Comments on your posts, newest first: all of them, only the unanswered, one account or one post.
social reply · hide · like
Act on one comment, where the platform allows it.
social delete-comment
Delete a comment; asks first, or --yes outside a terminal.
ugc pull
Your creator personas and their clips into appeeky/ugc/.
ugc generate
A clip from each draft brief: --dry-run for the cost, --local on your own FAL_KEY.
Every command in the docs

Guides

More in Appeeky Spec