SimplePost

SimplePost is a platform for AI agents, apps, and humans to post on social media. It gives you one TypeScript-powered posting layer and five ways to use it: SDK, HTTP API, Scheduler app, CLI, and MCP server.

SimplePost is open source and ownership first: get the code, run it yourself, modify it, and connect it to your own social platform apps and credentials. Learn more at simplepost.social.

Using ChatGPT? Open the SimplePost plugin, select + to install it, then start a new chat.

Agent Skill

Install the portable SimplePost skill in Codex, Claude Code, Cursor, and other Agent Skills-compatible clients:

npx skills add simple-post/core --skill simplepost

The skill teaches an agent how to publish, schedule, draft, preview, inspect, and manage posts through SimplePost without inventing account IDs, duplicating uncertain writes, or hiding partial platform failures. It also routes application integrations to the CLI, HTTP API, Scheduler app, or TypeScript SDK. The canonical source lives in skills/simplepost.

The same skill is bundled in the repository's Codex plugin:

codex plugin marketplace add simple-post/core
codex plugin add simplepost@simplepost-core

The repository root is also a portable Agent Plugin for Cursor and other compatible clients. See Cursor installation and marketplace verification.

Kiro can install the same package as a Power. See Kiro activation testing and submission guidance.

Grok Build can install this repository directly and use the same canonical skill. See Grok Build verification and marketplace guidance.

The repository root is also installable as a Gemini CLI extension:

gemini extensions install https://github.com/simple-post/core

See the Gemini CLI extension guide for OAuth verification and gallery publication.

The ClawHub bundle is packaged from integrations/openclaw while keeping this repository's skill canonical. See OpenClaw verification and publishing.

What You Can Build With It

All five paths build on @simple-post/sdk, with different payloads, authentication, and workflow capabilities. Hosted users share connected accounts across the web app, MCP, CLI, and API. Direct SDK/local CLI use your own credentials. Compare interfaces and published versus hosted behavior.

Quick SDK Example

npm install @simple-post/sdk

Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID (for example @mychannel), then give the bot permission to post in that chat. The chat ID is passed explicitly. Telegram setup.

import { post } from "@simple-post/sdk";

const botToken = process.env.TELEGRAM_BOT_TOKEN;
const chatId = process.env.TELEGRAM_CHAT_ID;
if (!botToken || !chatId) throw new Error("Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID");

const results = await post({
  content: { text: "Hello from SimplePost" },
  platforms: ["telegram"],
  options: { telegram: { chatId, credentials: { botToken } } },
});

const result = results.get("telegram");
console.log(result);

Inspect every entry in the returned Map for success or failure. This quickstart is verified against published SDK 1.3.1.

Why SimplePost Exists

Social APIs are inconsistent. Authentication, media rules, rate limits, scheduling behavior, and error responses all vary by platform. SimplePost hides that complexity behind one modern interface while still giving you access to the underlying code.

The main use cases are:

• AI agents that can validate, publish, or schedule social posts for a user.
• Product backends that need one posting interface instead of ten platform integrations.
• Humans who want a web UI for composing, previewing, and scheduling.
• Scripts and command line workflows that need reliable non-interactive posting.
• Self-hosted teams that want ownership, no subscription dependency, and no vendor lock-in.

Supported Platforms

Repository Layout

Getting Started

For hosted use, follow Get started. For development and self-hosting, start with the repository documentation index.

Release and compatibility references:

• Changelog
• SDK compatibility policy
• API versioning policy
• Migration notes

Found a bug or have a feature request? Open an issue or start a thread in Discussions.

Contributing

See CONTRIBUTING.md for how to set up the repo and submit changes, and SECURITY.md for reporting vulnerabilities.

License

Everything in this repository is licensed under the MIT License.

Product documentation

Hosted onboarding and user guides live at docs.simplepost.social. Run yarn docs:export with a sibling docs checkout to export references from this revision. Follow the documentation release checklist when changing public behavior.