• Terms of service
• Privacy policy
• Refund policy
• Acceptable use
• Support
• Agent guide

Agent guide

This guide is for people who already use an Agent such as Claude Code, Codex or Gemini CLI, and want that Agent to drive Galanty directly: picking a sample, editing copy and colors, previewing, and exporting — without writing your own ffmpeg, captioning or voice-over scripts.

Galanty does not include a drafting model of its own. Once connected, your Agent (and whichever model service it is signed in to) writes the storyboard, writes the scene code and edits the copy for you. Rendering and video export run on your own Mac. Where narration happens depends on the engine you pick: on this computer by default; with a cloud voice service, the narration text goes to that service; whether a custom-command program goes online is up to that program. With "Review the finished video" on, your signed-in Agent receives frames from the video, the narration with its timing and any open notes — and, when it redoes a scene, that scene's code and parameters.

Local help and handing over notes

Help → Product and Agent guides opens the bundled manual offline. Markdown is in Galanty.app/Contents/Resources/help/, outside app.asar. Read README.md and package.json first for the installed version and channel, then agent-guide.en.md and product-manual.en.md. MCP resources: talkframe://manual/index, talkframe://manual/agent/en, talkframe://manual/product/en (Chinese: zh).

The App Store sandbox prevents the app from launching an external Agent CLI. Connect your own Agent via MCP and reload its configuration. Then use Copy for Agent and send it the copied notes; connecting does not automatically process them. The Agent reads get_job({jobId, detail:true}) and talkframe://guide/notes, claims notes, edits, compiles and replies. Review and play the updated picture in the app.

1. What Galanty lets an Agent do

Once connected, your Agent uses these tools (15 MCP tools in total), grouped by what they do:

Getting started: pick a sample or template

• list_templates — see Galanty's built-in samples (IDs starting with S) and motion templates (bundled T numbers, or your own registered U numbers).
• fork_template — copy a sample or template into your workspace as the starting point for a new project.

Making a video

• make_video — generate a video from a one-line description, a document, or a storyboard JSON. By default it only compiles the picture and gives you a link you can watch right away — free, and it does not count against your export allowance. It only produces an MP4 (and counts toward your allowance) when you explicitly ask for an export.
• import_storyboard — submit or validate a storyboard (JSON). Use it to save changes to copy or component parameters.
• estimate_duration — no rendering; just calculates how long the current storyboard's voice-over will run and whether it fits your target length.

Watching and checking

• preview_scene — render one frame. You can tell the Agent a specific second or a line of narration and it will locate the matching scene and sentence — no need to guess a frame number.
• wait_job — wait for a job (compiling or exporting) to finish.
• review_render — has the Codex, Claude Code or Gemini command line chosen in the project settings score frames from the finished video. It goes online, and it only works in the website version with one of those CLIs installed and signed in on this computer — an API-key drafting service can't do it. Below 8/10 it redoes the weakest scene, for up to 3 rounds. You still need to watch the result yourself. The App Store version can't launch command lines; your Agent can look at frames from preview_scene itself instead.

Editing content and adding assets

• get_scene_runtime — the reference an Agent reads before writing its own scene code. Whenever you want a look of your own (3D, charts, hand-drawn, mock interfaces…), have the Agent read this first and write it. Most of the videos we're happiest with were drawn this way; templates and samples are just starting points.
• import_asset — bring in your own image, video, icon or sound effect for a storyboard's asset slot. MP4s rendered in Manim, Blender, After Effects and the like go in the same way.
• import_music — import your own background music, or an original track your Agent synthesized in code.
• search_icons — search Galanty's built-in icon library by keyword.

Managing jobs and feedback

• get_job — check a job's status, progress and output files, or list every job.
• cancel_job — stop a job that is in progress.
• report_gap — logged by the Agent whenever it finds something Galanty can't do, so it can be improved later. It only records the outcome and what was tried, never your actual script or asset content.

2. Website version vs. App Store version

Both channels can connect an Agent, but how you connect — and which files the Agent can reach — differ:

3. Connecting your Agent

One-click connect is not available yet. For now, every path is "copy a configuration, then paste it into the Agent's own config file." The sections below cover each Agent, with both channels.

Claude Code

Website version

1. Open Galanty → Settings → More (developer) → "MCP: let your Agent use the workbench."
2. Set the configuration target to Claude Code and click "Copy Galanty MCP settings."
3. Paste it into .mcp.json, merging it into any existing mcpServers — don't overwrite other servers. The copied content looks like the example below. That's the source-checkout form; in the installed app, command is Galanty's own executable and there's an extra ELECTRON_RUN_AS_NODE entry. Paste exactly what you copied — no separate Node.js install needed.

{
  "mcpServers": {
    "talkframe": {
      "command": "node",
      "args": ["<path where Galanty is installed on this computer>/scripts/mcp-server.mjs"],
      "cwd": "<path where Galanty is installed on this computer>",
      "env": {
        "DVS_WORKSPACE": "<your workspace path>",
        "DVS_DATA": "<data directory>"
      }
    }
  }
}

1. Optional: click "Copy project instructions" and paste them into your project's AGENTS.md or CLAUDE.md, so Claude Code already knows how to use Galanty.
2. Restart Claude Code, or have it reload its MCP configuration.

App Store version

Open Galanty → Settings → More (developer) → "Connect an Agent." The panel shows the local address and token. Use direct HTTP now; stdio forwarding is a future option once its package is published:

# Direct connection (nothing to install). The token only works on this computer; do not commit it to Git
claude mcp add --scope user --transport http galanty http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"

# Or use the local bridge (needs Node.js 20+; the npm package is coming soon): it hands project files to the app and downloads finished videos and preview frames to galanty-out/
claude mcp add --scope user galanty -- npx -y @galanty/mcp

Use the exact address, port and token currently shown in the app's Settings panel — just copy them as given.

Codex

Website version

1. Open Galanty → Settings → More (developer) → "MCP: let your Agent use the workbench."
2. Set the configuration target to Codex and click "Copy Galanty MCP settings."
3. Paste it into Codex's config.toml. It looks like this (again, what you copied wins):

[mcp_servers.talkframe]
command = "node"
args = ["<path where Galanty is installed on this computer>/scripts/mcp-server.mjs"]
cwd = "<path where Galanty is installed on this computer>"
startup_timeout_sec = 30
tool_timeout_sec = 600
# Approve Galanty tool calls automatically; remove the next line to confirm each call
default_tools_approval_mode = "approve"

[mcp_servers.talkframe.env]
DVS_WORKSPACE = "<your workspace path>"
DVS_DATA = "<data directory>"

1. Optional: paste the "project instructions" snippet into your project's AGENTS.md.
2. Restart Codex, or start a new session.

App Store version

Get the address and token from the same "Connect an Agent" panel, then use direct HTTP now; stdio forwarding is a future option once its package is published:

# Direct connection (nothing to install). The token only works on this computer; do not commit it to Git
[mcp_servers.galanty]
url = "http://127.0.0.1:<port>/mcp"
http_headers = { Authorization = "Bearer <token>" }
tool_timeout_sec = 600
# Approve Galanty tool calls automatically; remove the next line to confirm each call
default_tools_approval_mode = "approve"

# Or use the local bridge (needs Node.js 20+; the npm package is coming soon): it hands project files to the app and downloads finished videos and preview frames to galanty-out/
# codex mcp add galanty -- npx -y @galanty/mcp

Gemini CLI

Website version

1. Open Galanty → Settings → More (developer) → "MCP: let your Agent use the workbench."
2. Set the configuration target to Gemini and click "Copy Galanty MCP settings."
3. Paste it into .gemini/settings.json, merging it into any existing mcpServers:

{
  "mcpServers": {
    "talkframe": {
      "command": "node",
      "args": ["<path where Galanty is installed on this computer>/scripts/mcp-server.mjs"],
      "cwd": "<path where Galanty is installed on this computer>",
      "env": {
        "DVS_WORKSPACE": "<your workspace path>",
        "DVS_DATA": "<data directory>"
      }
    }
  }
}

1. Optional: paste the "project instructions" snippet into your project's AGENTS.md.
2. Restart Gemini CLI.

App Store version

# Direct connection (nothing to install). The token only works on this computer; do not commit it to Git
gemini mcp add --scope user --transport http galanty http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"

# Or use the local bridge (needs Node.js 20+; the npm package is coming soon): it hands project files to the app and downloads finished videos and preview frames to galanty-out/
gemini mcp add --scope user galanty -- npx -y @galanty/mcp

These commands were checked against each Agent's own --help output on this machine. Flag names can change with the Agent's own version; if a command doesn't match what you see, trust that Agent's own help text instead.

4. Verify the connection

Once configured, ask your Agent something simple to confirm it's connected, for example:

"What samples does Galanty have? Name a few."

The Agent should read the talkframe://samples resource and name a few samples with IDs starting with S. If it says it doesn't know what Galanty is, or reports a missing tool, see Section 8, Troubleshooting.

5. Make your first video

Once connected, try sending your Agent one of these three prompts (with your own content):

1. "Pick the sample that looks most like a product explainer, copy it, and rewrite it for our new feature. Just show me a preview — don't export yet."
2. "Turn this PDF into a 30-second vertical video: /absolute/path/to/my-document.pdf. Play it for me first."
3. "On that last video, make the music more upbeat and hold an extra second after the line at 0:05, then show me again."

The Agent will typically read talkframe://guide and the sample list first, copy the closest match, make the edit, and compile it for a watch link. It only spends an export from your allowance when you explicitly say "export" or "give me an MP4."

6. Common phrases

You don't need to know any tool names — just talk normally, and the Agent picks the right tool:

Asking for a better-looking video

These come from what worked on Galanty's own samples. They're suggestions — if you want something else, just say so:

7. Files and privacy

• Website version: the Agent and the app share the same workspace folder; your text and assets stay on your Mac. Whatever your Agent reads goes to its own model service, according to its own settings. When you choose to draft with an Agent, the text and drafting brief go to that drafting service; where narration and video review send data is covered at the top of this page.
• App Store version · direct HTTP connection: the Agent can only reach files inside the app's own sandboxed workspace, not your project folder.
• App Store version · local bridge: local file or directory paths you pass to a tool (for example import_asset's filePath, or make_video's codeDir) are uploaded into the app's workspace; finished videos and preview frames are downloaded back into your project's galanty-out/ folder.
• The token only works on 127.0.0.1 on this computer — don't commit it to Git or share it. Another program on this machine could operate your workspace if it obtained the token; keep it private.
• Export allowance and the watermark rule are the same whether or not you use an Agent: the free plan includes 7 exports a month, on your local calendar month, resetting on the 1st; Pro is unlimited and watermark-free.

See the privacy policy for the full picture, and Support for general app questions.

8. Troubleshooting

Can't connect, or the Agent reports a missing tool

• Make sure Galanty is open — both the local bridge and the direct connection need the app running.
• Website version: check that the pasted configuration and file path weren't altered, and that mcpServers really has a talkframe entry.
• App Store version: make sure you're using the address, port and token currently shown in the Settings panel.

The token expired or was reset

After you click "Reset token" in Settings, the old token stops working immediately. Remove any connection you already add-ed and re-add it with the new command.

The port changed

Galanty reuses the last port it used; if that port is taken by something else, it picks a new one. Just reopen the Settings panel and copy the address again.

The Agent can't find a file

The direct HTTP connection can only use files inside the app's workspace. To use files from your own project, import the file in the app first, or use the website version. Local-path forwarding will be an option once the bridge package is published.

Ran out of export allowance

The free plan gives you 7 exports a month, resetting on the 1st in your computer's time zone. To export now without a watermark or a limit, upgrade to Pro; otherwise keep using the free compile-and-watch link.

npx -y @galanty/mcp won't install

The local-bridge npm package hasn't been published yet. Until it is, use the direct HTTP connection instead.

The command itself errors out

Claude Code's, Codex's and Gemini CLI's own command syntax changes with their versions. The commands above were checked against the current version's --help output; if your flags look different, trust that Agent's own help text. Still stuck? Email support@galanty.cn — see Support.