gitroomhq/postiz-agent

What it is

postiz‑agent is a thin wrapper that lets AI‑agents (ChatGPT, Claude, Gemini, etc.) call the Postiz CLI from inside the various AI‑agent ecosystems (Claude Code, Cursor, Gemini, Grok Build, DeepSeek Harness, etc.). The underlying Postiz CLI talks to the Postiz SaaS platform, which provides a unified API for scheduling and publishing social‑media posts on dozens of platforms (Twitter/X, LinkedIn, Reddit, TikTok, Instagram, YouTube, Facebook, …).

Who might use it

• Developers building AI‑assistant tools that need to publish content automatically – e.g. a ChatGPT plugin that drafts a tweet and schedules it.
• Product teams that want to expose Postiz as a built‑in “skill” inside their own AI‑agent platform (Claude Code, Cursor, Gemini, etc.).
• Power users who already use the Postiz CLI and want to trigger it from a conversational AI without writing custom glue code.

Core pieces (as described in the README)

Piece	What it does
Skill/CLI integration	Registers a postiz skill inside the host agent. The skill forwards commands to the globally‑installed postiz npm CLI (which must be installed separately).
Manifest files	Provides the required plugin manifests for each host platform (.grok-plugin, .cursor-plugin, gemini-extension.json, DeepSeek Harness bundle, etc.).
MCP server registration	For platforms that support an MCP (Multi‑Channel Publishing) server, the plugin points to the hosted Postiz MCP endpoint (https://mcp.postiz.com/mcp‑oauth‑dynamic). This handles OAuth flow and token storage for the agent.
Postiz CLI	The real workhorse – authenticates (OAuth device flow or API key), lists integrations, uploads media, creates/schedules posts, fetches analytics, runs YouTube clipping, etc. All commands output JSON for easy parsing by agents.

How it works in practice (example flow)

1. Install the skill – e.g. npx skills add gitroomhq/postiz-agent or via the Cursor marketplace.
2. Authenticate – the first time the agent runs, it opens a browser to the Postiz OAuth device flow and stores credentials.
3. Agent calls a skill – a user asks the AI “Schedule a tweet for tomorrow about our new feature”. The agent uses the postiz skill to:
   • List available Twitter integrations (postiz integrations:list).
   • Possibly fetch dynamic data (e.g., trending hashtags) via postiz integrations:trigger.
   • Upload any media (postiz upload image.png).
   • Issue postiz posts:create … with the content, schedule time, integration ID, and media URL.
4. Postiz API receives the request, queues the post, and later publishes it on the chosen platform.

What the repo actually contains

• Plugin manifests for many AI‑agent ecosystems.
• Documentation on how to install the skill in each environment.
• Instructions for authenticating and using the underlying postiz CLI.
• Helper scripts for the DeepSeek Harness bundle.

Limitations / things to note

• The repository does not implement any AI model itself; it merely connects existing agents to the Postiz service.
• The postiz CLI must be installed globally (npm i -g postiz) and the user must have a Postiz account/API key.
• Some platforms (TikTok, Instagram) require media to be uploaded to Postiz first; the README stresses this as a mandatory step.

TL;DR

postiz-agent is a collection of plugin manifests that expose the Postiz social‑media automation CLI as a skill inside many popular AI‑agent platforms, letting those agents schedule and manage posts across 28+ social networks programmatically.