README.md

Socials Studio

Turn an idea, image, video, or OpenMontage project into a real social media campaign.

Tell it what you want -- a topic, a product shot, a finished video, or a rendered OpenMontage project -- and Socials Studio writes platform-specific posts for YouTube, X, Bluesky, LinkedIn, and Instagram, adapts each one to that platform's own conventions, and publishes only once you've reviewed and confirmed it. Claude Code is what operates the tools -- it does the writing, coordinating, and publishing -- and nothing is ever published without your explicit approval. Socials Studio is the local toolkit and set of skills Claude Code uses to do that safely.

Socials Studio is an independent community project, not affiliated with, maintained by, or endorsed by OpenMontage. It works just as well with any other video, image, or idea.

Public beta — v0.1.0-beta.4. Guided installers for Windows, macOS, and Linux are here (see Get started below); this beta has been developed and tested with Claude Code -- see Testing status before pointing it at a real account.

Download Socials Studio

Download Socials Studio -- the guided download experience, with an installer for each operating system and no GitHub or Git required.

Or grab v0.1.0-beta.4 directly from GitHub Releases:

• Windows (recommended): Socials-Studio-Setup.exe -- no GitHub, Git, or existing Python installation needed; Python is set up for you automatically. The installer isn't code-signed yet, so Windows may show a SmartScreen "unrecognized publisher" warning -- that's expected for now.
• macOS: Socials-Studio-macOS.zip -- needs a system Python 3.10+ already present.
• Linux: Socials-Studio-Linux.tar.gz -- needs a system Python 3.10+ already present, and real Google Chrome (not Chromium -- chromium/chromium-browser aren't supported; the design depends on real Chrome).

Either way, you'll still need Claude Code access and to sign in with a qualifying Claude account -- the installer can't do that part for you, and it never touches your social media accounts, logs in anywhere, or publishes anything during setup. See Testing status below for exactly what's been verified on each platform before pointing it at a real account.

Prefer the full walkthrough, checksums, and platform-by-platform detail? Use the Releases page or solvx.uk/socials-studio.

Get started

You need a Claude subscription either way -- Socials Studio doesn't work without Claude Code, since Claude is what actually reads your request, writes the posts, and runs the publishers. Two ways to get set up, both ending in the same place: a working Claude Code session, open in this project, ready to talk to.

New to all this? Use the guided installer.

This is the Download Socials Studio section above -- download the installer for your operating system and run it, no GitHub account or Git required on any platform. The installer copies the project onto your machine, checks for Claude Code and Google Chrome, and prepares the Python environment Socials Studio runs in. If Claude Code isn't found, it offers to install it for you -- on Windows, as an unchecked opt-in checkbox on the installer's own finish page (via WinGet if available, otherwise Anthropic's official installer, and only if you check the box); on macOS/Linux, as a yes/no prompt in the terminal. Declining either is fine -- the Socials Studio launcher is installed either way, and Claude Code is still required before you can use it. This project never bundles or redistributes Claude Code itself; it only offers to run Anthropic's own official installer, and only with your explicit say-so. It finishes by opening a Socials Studio launcher; the first time you run it, Claude introduces itself, explains what it can do, and offers to walk you through connecting your first platform.

Already use Claude Code? Install via the repository instead.

The secondary, technical route -- clone the repository and let Claude Code set it up:

git clone https://github.com/tradewithmeai/socials-studio.git
cd socials-studio
claude

Once Claude Code is open in the project, just ask it to set things up -- for example:

"Set this project up for me."

Claude will explain each setup step before running it (a Python virtual environment, dependencies, a health check) and wait for your yes each time -- nothing happens silently. No separate installer needed for this route.

What this is

An agentic social media studio, operated through Claude Code. Give it an idea, a campaign brief, or finished media. It can create platform-specific content, coordinate multiple posts, review and validate the campaign with you, publish approved material through the existing publishers, and inspect the response -- all from one local, extensible workspace.

OpenMontage can create the video. Socials Studio can request, understand, adapt, and publish the resulting media as part of a wider campaign.

This is file-based compatibility with OpenMontage, not a technical integration -- Socials Studio has no dependency on OpenMontage's code and doesn't call into it. It works with a finished video file from OpenMontage exactly the same way it would work with a finished video file from anywhere else, or with no video at all.

How it works (the simplest case)

1. Create -- Render or export your finished video from OpenMontage (or any other source).
2. Review -- Point Socials Studio at the file and set the title, description, and visibility. Every publisher validates by default and touches nothing until you explicitly confirm -- see Publishing safety below.
3. Publish -- Authenticate once, then publish to YouTube, X, Bluesky, LinkedIn or Instagram. Uploads default to private/draft where supported so you can review the live result yourself before making it public.

OpenMontage export -> Socials Studio review -> publish to YouTube, X, Bluesky, LinkedIn or Instagram

That's the single-video, single-post path. It's not the ceiling -- see the next section for what else you can ask for in the same conversation.

What you can ask it to do now

Socials Studio isn't a fixed set of commands you invoke one at a time -- it's Claude Code's reasoning and coding intelligence, working through this repository's authentication, validation, and publishing primitives, its skills, and a local codebase it can inspect and extend. None of the following needs a dedicated button or a pre-written skill before it's possible; a skill just packages a workflow that already works into something more repeatable. You can ask it to:

• Write a post for a specific platform, in that platform's own conventions.
• Turn one idea into several platform-specific posts in a single pass.
• Prepare text, image, and video variants for a post.
• Ask OpenMontage -- or another available agentic video application -- to generate the media a campaign needs.
• Use an OpenMontage project's own script/brief/render-report context (via the openmontage-context skill) instead of guessing what a video contains.
• Assemble several related posts into a coordinated, multi-platform campaign.
• Adapt each post to the rules and conventions of its destination platform.
• Present the whole campaign for your review before anything goes out, and validate every result -- every publisher here is safe-by-default and touches nothing until you explicitly confirm.
• Publish approved posts through the existing publishers (YouTube, X, Bluesky, LinkedIn, Instagram).
• Inspect subsequent activity on published posts, on request, and use those observations to prepare or recommend the next round of content.
• Add another social platform -- ask Claude Code to extend the repository following the existing publisher pattern (auth, validation, tests, and a skill), respecting that platform's real API/browser constraints, its terms, and this project's confirmation gates.

Some of these may lead Claude to write or adapt local code -- a new platform's publisher, for instance. That's the intended way this application grows, not a workaround; the result still has to pass this project's own validation and --confirm-publish gate before anything real happens.

What isn't available yet

• Live streaming.
• Unattended or scheduled automated publishing, as a packaged, supported workflow. Claude can already prepare and execute a multi-post, multi-platform campaign in one session with your review and explicit --confirm-publish at each consequential step -- what's missing is publication that continues without you reviewing and authorising it through that gate.

A future skill can turn either of these into something more discoverable, repeatable, and tested once there's a proven pattern worth packaging -- that's a maturity milestone, not the first moment the capability exists.

For OpenMontage users

OpenMontage render
    → Socials Studio reads available project context
    → review title, description and platform details
    → validate safely
    → explicitly confirm publication

OpenMontage's pipeline writes its own plain JSON artifacts alongside a render -- the script that was actually used, the intended tone and audience, the real output resolution and duration. If you're using Claude Code, the openmontage-context skill reads whatever of that is actually present for a given project (different OpenMontage pipelines produce different artifact shapes, so this isn't a fixed schema to depend on) and grounds the copy it suggests in what the video actually says, rather than inventing framing from scratch.

This works the same way regardless of source -- any finished video file can be used, with or without OpenMontage context available. See OPENMONTAGE.md for the full guide.

Supported platforms

Publish videos and posts to YouTube, X (Twitter), Bluesky, LinkedIn and Instagram.

Platform	How it authenticates	Publish	Notes
YouTube	OAuth + Data API	Yes	No browser at all. Google blocks automated sign-in, so this is the official API path. Needs your own Google Cloud OAuth client -- see setup below
X (Twitter)	Saved browser session	Yes	Text, image or video. Uses browser automation via a saved login session, not the X API -- selectors can break if X changes its interface
Bluesky	Saved browser session	Yes	Text, image or video
LinkedIn	Saved browser session	Yes	Text, image or video. Media can never be added to a post after publishing
Instagram	Saved browser session	Yes	Reels (video)

python doctor.py checks all of the above and tells you what is missing.

See ROADMAP.md for what's next.

Publishing safety

Every publisher in this repo -- the library function and its CLI wrapper -- validates only and touches no browser, no API, and no network call to a platform unless you explicitly confirm:

python -m auth.publish_bluesky "post text" --confirm-publish      # actually posts
python -m auth.publish_bluesky "post text"                        # validates only (the default)
python -m auth.publish_bluesky "post text" --dry-run               # validates only (explicit)

--confirm-publish (CLI) / confirm_publish=True (library call) is required to actually publish anything. --dry-run / dry_run=True always wins if both are passed, so there's no way to accidentally force a real publish through code that still passes dry_run=True out of habit. Every result includes a "dry_run" field and a plain-language "message" stating whether anything was actually published.

YouTube additionally requires exactly one of --made-for-kids / --not-made-for-kids and --acknowledge-upload-terms for a real upload -- see YouTube-specific requirements below.

Testing status

This beta has been developed with Claude Code. Publishing has been tested for YouTube, X, Bluesky, LinkedIn and Instagram, including with OpenMontage-rendered video.

This is exactly what the beta is for. If you run this against a real account -- with OpenMontage output or anything else -- please file a beta test report either way, pass or fail, both are useful. Other coding agents, operating systems, and configurations haven't been validated at all yet; reports on those are especially welcome.

Installers, specifically: CI builds and smoke-tests all three on GitHub's own runners (silent install, verify the expected files exist, verify a reinstall doesn't touch profiles/) before any installer change merges -- see .github/workflows/build-installers.yml. That's real, automated platform coverage, but it is not the same as a person installing this on their own machine and actually launching Socials Studio. Do not read any of the three as fully verified until that's happened:

• Windows: the v0.1.0-beta.3 installer was installed and launched successfully on a real Windows 11 machine -- existing Claude Code detection and launch into Socials Studio were confirmed. The optional "install Claude Code for me" route has passed automated Windows CI testing, but hasn't yet been tested by a person on a machine without Claude Code already installed. The newly built v0.1.0-beta.4 binary hasn't received a separate human hardware retest of its own yet.
• Linux: installer mechanics tested on Ubuntu 24.04 x64; real Chrome/account publishing not tested through this package. Requires real Google Chrome, not Chromium.
• macOS: automated runner test only; no human hardware test received.

If you try any of these on real hardware, a beta test report saying exactly what happened -- pass or fail -- is exactly what this needs, especially for macOS and Linux, which haven't had a real-hardware run yet.

Install for contributors (CLI route)

Most people should use Get started above instead -- the agent route or the guided installer. This section is the manual, command-line path: useful if you're contributing to Socials Studio itself, scripting it, or just prefer doing it by hand.

git clone https://github.com/tradewithmeai/socials-studio.git
cd socials-studio

Create and activate a virtual environment first -- this keeps the project's dependencies isolated from anything else on your machine:

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

Then install:

pip install -r requirements.txt
python -m playwright install chrome

Playwright drives a real Chrome build here (not bundled Chromium) -- social platforms flag automation fingerprints more readily on Chromium, so this uses the same Chrome you'd log into by hand. playwright install chrome is idempotent; safe to re-run. It also fetches/verifies a real Chrome browser build (a few hundred MB) -- know that before running it.

Supported Python versions: 3.10 through 3.13 (matching what this project's dependencies actually require and what's been tested in CI -- see .github/workflows).

If you're contributing or running the test suite, also install the development dependencies:

pip install -r requirements-dev.txt

Setup and authentication

YouTube is different from the rest -- it uses the official Data API, not a browser at all. Google blocks automated browser sign-in outright, so OAuth is the only supported path. See the onboard-youtube skill, or run:

python -m auth.setup_youtube_oauth

(one-time; requires your own Google Cloud OAuth client -- the skill walks through creating one). This tool requests only the minimum OAuth scopes publishing and python doctor.py demonstrably need (youtube.upload and youtube.readonly -- see PRIVACY.md). If a future version changes the requested scopes, a token issued under the old ones will fail on refresh with a "scope has changed" error rather than silently keep working -- delete profiles/youtube/token.json and re-run setup if that happens.

For X, Bluesky, LinkedIn and Instagram, log into each platform once. A real Chrome window opens to that platform's login page -- log in yourself, same as you normally would:

python -m auth.login_wizard --platform bluesky

The session is saved to profiles/<platform>/ on your machine only. It's gitignored, never transmitted anywhere, and never read by anything except your own later publish commands.

That window opens in English regardless of your OS or normal Chrome language -- this keeps the platform-detection selectors working reliably, since they look for English UI text. It only affects this isolated profiles/<platform>/ Chrome profile; your regular Chrome profile and system language are untouched. List supported platform keys anytime:

python -m auth.login_wizard --list

Example usage

Validate first -- this is also the default with no flags at all:

python -m auth.publish_youtube render.mp4 --title "My video" --dry-run

Real publish, private by default:

python -m auth.publish_youtube render.mp4 --title "My video" --description "..." \
    --visibility private --not-made-for-kids --acknowledge-upload-terms --confirm-publish

Pass --visibility public explicitly to go live immediately; otherwise review the private/draft upload on YouTube yourself before flipping it public.

YouTube-specific requirements

Per the YouTube API Services Terms of Service, Section 9.1, a real upload requires two things beyond what other platforms need:

• --made-for-kids / --not-made-for-kids -- mutually exclusive; you must pass exactly one before upload, declaring whether the video is directed at children. Argparse itself rejects passing both, and a real upload refuses to proceed if neither is given -- this is never defaulted or inferred. Sent as the API's status.selfDeclaredMadeForKids field (true or false).
• --acknowledge-upload-terms -- confirms the required upload notice was shown and accepted. python -m auth.publish_youtube prints the exact required text (see auth.publish_youtube.UPLOAD_TERMS_NOTICE) unconditionally on every real-publish attempt -- whether or not this flag is already set -- so the flag can never merely suppress a notice nobody saw; it only gates whether the upload proceeds past that point. This is enforced in code, not just documented here -- a real upload cannot proceed past it silently.

Neither is required for --dry-run.

Troubleshooting

• No saved <platform> session found -- run the login wizard for that platform first; the publish command reads from profiles/<platform>/. This applies to X, Bluesky, LinkedIn, and Instagram, which authenticate via a saved browser session.
• No YouTube token found -- YouTube doesn't use a browser session at all; run python -m auth.setup_youtube_oauth first. It writes profiles/youtube/token.json.
• Chrome install fails -- playwright install chrome needs network access; check your connection and re-run (it's a no-op if already installed).
• A step doesn't match what's on screen -- these platforms' UIs are not a stable public contract. Run with the browser visible (the default) so you can see where it diverges, and file a bug report with what you saw. Selectors going stale after a platform UI change is the single most likely failure mode for this kind of tool.
• Login wizard times out -- default wait is 10 minutes; re-run with --timeout <seconds> if you need longer (2FA app switching, etc.).

If this is useful to you

• Star the repo if this workflow saves you time -- it costs nothing and it's the easiest signal that it's worth continuing to maintain.
• Run it against a real account and file a beta test report, pass or fail -- both are useful.
• Used it with OpenMontage output specifically? Say so in that report. Real compatibility findings from actual projects are worth more than anything written in this README.

Reporting problems / requesting features

• Report a problem -> Bug report issue template.
• Feature/platform request -> Feature request issue template.
• Share test results -> Beta test report issue template. Please include: whether installation worked; your operating system; whether you used Claude Code or another coding agent; whether authentication worked; whether YouTube publication succeeded; where the instructions were unclear; and anything specific to OpenMontage-rendered output, if that's what you tested with.
• Broader feedback or ideas -> GitHub Discussions.

See SECURITY.md to report a security issue specifically, PRIVACY.md for what's stored locally and why, CONTRIBUTING.md before sending a PR, and OPENMONTAGE.md for the full OpenMontage-specific guide.

Roadmap

See ROADMAP.md and CHANGELOG.md.

License

MIT -- see LICENSE.