# For agents

> How ChatGPT, Claude, Codex and other AI agents connect to Eddy and drive an edit, and what they can't do.

Source: https://eddystudio.ai/docs/for-agents/ · Written from the app's source code, last checked 3 November 2026; generated tables are rebuilt from the source on every build; not every behaviour hand-tested in the beta build

Eddy is built to be driven by AI agents as well as by hand. An agent connects over MCP (the Model Context Protocol) and can do the whole job: check that Eddy is ready, find footage, record, start an edit, check on it, look at frames, and ask for changes.

## If you are an agent reading this

- Every page here has a plain Markdown copy: add `.md` to the page address, e.g. [/docs/for-agents.md](https://eddystudio.ai/docs/for-agents.md).
- [/llms.txt](https://eddystudio.ai/llms.txt) lists every page. [/llms-full.txt](https://eddystudio.ai/llms-full.txt) is all of them in one file.
- Eddy runs on the creator's Mac. You can only use it while Eddy Studio is open there and the creator has connected you.
- Never tell a creator a video is published or uploaded. Eddy can't do that for you; see [What agents can't do](#what-agents-can-t-do).
- Want one prompt to paste into ChatGPT or Claude? See the [Agent quickstart](https://eddystudio.ai/docs/agent-quickstart/).

## Connect an agent on the same Mac

In Eddy, open the **Doctor** sheet and use the **Connect your agent** card. It adds Eddy to Claude Desktop, Claude Code or Codex in one click. It only changes Eddy's own entry, and for Claude Desktop and Codex it backs up the settings file first. The card also shows the setting to paste by hand if you prefer.

A local agent gets the creator tools below and also the full set of detailed editor tools, one per action in the app, for precise timeline work.

## Connect ChatGPT or claude.ai (remote access)

Remote access is off until the creator turns it on in the Doctor sheet (**Use Eddy from ChatGPT and claude.ai**).

1. With remote access on, the Mac opens one outgoing connection to Eddy's relay at `relay.eddystudio.ai`. The Mac needs no open port.
2. In ChatGPT (developer mode connectors) or claude.ai (custom connectors), add the address the card shows.
3. A sign-in page opens and asks for the 8-character code shown on the Mac. The code works once and expires after 10 minutes, and each sign-in gets 5 tries. This shows the person signing in can see Eddy on the Mac.

For remote access, the relay keeps the connected apps, their grants, scrambled (hashed) tokens and your Mac's network name (which often includes your name), plus the sign-in code for its 10 minutes. It does not store footage or the content of calls. Access tokens last an hour and refresh tokens rotate; a refresh token used twice ends the grant. The card lists every connected app with a **Remove** button, which cuts that app off at once.

A remote agent gets the creator tools only, never the detailed editor tools.

## The creator tools

There are 15 creator tools. Every agent gets them, local or remote. The descriptions are the app's own words, the ones your agent reads.

| Tool | Name in the app | What it does (the app's own words) | Read-only |
| --- | --- | --- | --- |
| `eddy_get_started` | Get started with Eddy | Check Eddy is ready to edit before anything else: Studio running, the creator's AI editor signed in, fast transcription, their brand look, and edits in progress, with the next step. | Yes |
| `eddy_sign_in` | Sign in the AI editor | Start signing Eddy in to the creator's own ChatGPT or Claude account, which Eddy edits with. | No |
| `eddy_find_footage` | Find footage | Find the creator's recent recordings when they say "edit yesterday's recording" or don't know the path: Eddy recordings, Movies, Desktop and Downloads, newest first, each with the path for eddy_edit_this and its shape. | Yes |
| `eddy_record` | Record | Record the creator's screen and/or camera with Eddy's native recorder when they say "record this": start, pause, resume, stop, status, or list the inputs. | No |
| `eddy_edit_this` | Edit this footage | Edit this recording into a finished YouTube long, 1 to 3 Shorts, or both, when the creator says "edit this". | No |
| `eddy_get_edit` | Check an edit | Check how an edit is going when the creator asks: stage, progress, a one-line status, and once ready the long and Shorts with their file paths. | Yes |
| `eddy_watch` | Watch the finished edit | Look at the finished edit before describing it: frames of the long or a Short as images, at given seconds or spread evenly across it (a contact sheet). | Yes |
| `eddy_refine` | Refine the edit | Change a finished edit by prompt when the creator asks ("make the intro punchier", "Short 2 needs a stronger hook", "cut the tangent at 4:10"). | No |
| `eddy_resume_edit` | Resume an edit | Carry on an edit that failed or was interrupted (Eddy Studio closed) from the stage it stopped in. | No |
| `eddy_stop_edit` | Stop an edit | Stop a running edit when the creator asks: its import, editing and rendering. | No |
| `eddy_draft_video_details` | Write the video details | Write the YouTube title and description for the long or a Short of a finished edit, so Eddy's Export sheet opens with them filled in. | No |
| `eddy_change_look` | Change the brand look | Set or refine the creator's brand look for motion graphics when they describe their brand or ask for a change ("punchier", "a little less bounce", "fewer graphics", "use my channel's colours"): fill it from their YouTube channel, set the name, colours, light or dark, lettering and how the graphics move. | No |
| `eddy_list_projects` | List projects | List the creator's Eddy projects, newest first: name, length and when each was last opened. | Yes |
| `eddy_set_up_loop` | Set up the creator's loop | Read, set up or change how this creator makes a video, from the plan to the release: what to call them, their channel and niche, their shows (most have one; each has a name, its video names, the days and time they film it, and can be paused for a break), where their footage comes from, Shorts per video, whether Eddy grills them from the transcript before the edit, their own skill for planning, editing or the release (or Eddy's built-in step), and what goes out beside YouTube. | No |
| `eddy_read_transcript` | Read the transcript | Read what the creator said in a recording, as lines with the m:ss each starts at, before an edit: to grill them on the cut quoting their own words, or to plan the Shorts. | No |

_Generated from the app's source code each time these docs are built._

A typical run: `eddy_get_started`, then `eddy_find_footage` and confirm the file with the creator, then `eddy_edit_this`, `eddy_get_edit` every few minutes until it's ready, `eddy_watch`, and `eddy_refine` for changes. An edit takes hours, not minutes. No measured time is published yet (see [A real recording](https://eddystudio.ai/docs/real-edit/)), so don't promise the creator a time.

## Ready-made prompts

Eddy also offers MCP prompts. In apps with a prompt menu (Claude Desktop, for example) the creator can pick one instead of typing.

| Prompt | Shows up as | What it starts |
| --- | --- | --- |
| `edit-this` | Edit this video with Eddy | Edit a recording end to end into a YouTube long plus Shorts, or Shorts alone. |
| `set-up-my-loop` | Set up my video loop with Eddy | First run: set up how you make each video (plan, film, edit, review, release), with your own skills where you have them. |
| `run-my-loop` | Run my video loop with Eddy | Take one video through your loop: plan it, film it, edit it once the footage is in, review it, release it. |

_Generated from the app's source code each time these docs are built._

## What agents can't do

These stay with the person at the Mac:

- **Publish or upload.** A YouTube upload only starts from the creator's own click in the Export sheet. No agent, AI Tool or background job can start one.
- **Turn remote access on or off**, or add and remove connected apps.
- **Sign in to YouTube** for the creator.
- **Record the creator's verdict** on an edit, or resolve review comments.

## The local HTTP API

Behind the app is a local HTTP API on the Mac. It needs a secret that changes every launch, and it only answers on the Mac itself. It is internal and may change without notice. Use MCP instead.