Docs

Set up your agent, then everything gifgif does from the terminal, the browser and the HTTP API.

Agents

gifgif is a tool your coding agent calls. There is no model inside it and no API key to set: your agent looks at the frames and picks the moment, and gifgif makes the smallest file that fits and measures how close it stayed.

Claude, ChatGPT and other apps

Nothing to install. Add this address as a connector:

Connector URL

https://gifgif.dev/mcp

In Claude: Settings → Connectors → Add custom connector. In ChatGPT: Settings → Apps → Create. Paste the URL, then sign in with your email. Claude Code can use it too, without Node:

Terminal

claude mcp add --transport http gifgif https://gifgif.dev/mcp

Your assistant gives you an upload link; open it and drop the video in. A coding agent can upload the file itself. Results are always links, kept in your Library, where the connection shows as a connected app you can revoke.

Tool	What it does
`gif_upload`	A one-time link where the person drops the video in (or a curl command for a file on the same machine). Everything starts from the upload it names.
`gif_info`	A file's size, dimensions, frame rate and length.
`gif_frames`	A contact sheet of frames with timestamps, or one frame, so the assistant can see the clip and pick the moment.
`gif_optimize`	Fit a clip under a size limit with any edits (trim, crop, captions, blur and more). The result is always a link.
`gif_job`	Wait for, or cancel, a background job.
`gif_links`	List the links you have made.
`gif_update`	Change a link's title, alt text or how long it lasts.
`gif_delete`	Remove a link and its file.
`gif_targets`	The size guide: 1, 3, 5 and 10 MB and where each fits, and the shortcuts that pick one.

The sections below set gifgif up as a local server instead, which reads files straight off your machine.

Claude Code

Terminal

claude mcp add gifgif -- npx -y gifgif mcp
npx gifgif login

Cursor

Add gifgif to ~/.cursor/mcp.json, or to .cursor/mcp.json in one project:

Cursor settings

{
  "mcpServers": {
    "gifgif": {
      "command": "npx",
      "args": ["-y", "gifgif", "mcp"]
    }
  }
}

Then sign in once

npx gifgif login

Other MCP clients

Any client that runs local MCP servers takes the same entry in its settings:

MCP settings

{
  "mcpServers": {
    "gifgif": {
      "command": "npx",
      "args": ["-y", "gifgif", "mcp"]
    }
  }
}

Then sign in once

npx gifgif login

gifgif login opens your browser. Approve the code there, and the CLI and your agent can share links that last 90 days. Without it, your agent can still make files on your machine when ffmpeg is installed, but it can't share them or use the hosted optimizer.

Tools your agent gets

Tool	What it does
`gif_info`	A file's size, dimensions, frame rate and length.
`gif_frames`	A contact sheet of frames with timestamps, or one frame, so the agent can see the clip and pick the moment.
`gif_optimize`	Fit a clip under a size limit with any edits (trim, crop, captions, blur and more), and share it when asked.
`gif_share`	Upload a finished file and get a link.
`gif_links`	List the links you have made.
`gif_update`	Change a link's title, alt text or how long it lasts.
`gif_delete`	Remove a link and its file.
`gif_job`	Check on, or cancel, a background job.
`gif_targets`	The size guide: 1, 3, 5 and 10 MB and where each fits, and the shortcuts that pick one.
`gif_doctor`	Check ffmpeg, the encoder and your sign-in when something fails.

Then ask in plain words: "Make a GIF of the last 8 seconds of demo.mov for Slack and give me a link."

Start in a terminal

The same tool without an agent:

Terminal

npm install -g gifgif
gifgif login          # opens your browser to sign in
gifgif optimize demo.mp4 --max 3mb --share

Node 24 or newer. With ffmpeg installed, clips are processed on your machine; without it, on gifgif.dev.

Editor

No agent handy? The editor does it in your browser: drop a clip, trim and crop it, pick a size, and copy the link. You can try it without an account: 5 clips a day, with links that last 24 hours. Sign in and those links move to your account.

The editor in real time: the sample clip, trimmed on the filmstrip, cropped by drawing on it, fitted under Slack's 3 MB limit, shown beside the original, and its link copied.

Links

A link is handed out only once its file is finished, and the file never changes afterwards. The link is the file's share page: send it to someone or paste it in a chat, and Discord, iMessage, Telegram and Slack show a preview. Whoever opens it sees the file, its size and the limit it fits, and can download it; a GIF's page offers an MP4 copy too. For a README, a pull request or docs, copy the Markdown or HTML instead: they embed the file itself. Links are unlisted and not indexed by search engines.

Rename a link, change how long it lasts, or delete it in your Library, with gifgif edit and gifgif delete, or by asking your agent.

CLI

Command	What it does
`gifgif login`	Sign in through your browser. The CLI and your agent share the sign-in. `--invite CODE` redeems an invite instead.
`gifgif logout`	Sign this computer out: its token is revoked and removed from the config file.
`gifgif optimize <file>`	Fit a clip under a size (`--max 3mb`; add `--format mp4` for video), with any edits, and optionally `--share` it. Several files join end to end.
`gifgif frames <file>`	A contact sheet of frames with timestamps, for picking trim points.
`gifgif info <file>`	Size, dimensions, frame rate, duration.
`gifgif share <file>`	Upload a finished file and get a link.
`gifgif links`, `edit`, `delete`	List your links, change a title or lifetime, remove one.
`gifgif job <id>`	Check a background job started with `--async`.
`gifgif doctor`	Check ffmpeg, the encoder, and your sign-in.

Edits: --trim 2-8, --crop left-half, --speed 1.5, --reverse, --boomerang, --caption "Hi @top 2-5", --blur REGION, --pixelate REGION, --zoom REGION, --brightness, --contrast, --saturation, --grayscale, --fade-in, --fade-out, --border 8,white, --corners 24, --transparent "#00ff00", --mute. Output: --format gif|mp4|webp, --objective smallest|quality|fastest. Run gifgif --help for everything.

Sizes

Pick the size the place takes and gifgif does the rest: it lowers the width and frame rate until the file fits, at the best quality that size allows. Any size works, and --format mp4 makes a video for pages that play one.

Size	Fits
`--max 1mb`	email
`--max 3mb`	Slack
`--max 5mb`	a GitHub README, Notion, X or a web page
`--max 10mb`	Discord, a GitHub pull request or issue, Linear or Jira

Or let a shortcut pick the size, with a starting width and frame rate: --for email (1 MB), slack (3 MB), github (5 MB, a GitHub README), discord (10 MB) or web-video (a 5 MB MP4).

HTTP API

Send authorization: Bearer <token>. gifgif login saves a token to your config file; for CI and scripts, create one in your Library and set it as GIFGIF_SHARE_TOKEN. The CLI is a thin client over these calls.

Call	What it does
`POST /api/optimize?max=3mb`	Upload a clip (raw body); get the optimized file's links and the measured result. Same query names as the CLI flags (`format=mp4`; `for=slack` works too).
`POST /api/jobs`, `GET /api/jobs/{id}`	The same as a background job.
`POST /api/upload`	Store a finished file; `expires=7d` for a shorter life.
`POST /api/sources/multipart?name=&size=`	A clip over 100 MB, in parts: `PUT /api/sources/{id}/parts/{n}` for each, then `POST /api/sources/{id}/complete`. Pass `source={id}` instead of a body to the calls above. The CLI, the MCP server and the editor do this on their own.
`POST /api/frames`, `POST /api/info`	A contact sheet or the clip's details.
`GET /api/me/links`	Your links, newest first.
`DELETE /api/me/token`	Revoke the token making the call (what `gifgif logout` does).
`PATCH /api/g/{id}`, `DELETE /api/g/{id}`	Change a link's title, description or lifetime; remove it.
`GET /oembed?url=`	oEmbed for a link.

Limits

A free account: 25 clips a day, 500 MB a day, uploads up to 150 MB, links kept up to 90 days. Without an account, the editor allows 5 clips a day and its links last 24 hours. Pro: 100 clips a day, 1,000 a month, 5 GB of uploads a day and files up to 500 MB; links never expire. The limits are the same whether you use the website, the CLI or an agent.