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 - 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 <connectionId> --text "Shipping day." # now
shapeless posts create --to <connectionId> --text "..." --at 2026-09-21T09:00:00+03:00 # at a time
shapeless posts create --to <connectionId> --text "..." --queue # next free slot
shapeless posts create --to <connectionId> --text "..." --media k1,k2 \
--first-comment "Link: https://..." # LinkedIn, X, Bluesky
shapeless posts create --to <youtubeConnectionId> --text "..." --media <clip.mp4 key> \
--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 <cursor> # the next page back
shapeless jobs show <id> # transcript summary + outputs
shapeless jobs tail <id> # 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 <id> and this one --media-key workspace-assets/<account>/logo.png
# Resume a stuck or failed run - history is rebuilt server-side
shapeless jobs continue <id> keep going, but make the second post shorter --watch
shapeless jobs stop <id>
Posts: the queue
shapeless posts list --status proposed
shapeless posts show <id>
shapeless posts approve <id> <id> <id> # proposed -> scheduled [publish]
shapeless posts dismiss <id>
shapeless posts publish <id> # out, now [publish]
shapeless posts mark-posted <id> --url https://...
Agents, Brand Memory, assets
shapeless agents list
shapeless agents create --name "Daily reach" --prompt "..." --days mon,thu --hours 9
shapeless agents edit <id> --status paused # or: shapeless agents pause <id>
shapeless agents wake <id> # 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, 32 of
them: 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/<id> -
so an agent can hand the human back a link to what it just did.
jobs_brief <id> 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 <id> 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),
Smithery,
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: shapelessai-ai-sdk),
,
,
,
The API
Everything above rides one documented contract:
shapelessai.com/docs/api - every route, the scope each needs,
rate limits, and what deliberately refuses an API key. Machine-readable at
/api/openapi.json.
| Page | What it answers |
|---|
| /docs | Start here: key, MCP URL, CLI, the three moves |
| /docs/posts | Create, schedule, queue, media, first comment, every refusal |
| /docs/platforms | Limits and rules per platform, live from GET /api/platforms |
| /docs/api | Every route a key opens, and the scope it needs |
| /docs/cli | The shapeless command |
| /docs/mcp | The hosted MCP server and its tools |
| /docs/jobs | Durable runs |
| /docs/brand-memory | The account's durable knowledge |
| /docs/auth | Keys, scopes, OAuth, rate limits |
Support and privacy
