frameshell

Connect your agent.

Frameshell has no AI of its own. You bring the agent you already use, or pick one below; it edits the video while you watch it in the app. Set it up once and it works in every project.

Which one?

All of them can edit your video. The difference is the app you talk to it in and the account it needs.

AgentYou talk to it inAccount it needs
Claude Desktop Claude's chat app. No terminal.
Claude Code The terminal inside Frameshell
Codex The terminal inside Frameshell
Gemini CLI The terminal inside Frameshell
OpenCode The terminal inside Frameshell
Pi The terminal inside Frameshell

New to all this? Start with Claude Desktop if you have a Claude account, or Claude Code if you pay for Claude.

Claude Desktop Easiest

You chat with Claude in its own app, and it edits the project open in Frameshell through Frameshell's MCP connection.

  1. Install Claude

    Download it from claude.com/download and sign in. macOS and Windows; on Linux there is a beta for Ubuntu and Debian.

  2. Connect Frameshell to Claude

    In Frameshell 0.8 or later, open a project and click Connect Claude Desktop above the terminal. Frameshell shows what it adds to Claude's settings, keeps the other servers as they are, and backs the file up first.

  3. Or add it by hand

    On Linux or with an earlier version: in Frameshell choose File → Install 'frameshell' Command in PATH (the .deb package has it already). Then in Claude open Settings → Developer → Edit Config, put this in the file, keeping anything already in mcpServers, and save:

    macOS
    { "mcpServers": { "frameshell": { "command": "/usr/local/bin/frameshell", "args": ["mcp"] } } }
    Windows
    { "mcpServers": { "frameshell": { "command": "cmd", "args": ["/c", "%LOCALAPPDATA%\\Frameshell\\desktop\\bin\\frameshell.cmd", "mcp"] } } }
    Linux
    { "mcpServers": { "frameshell": { "command": "/usr/bin/frameshell", "args": ["mcp"] } } }

  4. Restart Claude

    Quit Claude completely and open it again. Frameshell then shows among its connectors.

  5. Try it

    With your project open in Frameshell, ask Claude: “What videos does my Frameshell project have?” Claude works on the project of the Frameshell window you used last. With versions before 0.8, tell it where the project is.

Claude Code

Anthropic's agent for the terminal. It finds the Frameshell skill in your project by itself.

  1. Install it

    Paste one line in a terminal: Terminal on macOS, PowerShell on Windows. It needs no other software.

    macOS, Linux
    curl -fsSL https://claude.ai/install.sh | bash
    Windows
    irm https://claude.ai/install.ps1 | iex

  2. Start it in Frameshell

    Open your project, click into the terminal panel, type claude and press Enter. The first time, it opens your browser to sign in.

  3. Ask

    “Remove the silences and the takes I repeated.” It asks before running commands; from Frameshell 0.7, new projects let it run Frameshell's own without asking.

Codex

OpenAI's agent for the terminal. It reads the project's AGENTS.md, which points it at the Frameshell skill.

  1. Install it

    Paste one line in a terminal.

    macOS, Linux
    curl -fsSL https://chatgpt.com/codex/install.sh | sh
    Windows
    powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

  2. Start it in Frameshell

    In the project's terminal type codex. Choose Sign in with ChatGPT the first time.

  3. Ask

    In a project made before Frameshell 0.7, start with “Read .claude/skills/frameshell/SKILL.md first.” Newer projects tell it themselves.

Gemini CLI

Google's agent for the terminal. It reads the project's GEMINI.md. Google replaced it with Antigravity CLI for free accounts in June 2026; with an API key or a paid plan it keeps working.

  1. Install it

    With Homebrew on macOS, or with npm where Node.js is installed.

    macOS
    brew install gemini-cli
    Any
    npm install -g @google/gemini-cli

  2. Start it in Frameshell

    In the project's terminal type gemini and choose how to sign in.

  3. Ask

    As with Codex, a project made before Frameshell 0.7 needs “Read .claude/skills/frameshell/SKILL.md first.”

OpenCode

An open source agent that works with many model providers. It loads the Frameshell skill from the project by itself.

  1. Install it

    Paste one line in a terminal. On Windows, Scoop or Chocolatey install it too.

    macOS, Linux
    curl -fsSL https://opencode.ai/install | bash
    Windows
    scoop install opencode

  2. Start it and pick a model

    In the project's terminal type opencode, then /connect to sign in to a provider and /models to choose one.

  3. Ask

    “Add subtitles from what is said.”

For advanced users: Pi

Pi is a small open source agent that works with many providers. It runs commands without asking first, so it can change or delete files on its own. Use it if you are comfortable with that, or inside a container.

macOS, Linux
curl -fsSL https://pi.dev/install.sh | sh
Windows
powershell -c "irm https://pi.dev/install.ps1 | iex"

In the project's terminal type pi, then /login. It reads AGENTS.md; in older projects, ask it to read .claude/skills/frameshell/SKILL.md first.

Things to ask

Talk to it like you would to an editor. It works in steps and you see each one on the timeline.

  • “Remove the long pauses and the takes I repeated.”
  • “Add subtitles, two words at a time, at the bottom.”
  • “Make a vertical version for Reels and TikTok.”
  • “Put a title card with the episode name at the start.”
  • “Export it for YouTube.”

Changed your mind? Open History in Frameshell and revert any change, yours or the agent's.

Windows: the first start

Frameshell is not signed for Windows yet, so the first time Windows protects you with a blue SmartScreen window. Click More info, then Run anyway. It asks once.

If something does not work

  • “frameshell: command not found” outside Frameshell: choose File → Install 'frameshell' Command in PATH, then open a new terminal.
  • The agent does not know Frameshell: start it from the terminal inside Frameshell, in the project folder, or ask it to read .claude/skills/frameshell/SKILL.md.
  • Claude Desktop does not list Frameshell: check the config file is valid JSON, then quit Claude completely and open it again.
  • Anything else: run frameshell doctor in the project's terminal and send what it prints in a GitHub issue.

Open an issue