ShapelessAI

ShapelessAI

ShapelessAI runs your social presence: it drafts, schedules, and publishes content across your connected platforms, holds your Brand Memory, and keeps standing agents working while you sleep.

This repo is the public home of the agent surface: the shapeless CLI, the MCP server, the Claude Code plugin, and the issue tracker. Your agent or script drives a ShapelessAI account: write and schedule posts, create jobs and resume stuck ones, approve and publish, edit Brand Memory, manage the standing agents.

The documentation lives at [shapelessai.com/docs](https://shapelessai.com/docs) - routes, scopes, platform limits, refusal codes, one page per subject. Every page also answers raw Markdown: append .md to its path (https://shapelessai.com/docs/posts.md) or send Accept: text/markdown. An agent that wants all of it in one fetch should read shapelessai.com/llms-full.txt.

Install

npx shapelessai --help      # one-off

npm i -g shapelessai # keeps shapeless on your PATH

Node 20 or newer.

Authenticate

Mint a key in the studio: Settings -> API keys (/studio/api-keys). Give it only the scopes the caller needs - read, write, or publish. Only publish can put content out.

shapeless login             # paste the key; we verify it and store it 0600

export SHAPELESS_API_KEY=slk_... # or: env var, beats the stored key

Config lives in ~/.config/shapeless/config.json. SHAPELESS_BASE_URL overrides the API host (default https://shapelessai.com). shapeless logout forgets the local copy; revoke the key itself in the studio.

Every command takes --json to print the raw API response, and --help.

Post

Write it yourself and put it on the rail - now, at a time, or in the account's next free queue slot. Needs the publish scope.

shapeless connections                     # the accounts and their ids

shapeless platforms # limits, media rules, settings schema (no key needed)

shapeless posts create --to --text "Shipping day." # now shapeless posts create --to --text "..." --at 2026-09-21T09:00:00+03:00 # at a time shapeless posts create --to --text "..." --queue # next free slot shapeless posts create --to --text "..." --media k1,k2 \ --first-comment "Link: https://..." # LinkedIn, X, Bluesky shapeless posts create --to --text "..." --media \ --title "The video title" --settings '{"privacyStatus":"unlisted"}'

The MCP tool is posts_create with the same arguments: connectionId, text, mediaKeys, title, scheduledAt or queue: true, settings, firstComment. Read platforms_list first for the platform's limits and its settingsSchema.

Free plan: ten posts a day on the rail, counted on the UTC day each post goes out on, so a week planned ahead is ten a day rather than ten in total. The eleventh answers 402 {code: "free_daily_cap", limit, day, resetsAt}, which names the day that is full. X bills per post, so Free posts to X once a day and without links (402 free_x_daily_cap, free_x_link); the $9 Scheduler plan lifts the daily cap and carries 150 X posts a month, and the agent plans have no cap. Composing, scheduling and publishing never spend credits, and Free also carries 125 credits a month for the agent team. Details: shapelessai.com/docs/posts.

Jobs: durable runs

A job is a run the server keeps going whether or not you stay connected - the right shape for agents and cron.

# Fire and forget

shapeless jobs create draft three posts about our beta launch

Watch it live (tails the event stream, falls back to polling)

shapeless jobs create plan this week --label "Weekly plan" --budget 2.50 --watch

Come back later

shapeless jobs list # 200 newest; prints a cursor if older jobs exist shapeless jobs list --before # the next page back shapeless jobs show # transcript summary + outputs shapeless jobs tail # re-attach to the live stream

Put files on the message - the agent sees the image, not just its name

shapeless jobs create does this thumbnail work? --attach ./thumb.png --attach ./notes.md shapeless jobs continue and this one --media-key workspace-assets/ /logo.png

Resume a stuck or failed run - history is rebuilt server-side

shapeless jobs continue keep going, but make the second post shorter --watch

shapeless jobs stop

Posts: the queue

shapeless posts list --status proposed

shapeless posts show shapeless posts approve # proposed -> scheduled [publish] shapeless posts dismiss shapeless posts publish # out, now [publish] shapeless posts mark-posted --url https://...

Agents, Brand Memory, assets

shapeless agents list

shapeless agents create --name "Daily reach" --prompt "..." --days mon,thu --hours 9 shapeless agents edit --status paused # or: shapeless agents pause shapeless agents wake # run it now [publish]

shapeless brain ls shapeless brain get positioning.md shapeless brain put voice.md --file ./voice.md # or pipe on stdin shapeless brain import ./pitch-deck.pdf shapeless brain export --out brain.zip

shapeless assets list shapeless assets upload ./logo.png shapeless connections

MCP server

The hosted server is `https://shapelessai.com/mcp`. Add that URL to any host that speaks remote MCP - Claude (Settings -> Connectors -> Add custom connector), ChatGPT (Developer mode), Claude Code, Cursor, Codex, VS Code, Gemini CLI - and it opens a ShapelessAI tab to sign in and allow. OAuth, no key. The steps for each host, in the vendor's words, are at shapelessai.com/connect.

A client that cannot open a browser (the Agent SDK, a CI job, a self-hosted agent) skips OAuth: send an API key from Settings -> API keys as Authorization: Bearer slk_... to the same URL. Any MCP client that sets a header works; the scope is the key's.

curl -s https://shapelessai.com/mcp -H "Authorization: Bearer $SHAPELESS_API_KEY" \

-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

claude mcp add --transport http --scope user shapeless https://shapelessai.com/mcp   # then /mcp -> Authenticate

codex mcp add shapeless --url https://shapelessai.com/mcp && codex mcp login shapeless gemini mcp add --transport http shapeless https://shapelessai.com/mcp

The same tools (posts_create, jobs_create, posts_approve, brain_write, ...) also run locally: shapeless mcp speaks MCP on stdio with the API key from shapeless login, and adds the tools that read your disk (assets_upload, brain_import, and files on a job message). Every tool carries a title and annotations - read-only tools run freely, anything that publishes, spends or overwrites is flagged destructive so a host asks you first - and each description names the scope it needs.

Beyond the account tools, every tool our own studio agent holds is its own MCP tool too: generate_image, generate_footage, edit_footage, render_carousel, speak, caption_file, web_search, x_pulse and the rest. Each answers the files it made as media keys you can publish with posts_create. The table with what each one costs is at shapelessai.com/docs/mcp; tools_list reads it live.

A job is a conversation, so work passes both ways between your terminal and the web app:

• Every job result carries a `url` - https://shapelessai.com/studio/c/ - so an agent can hand the human back a link to what it just did.
• `jobs_brief ` is the cheap read before replying: the last 30 messages clipped, reasoning and tool-activity dropped, an artifact inventory and post counts per queue status. Deterministic, no model in the loop. jobs_get still gives the full transcript.
• `jobs_list` answers 200 jobs at a time, newest first, with a nextCursor; pass it back as before to walk further into the history.
• `jobs_tail ` watches a job's run (60 seconds max, 200 events) and returns the events plus a cursor to resume from; a job with no run stream to attach to answers {live: false} instead of erroring.
• `jobs_create` and `jobs_continue` take files: files (absolute local paths - .md/.txt ride inline, images, video, audio and PDF are uploaded here) and mediaKeys (anything already in the account, e.g. what assets_upload returned). Up to 6 per message. They land on the message the human sees in the studio, and the agent reads them for real - an image's pixels are inlined for that turn, not just its filename.

There is one prompt, `continue` (argument: id), which Claude Code surfaces as a slash command: it loads that conversation's brief and tells the agent to reply into the same thread with jobs_continue.

Running the stdio server instead of the hosted one - Claude Code:

claude mcp add shapeless -e SHAPELESS_API_KEY=slk_... -- npx shapelessai mcp

Claude Desktop (claude_desktop_config.json), and other stdio-only hosts:

{

"mcpServers": { "shapeless": { "command": "npx", "args": ["shapelessai", "mcp"], "env": { "SHAPELESS_API_KEY": "slk_..." } } } }

Without the env var the server uses the key stored by shapeless login.

Agent Plugins (Cursor, Kiro, Copilot, Codex) and Gemini CLI

plugins/shapeless is also an Agent Plugins 1.0 package (plugin.json, mcp.json, skills/), so any client that loads that format installs the hosted MCP server and the skill from this repo. Gemini CLI reads gemini-extension.json at the root:

gemini extensions install https://github.com/FirstClassTree/shapelessai

Claude Code plugin

This repo is also a plugin marketplace. The shapeless plugin wires up the hosted MCP server and ships a skill that teaches Claude the ropes - scopes, the post queue, when to touch Brand Memory:

/plugin marketplace add FirstClassTree/shapelessai

/plugin install shapeless@shapeless

Then run /mcp, pick shapeless and choose Authenticate - a browser tab signs you in once.

Where else ShapelessAI is listed

The same server and skill, installable from the registry your client already reads:

• MCP: Official MCP Registry (com.shapelessai/shapeless), Glama, LobeHub, ModelScope
• Apps, plugins and skills: ChatGPT, cursor.directory, ClawHub, skills.sh, claude-plugins.dev, ModelScope skills, 360 SkillHub
• Packages: Docker Hub, conda, Snap, Chocolatey, npm (AI SDK tools: [shap