The social agents repo is an open-source agent harness that runs your social accounts through Creator OS. It lives at github.com/kevinbadi/social-agents, and the fastest way to see what it does is one command: npm start creatoros social-agents. That starts an interview about your brand, then the agent posts, replies to comments and DMs, runs automations, and reports. This post walks through what the repo contains, how to install it, how to wire it to the Creator OS API and follow each network’s publishing rules, and when the repo stops being the right tool.
you ──► npm start creatoros social-agents
│
▼
brand interview (voice, offer, cadence)
│
▼
agent loop ──► create_post ──► Creator OS API
│ │
│ └──► instagram / tiktok / x / linkedin
▼
replies, DMs, automations, weekly report
│
▼
local dashboard (runs on your machine)What the Social Agents Repo Actually Is
It is an agent harness, not a scheduler. The distinction matters. A scheduling dashboard wants you to sit in a browser and click a calendar. The repo wants a model to make decisions: what to post, when, in what voice, and how to answer the comments that land afterward.
Three things define it:
- It is local. The harness runs on your machine, with a local dashboard. Your prompts, your brand interview and your logs stay where you put them.
- It is model-agnostic. Bring your own model: a logged-in Claude Code session, an
ANTHROPIC_API_KEY, or any Anthropic-compatible API. Creator OS does not ship its own model, and the repo does not lock you to one vendor. - It calls Creator OS over the API. Posting, commenting, DMs and analytics run through Creator OS, the multi-platform publishing product that covers Instagram, TikTok, YouTube, X, LinkedIn, Facebook, Threads, Skool, a WordPress blog, and paid ads as an add-on. It is where your accounts actually live, and it is what the harness drives.
If you have read our piece on open-source social agents, this is the practical companion: what is in the box and how to get it running today.
What Is Inside the Repo: Agents, Tools, and Configs
The repo is organized around the loop, not around a UI. You will find four kinds of thing.
Agents
An agent is a named job with a prompt and a tool allowlist. The harness interviews you once about brand voice, offer and posting cadence, then reuses that context on every run. You can add agents for a launch week, a weekly recap, or a comment triage shift.
Tools
Tools are the actions an agent can take. Through Creator OS they map to MCP tool names like create_post, update_post, upload_media_from_url, list_comments, reply_to_comment, list_conversations, send_message, create_automation, get_post_analytics, get_best_time_to_post, get_follower_stats, check_caption_length, skool_create_post, skool_multi_post, blog_create_article, ads_create_ad, ads_boost_post, skills_list and skills_get. Destructive tools such as delete post, delete comment, disconnect account and delete ad are marked so the AI app asks you first.
Configs
Config is where the harness reads your workspace, your model choice and which agents are enabled. Nothing about your credentials belongs in the repo itself. Keys go in environment variables, and the config points at them.
The dashboard
A local dashboard shows what ran, what published, and what the agent decided. It is a debugging surface, not a client-facing tool.
How the Social Agents Repo Compares to Other Options
There are three broad shapes of tooling here, and they are not really competing.
A social media scheduling dashboard is a calendar with a composer: you write, you pick a time, you watch it go out. A workflow builder is a visual graph where you connect triggers to actions. Both are useful and both assume a human is driving.
The repo takes a third shape. It hands the loop to a model and keeps the execution layer in a product. Creator OS ships a hosted MCP server at https://mcp.creatoros.ca/mcp and a CLI, so an AI agent can run your accounts through the same API a human would use in the web app. That means the publishing rules for each network, the media pipeline, the comment and DM plumbing and the analytics are handled by Creator OS, and the repo only has to decide what to do.
If your instinct is to compare agent harnesses to automation platforms, our breakdown of Creator OS vs Zapier for social media covers where each one fits. If you would rather see the API surface first, start at the social media API for AI agents.
Installing and Configuring the Repo Step by Step
Here is the full path from nothing to a first automated post.
1. Create a Creator OS workspace and connect accounts
Sign up, then connect the accounts the agent should run. Every plan includes API keys, the MCP server, the CLI and the agent skills. The Creator plan is $19.99/month or $59.99/year and covers up to 8 connected accounts, which is 7 socials plus Skool.
2. Clone the repo and start the harness
git clone https://github.com/kevinbadi/social-agents
cd social-agents
npm start creatoros social-agentsThe first run interviews you. Answer it properly. The brand interview is the difference between an agent that sounds like you and an agent that sounds like a press release.
3. Pick a model
Either use a logged-in Claude Code session, set ANTHROPIC_API_KEY, or point at any Anthropic-compatible API. Creator OS works with any MCP-capable AI app; it does not ship its own model.
4. Add the Creator OS MCP server
In Claude: Settings, Connectors, Add custom connector, paste https://mcp.creatoros.ca/mcp, sign in, pick the workspace, then choose read only or read & write. In Claude Code:
claude mcp add --transport http creatoros \
https://mcp.creatoros.ca/mcp \
--header "Authorization: Bearer cos_live_..."Cursor, Windsurf and VS Code take an mcpServers entry with type http, the URL and the same Authorization header. ChatGPT uses the same URL as a connector in developer mode. The MCP docs have the exact snippets.
5. Install the CLI skills (optional)
npx @creatoros/cli@latest initThat installs 14 Claude Code skills: post-everywhere, post-shortform, post-longform, post-threads, schedule-posts, respond-to-comments, respond-to-dms, automations, analytics, kairos-dashboard, ads, meta-campaign-builder, skool and blog. Later, creatoros sync updates them without overwriting files you edited; updates land as .new files.
6. Verify before you let it post
creatoros auth:check
creatoros accounts:list
creatoros accounts:health
creatoros accounts:connect instagramaccounts:health is the one people skip and then regret. Check it before every long unattended run.
Connecting the Agent to the Creator OS API
The repo decides; Creator OS executes. Two credentials make that work.
MCP for interactive sessions
When you are sitting in Claude or Cursor and want the agent to draft and schedule, the hosted MCP server is the shortest path. Nothing to install, and read-only connections only see read tools because the API refuses writes from them.
The REST API and CLI for unattended runs
The REST API authenticates with a Creator OS API key that starts with cos_live_ and is pinned to one workspace, which is one set of socials. An agent holding one workspace’s key cannot post to another. IDs are opaque typed tokens: acc_, post_, cmt_, conv_, msg_, auto_, med_. Errors come back in one shape: { error: { code, message, status } }. The docs at creatoros.ca/docs list the base URL; use those, not a guess.
A concrete posting call from the CLI looks like this:
creatoros posts:create \
--text "Three things I learned shipping a Skool community this month" \
--platforms instagram,tiktok,x \
--media https://cdn.example.com/clip.mp4 \
--scheduledAt 2026-03-04T14:00:00Z \
--timezone America/TorontoCreator OS applies each platform’s rules for you: Reels, Shorts, the TikTok consent flags, caption limits, and the rest. In the advanced REST form, platforms become objects with their own options and account_id, and TikTok settings go in a top level tiktok object. Upload a file once with creatoros media:upload and you get a med_ id you can reuse on every network.
One behavior worth knowing when the agent posts to a network you forgot to connect: those networks come back in missing_platforms, and the rest still go out.
Rate Limits and Account Controls to Respect
An agent that posts faster than a human is an agent that trips platform controls. Four habits keep you inside the lines.
- Pace the queue. Do not let one run publish twenty things. Spread posts across the day and use
get_best_time_to_postrather than guessing. - Validate the expensive stuff. Before a campaign, add
--validateOnlyto the create call. Ads are also created paused for review. - Keep read-only where read-only is enough. A commenting agent that only needs to read should not hold a write key.
- Expect destructive tools to prompt. Deletes and disconnects are marked so the AI app asks first. Do not route around that.
There are also hard ceilings on the platform side, and Creator OS surfaces them so you hit them in a log instead of an account review. Meta allows roughly 30 creates per ad account per 5 minutes. Google allows about 15 live calls a minute. TikTok campaigns carry a $20 minimum budget. LinkedIn sponsored posts start at 10 per day and are reviewed. Budgets are whole units of the ad account currency.
If you edit video in the same pipeline, the same care applies to compute. Our notes on running video generation locally and on faster social video models cover where the time actually goes.
Common Errors and How to Fix Them
The agent posts to the wrong accounts
Your key is scoped to one workspace. If a post lands somewhere unexpected, you are running the harness against the wrong workspace, or using a key from another one. Run creatoros profiles:list and creatoros accounts:list to confirm what the current key can see.
A scheduled post never goes out
Check the timezone first. A missing --timezone on a scheduled create is the most common cause. Then check status:
creatoros posts:list --status scheduled
creatoros posts:list --status failed
creatoros posts:get post_abc123
creatoros posts:retry post_abc123Media fails on one network but not another
Platform rules differ. Instagram cannot attach trending audio through the API, so sound has to be baked into the file; Stories have no collaborators, location or paid partnership. YouTube Shorts do not take custom thumbnails. Validate before publishing:
creatoros validate:post-length --text "your caption"
creatoros validate:media --url https://cdn.example.com/clip.mp4The agent replies to something it should not
Pull the thread, read it, then act.
creatoros inbox:comments --platform instagram --limit 25
creatoros inbox:post-comments post_abc123 --accountId acc_123
creatoros inbox:hide-comment post_abc123 cmt_777 --accountId acc_123
creatoros inbox:reply post_abc123 --accountId acc_123 --message "Thanks, sending details now"Note that replying to TikTok comments is not supported, and TikTok has no DMs. If an agent assumes otherwise, it will fail quietly.
When to Move from the Repo to a Managed Platform
The repo is the right answer when you want to control the loop: your own model, your own prompts, your own dashboard, your own machine. It is also the right answer when you are building something and want to inspect every step.
It becomes the wrong answer when nobody wants to own the upkeep. A self-hosted harness needs someone to update dependencies, watch runs and notice when a platform changes a rule. Once the novelty wears off, that is a job.
The move is smaller than it sounds, because the execution layer does not change. Creator OS already ships the web app, the iOS app, the REST API, the CLI and the hosted MCP server, and every plan includes API keys, the MCP server, the CLI and the agent skills. You can start in the repo and graduate to schedules you manage in the app without rewriting your posting logic.
For teams that want the agent to keep working but stop being a side project, the practical path is to keep the agents you like and run them through the platform. If you are editing video alongside the posting, the open-source OPEN VIDEO EDIT skills do something similar for footage: they turn a raw talking-head clip into an animated short with captions, logos, faces, GIFs, b-roll cards and counters, rendering locally with Python and ffmpeg.
That is the pattern across all of this: open source for the parts you want to own, a hosted platform for the parts you do not. Our post on AI agent skills for social media automation goes deeper on how the skill layer fits together.
Get Started with Creator OS
Two commands and an interview stand between you and an agent that runs your socials.
- Create a workspace at creatoros.ca/sign-up. The Creator plan is $19.99/month or $59.99/year for up to 8 connected accounts.
- Connect your socials and Skool, then generate an API key.
- Clone the repo and run
npm start creatoros social-agents. - Answer the brand interview honestly. The agent copies what you tell it.
If you would rather watch it happen first, the walkthroughs on the KevBuildsApps YouTube channel show the setup end to end, and the launch video covers the original release. For everything else, the docs at creatoros.ca/docs are the source of truth.