Skip to content

Write HTML. Render video. Built for agents.

docs: add Studio app pages for Mac and Linux (#5063)

Miguel Ángel061a5c026520
diff --git a/docs/docs.json b/docs/docs.json
index eab955b7ae..92cecc2104 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -248,6 +248,33 @@
}
]
},
+ {
+ "tab": "Studio app",
+ "icon": "laptop",
+ "groups": [
+ {
+ "group": "Get started",
+ "pages": [
+ "studio-app/index",
+ "studio-app/connect-your-agent"
+ ]
+ },
+ {
+ "group": "Make videos",
+ "pages": [
+ "studio-app/first-video",
+ "studio-app/edit-with-the-agent",
+ "studio-app/export"
+ ]
+ },
+ {
+ "group": "Help",
+ "pages": [
+ "studio-app/troubleshooting"
+ ]
+ }
+ ]
+ },
{
"tab": "Catalog",
"icon": "grid-2",
diff --git a/docs/public/images/studio-app/export.jpg b/docs/public/images/studio-app/export.jpg
new file mode 100644
index 0000000000..a61189aa33
Binary files /dev/null and b/docs/public/images/studio-app/export.jpg differ
diff --git a/docs/public/images/studio-app/first-video.jpg b/docs/public/images/studio-app/first-video.jpg
new file mode 100644
index 0000000000..bc628dfdde
Binary files /dev/null and b/docs/public/images/studio-app/first-video.jpg differ
diff --git a/docs/public/images/studio-app/home.jpg b/docs/public/images/studio-app/home.jpg
new file mode 100644
index 0000000000..66e5fa8d7a
Binary files /dev/null and b/docs/public/images/studio-app/home.jpg differ
diff --git a/docs/public/images/studio-app/project.jpg b/docs/public/images/studio-app/project.jpg
new file mode 100644
index 0000000000..b7f0ae9e2e
Binary files /dev/null and b/docs/public/images/studio-app/project.jpg differ
diff --git a/docs/studio-app/connect-your-agent.mdx b/docs/studio-app/connect-your-agent.mdx
new file mode 100644
index 0000000000..06a9fb7821
--- /dev/null
+++ b/docs/studio-app/connect-your-agent.mdx
@@ -0,0 +1,72 @@
+---
+title: "Connect your agent"
+description: "Set up Claude Code or Codex once so the HyperFrames Studio app can build and change your videos."
+---
+
+The app makes your videos with an agent that runs on your computer: **Claude Code** or **Codex**. You set one up
+once. After that, every request you send goes to it.
+
+| Agent | You need |
+| --- | --- |
+| Claude Code | A Claude account or an Anthropic Console account. The app installs it for you. |
+| Codex | A ChatGPT account. You install it and sign in with two commands. |
+
+Runs bill to the plan of the account your agent is signed in with. To use an API key instead, change **Bill runs
+to** in **Settings** > **Permissions**.
+
+If both are ready and you have not picked one, the app uses Claude Code.
+
+## Claude Code
+
+The first time you send a request without an agent, the **Connect Claude Code** screen opens with three steps.
+
+<Steps>
+ <Step title="Install Claude Code">
+ Choose **Install Claude Code**, then **Install** in the dialog. The app runs Anthropic's official installer,
+ which puts Claude Code in your home folder. It takes about a minute.
+ </Step>
+ <Step title="Sign in">
+ Choose **Sign in to Claude**. Your browser opens Claude's sign-in. Use your Claude account or an Anthropic Console
+ account, then come back to the app.
+ </Step>
+ <Step title="Check that it answers">
+ The app checks that Claude Code runs. When it shows **Claude Code is connected**, it sends the request you
+ started with.
+ </Step>
+</Steps>
+
+If a step fails, the app shows a command you can run yourself. Choose **Copy command**, then **Open Terminal**, and
+paste it:
+
+```bash
+# Install Claude Code
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Sign in
+claude auth login
+```
+
+## Codex
+
+The app does not install Codex for you. Open **Settings** > **Agent** or the agent picker in the chat header, find
+Codex, and use its buttons:
+
+1. **Copy install command**, then paste it into a terminal:
+ ```bash
+ curl -fsSL https://chatgpt.com/codex/install.sh | sh
+ ```
+2. **Copy sign-in command** (`codex`), run it in a terminal, and sign in with your ChatGPT account.
+3. Back in the app, choose **Check again**. Codex shows **Ready**.
+
+## Switch agents
+
+Use the agent picker in the chat header, or **Settings** > **Agent**, and choose **Use** next to the agent you want.
+The choice applies to your next request.
+
+Each agent row shows its state: **Ready**, **Not signed in**, **Not installed**, or **Installed, but won't start**,
+with the button that fixes it.
+
+## Related topics
+
+- [Make your first video](/studio-app/first-video)
+- [Updates and troubleshooting](/studio-app/troubleshooting)
diff --git a/docs/studio-app/edit-with-the-agent.mdx b/docs/studio-app/edit-with-the-agent.mdx
new file mode 100644
index 0000000000..55841e6b3a
--- /dev/null
+++ b/docs/studio-app/edit-with-the-agent.mdx
@@ -0,0 +1,69 @@
+---
+title: "Change your video with the agent"
+description: "Type a change, point at the picture, draw, or comment, then send several edits to the agent at once."
+---
+
+Every change starts the same way: show the agent where, say what, and send. You can type, point at something in
+the picture, draw over it, or leave a comment at a moment in the video.
+
+<Frame caption="A project: the chat on the left, the picture with its tools in the middle, and the timeline below.">
+ <img
+ src="/public/images/studio-app/project.jpg"
+ alt="The Spring Launch project open in the HyperFrames Studio app with the chat, the picture, and the timeline"
+ />
+</Frame>
+
+## Type a change
+
+Type in the chat box, which says **Describe a change**, and press Enter. Type `@` to add moments, media, files, or
+other projects to your message.
+
+While the agent is working, Enter queues your message to run next. To change that, open **Settings** > **Agent**
+and switch **While Framey works, Send** from **Queue** to **Steer**, which stops the run and starts again with your
+words. Picks and files always queue.
+
+## Point, draw, or comment on the picture
+
+The tools under the picture, on the left:
+
+| Tool | What it does |
+| --- | --- |
+| **Select** (V) | Click an element, choose **Prompt to edit** (or press A), and describe the change. Click again to pick what contains it. |
+| **Draw** (D) | Circle or mark a spot and say what should change. Several strokes become one drawing. |
+| **Comment** (C) | Pin a comment to a spot and moment: **What should change here?** |
+
+The picture opens with **Draw**. Press Escape to go back to **Select**. Right-click an element for quick actions
+such as **Ask Framey**, **Hide**, **Bring to front**, **Replace with**, and **Delete**.
+
+You can also draw across the timeline to talk about a stretch of the video, such as "tighten this part".
+
+## Send several edits at once
+
+Picks, drawings, and comments do not run on their own. Each one becomes a row in **Pending video edits**, up to 10.
+Check them, add a note for all of them, then send them as one request with the send button, for example
+**Send 3 edits to Claude Code**. Choose **Edit note** to change a row's words, or **Delete** to drop it.
+
+## Change the timeline yourself
+
+Some changes are faster by hand. Hover a clip on the timeline to **Split** it at the playhead, **Delete** it, or
+open **Quick edit** to change a video or audio clip's **Speed**, **Volume**, and **Fade**. Drag clips to move or trim
+them.
+
+Right-click an empty gap for **Close gap**, or to ask what should fill it. The app suggests ideas that fit what
+plays around the gap.
+
+## Get inspired
+
+**Get inspired** is a library of short example moments from real videos: **Motion graphics**, **A-roll Cuts**,
+and **Mobile Ads**. Find it on Home, in a new project's empty chat, and in the **Inspirations** tab beside your files.
+Choose **Add** or **Use** to put a moment in your message as a reference, then say how to use it and send.
+
+## Undo
+
+Press Cmd+Z to undo and Cmd+Shift+Z to redo (Ctrl+Z and Ctrl+Shift+Z on Linux). Each agent run in the chat also has its own **Undo** button.
+
+## Related topics
+
+- [Export and share](/studio-app/export)
+- [Make your first video](/studio-app/first-video)
+- [Updates and troubleshooting](/studio-app/troubleshooting)
diff --git a/docs/studio-app/export.mdx b/docs/studio-app/export.mdx
new file mode 100644
index 0000000000..686a535ce9
--- /dev/null
+++ b/docs/studio-app/export.mdx
@@ -0,0 +1,56 @@
+---
+title: "Export your video"
+description: "Render a finished video file from the HyperFrames Studio app and find it in your Downloads folder."
+---
+
+When the video is ready, choose **Export** in the project's top bar. The **Export** panel opens beside the picture.
+
+<Frame caption="The Export panel with quality, format, and frame rate.">
+ <img
+ src="/public/images/studio-app/export.jpg"
+ alt="The Export panel in the HyperFrames Studio app with Quality, Format and Frame rate choices and a Render 1080p MP4 button"
+ />
+</Frame>
+
+## Choose the file
+
+| Choice | Options | Default |
+| --- | --- | --- |
+| **Quality** | **1080p** or **Project size**, plus **4K** when the project fits it | 1080p |
+| **Format** | **MP4**, **WebM**, **MOV** | MP4 |
+| **Frame rate** | 24, 30, 60 | 30 |
+
+MP4 is the right choice for sharing and uploading. Pick another format only when the place you are sending it asks
+for one.
+
+## Render
+
+Choose the render button, for example **Render 1080p MP4**. The panel shows **Getting ready**, then **Rendering**
+with the frames done so far, then **Finishing the file**. You can close the panel and keep working; the render
+continues. Choose **Cancel** to stop it.
+
+**Export** is unavailable while the agent is building the project. Wait for the run to finish.
+
+## Find the file
+
+The video is saved to your **Downloads** folder, named after the project with the date and time, for example
+`Spring Launch 2026-05-04 10.30.mp4`. When it is done, the panel shows **Export ready** with the file size:
+
+- **Open video** plays it.
+- **Show in Finder** (**Show in folder** on Linux) opens the folder.
+
+Watch the exported file once from start to end before you send it.
+
+## If the export fails
+
+- The render fails or does not start: choose the render button again. If it keeps failing,
+ ask the agent to check the project, then export again.
+- **The video was made but could not be saved to your Downloads folder**: free up space or check that the Downloads
+ folder exists, then export again.
+- **HyperFrames could not start its built-in FFmpeg**: the app may be damaged. Reinstall it from
+ [hyperframes.dev/studio](https://hyperframes.dev/studio).
+
+## Related topics
+
+- [Change your video with the agent](/studio-app/edit-with-the-agent)
+- [Updates and troubleshooting](/studio-app/troubleshooting)
diff --git a/docs/studio-app/first-video.mdx b/docs/studio-app/first-video.mdx
new file mode 100644
index 0000000000..55892c80e8
--- /dev/null
+++ b/docs/studio-app/first-video.mdx
@@ -0,0 +1,56 @@
+---
+title: "Make your first video"
+description: "Pick four parts, add your website or idea, and let the agent build your first video in the HyperFrames Studio app."
+---
+
+The **Create your first video** card on Home builds a launch video from four parts, each taken from a real launch
+video. You pick the parts, add your website or an idea, and the agent builds one video from them.
+
+<Frame caption="The first-video card: four parts, then your website or idea.">
+ <img
+ src="/public/images/studio-app/first-video.jpg"
+ alt="The Create your first video card with Hook, Proof, Turn and Call to action slots and a field for your website or idea"
+ />
+</Frame>
+
+| Part | What it does |
+| --- | --- |
+| **Hook** | Grab attention in the first seconds |
+| **Proof** | Show the product doing its job |
+| **Turn** | Flip from problem to answer |
+| **Call to action** | Land the brand and the ask |
+
+## Build it
+
+<Steps>
+ <Step title="Pick the four parts">
+ The card starts with one clip in each part. Use the shuffle button beside them for a new set, or hover a part to
+ shuffle it or browse the others.
+ </Step>
+ <Step title="Add your website or idea">
+ Type your website, such as `yourcompany.com`, or describe your idea. A website gives the agent your fonts, colors
+ and logo.
+ </Step>
+ <Step title="Choose Use this cut">
+ The request goes straight to the agent. If you are not signed in or have no agent yet, the app walks you through
+ that first, then sends it.
+ </Step>
+</Steps>
+
+## What should happen
+
+The app creates a project for your video and the agent starts building it. On your first video, a short tour
+replays how a launch video was made while yours builds, then Framey takes you to your project. In the project, the
+chat shows what the agent is doing, such as **Reading files** or **Editing files**.
+
+When the agent finishes, the video is ready to play, change, and export.
+
+## Start from your own words instead
+
+You do not need the card. Choose **Back to home**, type what you want in the prompt box, and press Enter. Type `@` to add files, other
+projects, or media. To open the card again later, choose **Take the step by step** next to **Get inspired**.
+
+## Related topics
+
+- [Change your video with the agent](/studio-app/edit-with-the-agent)
+- [Connect your agent](/studio-app/connect-your-agent)
diff --git a/docs/studio-app/index.mdx b/docs/studio-app/index.mdx
new file mode 100644
index 0000000000..7e3c8665b8
--- /dev/null
+++ b/docs/studio-app/index.mdx
@@ -0,0 +1,84 @@
+---
+title: "Get the HyperFrames Studio app"
+sidebarTitle: "Get the app"
+description: "Download the HyperFrames Studio app for Mac or Linux, open it for the first time, and sign in with your HeyGen account."
+---
+
+The HyperFrames Studio app for Mac and Linux is the easiest way to make a video with HyperFrames. You describe the video, an
+agent on your computer builds it, and you change it by typing, pointing at the picture, drawing, or commenting.
+You do not need to write code. Framey, the small
+green guide, points you to the next step along the way.
+
+<Frame caption="Home: the prompt box, your projects on the left, and Get inspired below.">
+ <img
+ src="/public/images/studio-app/home.jpg"
+ alt="The HyperFrames Studio app's Home screen with the Make something prompt box and one project named Spring Launch"
+ />
+</Frame>
+
+## Download and install
+
+<Tabs>
+ <Tab title="Mac">
+ <Steps>
+ <Step title="Download">
+ Go to [hyperframes.dev/studio](https://hyperframes.dev/studio) and choose **Download for macOS**.
+ </Step>
+ <Step title="Install">
+ Open the downloaded disk image and double-click **Install HyperFrames**. The installer copies the app into
+ Applications and shows **Checking it is really from HeyGen**, which can take a minute or two. When it says
+ **HyperFrames is in Applications**, choose **Open HyperFrames**.
+ </Step>
+ </Steps>
+
+ If your Mac's Applications folder is locked for your account, the installer puts the app in the Applications
+ folder inside your home folder instead. If it says **The download looks damaged**, choose **Download again**. If
+ it says the check **took too long**, nothing was installed: choose **Try again**.
+ </Tab>
+ <Tab title="Linux">
+ <Steps>
+ <Step title="Download">
+ Go to [hyperframes.dev/studio](https://hyperframes.dev/studio) and choose **Download** next to Linux. You get
+ one file, `HyperFrames-x86_64.AppImage`, for 64-bit Intel and AMD computers.
+ </Step>
+ <Step title="Make it runnable and open it">
+ In a terminal, in the folder you downloaded it to:
+
+ ```bash
+ chmod +x HyperFrames-x86_64.AppImage
+ ./HyperFrames-x86_64.AppImage
+ ```
+ </Step>
+ </Steps>
+
+ The AppImage is the whole app. Keep it anywhere you like and open it the same way next time.
+ </Tab>
+</Tabs>
+
+## First launch
+
+1. A short survey asks what you want to make and which agent you use. Every answer is optional, and **Skip all**
+ counts as an answer. What you make decides where **Get inspired** opens. The agent you name starts your first
+ chat if it is already set up.
+2. Home opens with the **Create your first video** card. See
+ [Make your first video](/studio-app/first-video).
+
+A notice also explains what usage data the app records. Choose **Got it** to dismiss it.
+
+## Sign in with HeyGen
+
+On first launch, the app asks you to sign in the first time you click something after the survey.
+
+1. Choose **Continue with HeyGen**. Your browser opens hyperframes.dev.
+2. Sign in there within two minutes. The browser sends you back to the app, which shows **You're in!** and carries
+ on with what you clicked.
+
+If the sign-in runs out of time, choose **Continue with HeyGen** again. If you choose **Not now**, the app asks
+again on your next click.
+You can sign in or out at any time from **Settings** > **Account**.
+
+## Related topics
+
+- [Connect your agent](/studio-app/connect-your-agent)
+- [Make your first video](/studio-app/first-video)
+- [Updates and troubleshooting](/studio-app/troubleshooting)
diff --git a/docs/studio-app/troubleshooting.mdx b/docs/studio-app/troubleshooting.mdx
new file mode 100644
index 0000000000..6a9d1a7551
--- /dev/null
+++ b/docs/studio-app/troubleshooting.mdx
@@ -0,0 +1,86 @@
+---
+title: "Updates and troubleshooting"
+description: "How the HyperFrames Studio app updates itself, and what to do when it says your agent is signed out, out of usage, or blocked."
+---
+
+## How updates arrive
+
+The app checks for a new version when it opens and every few minutes after that. When one is ready, you get a
+notification, a round update button appears in the bottom-right corner, and Framey points at it: **There's a new
+update. Click here**.
+
+1. Click the update button. It fills up as the update downloads.
+2. The app restarts by itself as soon as nothing is running: no agent run, export, or setup in progress. It reopens
+ the project you had open, and you do not lose anything.
+
+To check by hand, open **Settings** > **Updates** and choose **Check for updates**. On a Mac, **HyperFrames** >
+**Check for Updates…** in the menu bar does the same. Some updates show a short video of what is new.
+
+If an update says **The update is taking longer than it should** or **The update didn't finish**, click the update
+button and choose **Try again** to cancel it and start a new one, or **Download it instead** to get the
+latest version from the download page. **Download the latest version** in **Settings** > **Updates** also opens the
+download page. If it says **Could not check for updates**, check
+your internet connection, then try again.
+
+## The app asks me to sign in to HyperFrames
+
+Sending a request needs your HeyGen account. Choose **Continue with HeyGen** and finish in your browser within two
+minutes. If you see **No connection**, check your internet. If you see **The sign-in expired** or **HeyGen didn't
+sign you in**, choose **Try again**.
+
+## You're signed out of Claude Code
+
+The chat shows a sign-in card. Your message is kept. Choose **Sign in**, finish in your browser, and the message
+sends as soon as you are back. Choose **Use Codex instead** to send it with Codex if Codex is ready.
+
+For Codex, the chat says **Codex is not signed in**. Choose **Copy sign-in command**, run it in a terminal, then
+choose **Try again**.
+
+## My agent hit its usage limit
+
+The chat says, for example, **Claude Code hit its usage limit. It resets** at a time. This is your agent's own plan
+limit, not a HyperFrames one. Wait until it resets and choose **Try again**, or choose **Switch to Codex** (or
+**Switch to Claude Code**) if the other agent is set up.
+
+If the chat says the agent **had a problem on its side**, the agent's service is busy or down. Try again in a few
+minutes.
+
+## Claude Code blocked a step
+
+**Agent access** in **Settings** > **Agent** decides what Claude Code may do:
+
+- **Full access**, the default: it can install, use the internet, and run anything, with no checks.
+- **Auto**: it works in your project and blocks risky steps on its own.
+
+With **Auto**, a step Claude Code refuses shows as blocked in the run's work log. If the change needed that step,
+switch to **Full access** and send the request again.
+
+## The agent is not installed or won't start
+
+The chat says Claude Code **is not installed**. Choose **Try again** and the app sets it up for you. If
+Claude Code is installed but will not start, choose **Reinstall** in **Settings** > **Permissions**. See
+[Connect your agent](/studio-app/connect-your-agent) for the manual commands.
+
+## Other messages
+
+| The chat says | Do this |
+| --- | --- |
+| **… ran out of room in this chat** | Choose **Start a fresh session**. |
+| **… needs an update to use** a model | Choose the update button in the chat. |
+| **… could not reach the internet** | Check your connection, then **Try again**. |
+| **… could not finish this change** | Choose **Try again**, or say the change differently. |
+
+## Where your work is kept
+
+- **Your projects**: the hidden `.hyperframes-studio` folder in your home folder.
+- **Exported videos**: your Downloads folder.
+- **App settings and sign-in**: `Library/Application Support/HyperFrames` in your home folder on a Mac, and
+ `.config/HyperFrames` in your home folder on Linux.
+
+Each project is a plain HyperFrames project folder, so it also opens in the
+[Studio web editor](/studio/index) and with the [command line](/developers/cli).
+
+## Related topics
+
+- [Connect your agent](/studio-app/connect-your-agent)
+- [Export your video](/studio-app/export)