---
title: "Agents"
description: "Describe a new animation or narrated film, compare its takes, and open the version you want to edit."
canonical: "https://terminal.lottiefiles.com/docs/agents/"
last_updated: 2026-10-30
---

# Agents

Describe a new animation or narrated film, compare its takes, and open the version you want
to edit.

When you’re elsewhere, the terminal tells you when an idea is ready or needs you.

## Before you start

Install Claude Code, Codex or Kimi Code and sign in on this computer: run `claude` once, or
`codex login` or `kimi login`. Creator Terminal uses that account without a separate AI API
key. The agent process runs here; model requests go to your agent provider. Frolic compiles
here too, but still needs the signed-in AI agent.

In **Settings** (`F2`), leave **App › AI features** on. When it is off, Agents Mode is
unavailable. Turning it off stops all active agents and closes the view. The same switch
controls the [copilot](https://terminal.lottiefiles.com/docs/copilot.md) and zen's conversation.

The **Engine** and directed films also need a LottieFiles sign-in and a network connection.
**Frolic** needs no LottieFiles sign-in. See [Choosing the copilot or
agents](https://terminal.lottiefiles.com/docs/concepts/copilot-and-agent-takes.md).

## The agent view

Press `⌃O` (or click **Agents Mode** in the left panel, **View › Agents Mode**, or
**Agents** in the palette). The studio gives way to a view with no score (the timeline) and
no editing panels. After your first idea, your threads run down the left, with a conversation for
each idea. Each turn shows your message, its answer, then the takes it made. The newest
turn sits just above the box; scroll back through earlier iterations. The newest turn’s
cards are larger, keeping their proportions within about 45% of the window’s height.

Where the terminal shows no pictures, takes and their versions play in coloured block
characters, with the same detail as the studio stage. Animation cards use the thread’s clock;
compare plays all takes together.

![The new idea page asks what you want to make, with animation and film choices.](https://terminal.lottiefiles.com/docs/assets/shots/more-agents-new-idea.png)

- **What do you want to make?** Choose **An animation** or **A film, narrated with music**
  (`⌃T` switches between them). Describe your idea in the box below and send it. It becomes
  a thread with its own agent. An open-ended ask ("a logo sting for the launch") gets two to
  four takes, each a different idea; a clear one gets one.
- **Compare the takes**: choose **compare ›** on the newest turn’s summary (with two or
  more takes), or press `⌃G`. The board shows equal-size cards, all playing on one clock. A
  shorter take holds its last frame until the longest ends, then all loop together. Click or
  drag the scrubber to seek all of them. On a narrow screen, one take is big and the others
  show letters and direction names where they fit, else letters; in a small window, the
  names sit beside the picked picture. Click `‹` or `›` to pick the previous or next take.
  **conversation ›** or `⌃G` returns to the conversation. Switching ideas or starting a new one opens the conversation.
- **Pick a take**: `⇥` or `⇧⇥` moves between the message box (or its open question) and
  the takes. On the takes,
  `←` `→` picks through the conversation’s cards and scrolls to each; in compare it picks
  among the latest takes. `space` plays or pauses, and `h` `l` steps one frame and pauses. `⏎`
  opens the picked take's page (a double-click on its card does too). `esc` returns to the
  box or its open question. With no open question, typing a letter returns to the box and
  types it there. Clicking a card picks it without moving keyboard focus.
- **A take's page** shows its version big and its versions newest first, on the thread's
  clock. `↑` `↓` chooses a version while the takes have focus (`⇥` returns focus from the
  box). `c` switches between **one** and **side by side**, comparing with the version before
  it. Press `v` on a version, then choose another, to compare against that version;
  **compare** chooses it by mouse. Each picture is labelled. `esc`, **← All takes**, or
  **All takes** returns to the conversation or compare with the same take picked.
  **Use v2 in the studio** opens the shown version.
- **Notes at a moment**: on the takes, press `n` to focus the box and aim a note at the
  picked take at the clock's moment. **◆ to B · at 0.80 s** shows the aim above the box;
  click **×**, or press `⌫` with an empty box, to remove it. A take's page aims the box at
  that take without a time until `n` adds one. Your words stay as typed in the conversation;
  the agent also gets the take, seconds, and that take's own frame. A note without an aim
  goes to the whole thread. **◆** on the scrubber marks notes for the picked take; click one
  to seek to its moment. The take's **Notes** lists its messages and version changes in
  conversation order; scroll or use Page Up / Page Down to read earlier notes. **More like
  this** aims the box at this take and starts "More like B: " for you to finish.
- **Refine one** by naming it: "B, with more overshoot". Takes have short direction names,
  such as **B · Drop**, and versions numbered **v1**, **v2**, in their history's order. The
  words under the label in compare say what changed. A dot marks a version changed since you last
  picked that take. While the agent works, the card says what it is making.
- **Read the conversation**: finished turns fold their steps. Choose **show steps** to unfold
  them. Scroll with the wheel or Page Up / Page Down. In compare, the player stays put above
  the conversation; in the conversation, the cards scroll with their turns.
- **Open the one you like** (`⌃B` or **open ↗**) in the studio, as a file of its own; `w`
  saves it to Documents. `⌃O` goes back to the agents, still working.
- **Send your version back**: a document opened from a take shows **↩ from … · B v2** under
  its name. **send back as v3** (or **Send back to the agents** in the palette) adds your
  edits as the take's next version and returns to the thread with it picked. Its card and
  version row say **v3 · yours**; its notes say **you · edited in the studio → v3**. You can
  edit the same document and send it back again as v4. If its agent is at work, let the turn
  finish before sending back. The agent's next message tells it to build on your version.
  The Engine loads its Lottie before the take's next script; Frolic reads the source written
  from your edits. A version over the Engine's 4 MB limit stays on the take and cannot be
  loaded there. Import warnings appear in the version's change note. The thread keeps the
  authored studio document beside the Lottie export, so studio features remain in your
  version. State machines, themes, tokens and the studio's looks ride along on later
  versions (see below).
- **Several ideas at once**: `⌃N` (or **+ New idea**) starts another while the first works.
  The list shows a spinner while one works and a dot when one finished while you were
  elsewhere.

Closing this view returns to the studio; it does not stop the agents. **■ stop** or `⌃C`
stops the current thread's turn. Requests sent while it works wait until that turn finishes.

Drag over conversation text to highlight it and copy it when you release.

### Questions in a conversation

An agent can offer a plain choice, a palette of named colour sets, or font faces. The question
replaces the message box at the bottom, with numbered options and **● picked** beside the
agent's choice. The agent continues with that pick immediately. Palette options show colour
swatches; fonts show the face names. A newer question replaces the previous one in that thread.

Use `↑` `↓` to move, a number to choose at once, or `⏎` to choose the option under **❯**.
Clicking an option chooses it too. Choosing another sends a message such as
`Use the palette "Coral reef" instead.`, so the agent makes the next version. Choosing the
agent's pick or pressing `esc` keeps it. Each closes the question.

**Type something else…** closes the question and returns the box with its caret. A draft
started before the question stays as typed. Options scroll to keep the cursor in view when
space is short. `⇥` moves between the takes and the question. A take's page keeps its box for
notes; the film plan's voice picker waits for your choice before building.

### Boards from a studio tab

Ask the [copilot](https://terminal.lottiefiles.com/docs/copilot.md) for options of the open document. In compare, the idea line says
**start from: NOVA sting (the tab) · the hover**. Take A starts with that document, and the
agent makes the requested takes from it. **Use** and **open ↗** return a version to that tab
as one undo step: **B is in NOVA sting · u undoes it**. A closed tab makes the version open
as a file of its own.

### Interactivity and what rides along

Ask the take: "Make B a button: hover and press", or "Give B a dark theme and an accent
token". Its agent uses the copilot's `states` and `tokens` tools on that take's latest
version; `document` lets it read the layer names and properties. A document edit makes a new
version, with a note such as **added state machine button**, **added theme dark** or **added
token accent**. Motion still comes from the Engine's scripts or the Frolic source.

State machines, themes, tokens (their property links and slot values), and studio looks
(materials, ink and soft edges) ride along when the maker returns a new version. These parts
come from the latest document edited with the take's tools or sent back from the studio.
Layers must keep unique names; token properties must keep the same path, item types and
value within that layer. Changed token properties keep the maker's value, and theme rules
for missing slots are left off. Machines keep their layer names and marker names. A machine
whose layer or marker cannot be matched is left off that version, and its change note says
why. It can return when a later version has the missing layer or marker again. Missing token
properties and looks are left off too. The card's second line and each version row show both
what changed and what that version carries.

**Use** opens the kept version, so its machines appear in **States** and its themes and
tokens remain available for editing and shipping. No studio window is needed for the agent's
document tools; trying a machine on the studio's stage still needs the studio.

### Changes and earlier versions

Agents make their thread's takes, not the document you left in the studio. Each changed
version stays in the conversation. To return to an earlier result, scroll back, select its card
and press `⌃B` to open it. This is separate from the studio's undo history. Once you edit an
opened take, `u` undoes those studio edits and `⇧U` restores them.

An agent's tools are limited to its takes or assigned film shots, references and the app's
media tools. It has no general shell or your other connected tools. Engine takes are made in
cloud documents; Frolic sources and the thread history are kept on this computer. Your
prompt and supplied references go to the AI provider; Engine work also uses LottieFiles.

### What you can give it

- **Something to learn from** (on the Engine): drop a video on the composer, or paste a link
  to a video, a page or a picture. The agent studies its shots, look, pace and palette, and
  makes the take in its manner.
- **A brief**: drop a PDF or a text file (a one-pager, a script).
- **A picture on this computer**: name it ("animate the logo in ~/Desktop/logo.png") and the
  agent traces it into shapes to animate.
- **Type**: name a face ("Manrope ExtraBold"), from Google Fonts or this computer.
- **Music**: ask for it ("with music", "a lofi bed under B") and it gets music made to its
  length, timed to its moments.
- **A voice**: ask for one ("a voiceover on A", "say the tagline at the end"), and its lines
  are voiced under the take, timed for its motion to land on their words. You need to be
  signed in to LottieFiles; the voice model is **Voice** in Settings.

### On the Engine or in Frolic

A new animation is made on the LottieFiles Engine in the cloud. Click **use Frolic instead**
to switch to Frolic, or open the agent and model menu below the box and choose **Made on the
Engine** or **Made in Frolic**. A dot marks the chosen one. Films always use the Engine:

- **On the Engine**, each take is a document in the cloud. You need to be signed in
  (`creator-tui login`, or **sign in ↗** on the new idea page). If you send while signed
  out, your idea waits and sign-in starts. It goes to the agent as soon as sign-in
  completes. The view shows a link when the browser cannot open: `y` copies it. **cancel
  sign-in** or `esc` cancels sign-in and keeps the idea waiting. You can sign in again or
  choose **make it in Frolic instead** for an animation with no takes yet. An expired
  sign-in also keeps the message waiting.
- **In Frolic**, each take is a Frolic document the agent writes and Creator Terminal
  compiles here: no LottieFiles sign-in, and every version of its source is kept.

### Who does the work

Each thread's agent is Claude Code, Codex or Kimi Code, signed in as you are. The button
below the message box shows the agent and model (**claude · opus ▾**): click it for a menu
of the agents installed here and the models each lists for your account, for new ideas or
for the selected thread's next message. Wait for a running turn to finish, or stop it first.
New ideas start on Claude's **Opus**, thinking at high effort (medium for Haiku); the others
keep their own effort settings, and can keep their own model too. An agent with many models
shows a few, and **more models ›** for the rest. A film has a director and a crew, each with
a menu of its own.

In **Settings** (`F2`), **Agents** has **Agent for new ideas**, **Model for new ideas**,
**Model for new films** (the crew) and **Style for new films**. The default style is **Learn
from attachments**. These choices live in `settings.json`.

Threads are kept in `~/.config/motion/agents`, a folder each. A thread opened after a restart picks up where it was.

## Films

Choose **A film, narrated with music** on a new idea's page (`⌃T`) and give it a story: a
topic ("why flamingos are pink"), a script, or a link to an article. Give it a film to learn
from too: drop the video, or paste its link (YouTube, Vimeo, X and the like). A director
agent makes the film as a studio would, and you watch it happen:

![A directed film before sending, with the Style choices visible.](https://terminal.lottiefiles.com/docs/assets/shots/more-agents-film-setup.png)

1. **Study**: it watches what you gave it: the shots, the pace, the palette, what's said.
2. **The plan**: the script shows its lines grouped by shot, with an estimated length, and
   **who speaks**. The idea says **needs you** while it waits. Each speaking part has its own
   voice picker. Nothing is voiced or built until you approve.

   The picker opens on the agent's three voices, with a reason for each. `←` `→` move,
   `space` plays the film's first line for that part on this computer, and `⏎` chooses.
   Samples are made on demand and kept in the thread's folder: hearing one again reuses it.
   Choose **all voices ›** (`a`) to search the catalogue. Type to filter, use the trait chips
   supplied by the catalogue, and `↑` `↓` to move. A short pause on a voice plays its sample;
   `⏎` chooses it and `esc` returns to the three. A `+` after the count means the catalogue
   supplies a limited result at a time; searching asks it for more matches.

   `tab` moves from the picker to the approval bar, then to the box; from the box it returns
   to the picker. You can also ask in words, such as "a younger voice". **change the script**
   puts the focus in the box. Your words go back to the director, which proposes a new plan.
   After choosing every speaking part's voice, choose **Voice it and build** (`⏎` on the
   bar). Building takes a while; you can leave the idea and come back. Later revisions use
   the approved voices. Voices come from ElevenLabs when `ELEVENLABS_API_KEY` is set, else
   LottieFiles' voices when you're signed in (**Voice** in Settings picks the model), else the
   system's voice. If none is available, the plan says the film will be silent and still asks
   for approval. Each shot lasts as long as its lines.
3. **Cast**: it draws what recurs (the palette, the characters, props and backdrops) once, for
   every shot to use.
4. **Shots**: a crew of agents builds the shots, eight at once, landing things on the words and putting sounds on the moments. The storyboard fills in as they
   work.
5. **Review**: the director looks at each shot and sends notes back until it's right.
6. **Cut**: the shots in order, with the narration, music made to the film's length, and the
  sounds. You get a card that plays (open it in the studio like any take), and an MP4 in
  Documents.

Ask for changes afterwards ("make shot 4 slower", "shorter: 45 seconds") and it
changes what you named and cuts again. Everything is kept in the thread's folder.

### Styles

Keep a film's style to make other films in it without studying the video again: **keep this
style ↗** on its card (or tell the director "keep this style as Night Hive").

- Kept styles are listed under **Style** on a new film's page. Pick one and the film starts
  in its look, so the director goes straight to the story. Those that don't fit on the row are
  under **+N more**, a menu of every style. You can name one in a message too ("in my Night
  Hive style").
- **take it off the shelf** removes one.
- Two come with Creator Terminal: **Bright Science** (bold, saturated flat vectors with
  label tags) and **Pastel Friends** (matte pastel stages, soft characters with dot eyes).

## Keys

| | |
|---|---|
| `⏎` · `⇧⏎` (`⌥⏎`) | send · a new line |
| `⇥` `⇧⇥` | in an animation: move between the box and the takes; in a film: next or previous card |
| `←` `→` | on the takes: pick a take |
| `space` · `h` `l` | on the takes: play or pause · step a frame and pause |
| `⏎` · `esc` | on the takes: open the take's page · back to the box |
| `↑` `↓` · `c` · `v` | on a take's versions: choose · compare · mark a version to compare with |
| `n` | on the takes: aim a note at the picked take and current moment |
| `esc` | on a take's page: all takes |
| `⌃G` | conversation or compare; `esc` leaves compare |
| `⌃B` | open the picked card's take in the studio |
| `⌃N` · `⌃↑` `⌃↓` | a new idea · the thread above and below in the list (`⌃←` `⌃→` too) |
| `⌃T` | on a new idea's page: an animation or a film |
| `⌃C` | stop the agent's turn, or clear what's typed |
| `esc` · `⌃O` | back to the studio |
| `⌃L` | LottieFiles |
| `⌃U` | clear the message box |
| `←` `→` · Home / End · `⌃A` / `⌃E` | move the caret · start or end of the message |
| `⌫` · Delete · `⌃W` / `⌥⌫` | previous character · next character · previous word |
| `e` | ship the picked version while the takes have focus; `esc` returns |
| `↑` `↓` | recall messages while the message box has one line |
| Page Up / Page Down | scroll the conversation |

## Tags in a message

Type `@` in the new idea, conversation, compare or take message box. The menu opens above
the box (below when there is more room): OPEN documents, TAKES and their versions, STYLES,
then RECENT files. Type words to filter, without case; use `↑` `↓` and `enter`, or
click an item. Long lists scroll with the selection or the wheel. `esc` closes the
menu and leaves the words typed. “A file on this computer” opens the same file
chooser as **Open a file…**, and attaches the file you choose.

A tag leaves the message text and becomes a chip above it. Documents and takes say
**start from**; videos, pictures, pages and styles say **learn from**. Click a chip's
`⇄`, or press `F6` to flip the last chip. With the message empty, `⌫` removes the
last chip.

For a new animation idea, the first document or take marked **start from** supplies
take A's first version. The Engine loads its Lottie into take A; Frolic converts it
to source. The agent is told to build on it. Other references are studied as
attachments are. On an existing thread, tags are references, including those marked
**start from**. A take always points to the selected version in its thread folder.

## Ship a take

Choose **ship ↗** beside **open ↗** on a take or version, or press `e` while the takes
have focus. Export opens over the conversation or compare on that version's document. It has
the studio's formats, sizes and destinations. LottieFiles receives a dotLottie with the version's state
machines and themes; this computer receives the format you choose. `esc` returns to the
conversation, compare or version page. An export already started finishes after the panel closes.

A successful export is kept on that version. **on LottieFiles ↗** opens its file;
**saved to Documents ↗** (or the folder you chose) shows the local file in Finder or Explorer.
The board card shows the newest destination; earlier versions keep theirs.

## Ideas that need you

Ideas waiting for you come first: sign in, approve a plan, or make a choice. Next are ideas
that changed while you were elsewhere (**●**), then those being made, then the rest by their
last change. Each row says which: **needs you · pick a voice**, **B v3 new ●**,
**making B · 40 s**, or **3 takes · 2 d**.

**← Ideas** (or **Ideas** in the palette) opens the Ideas page, with the latest takes as small pictures. A narrow
window opens here when you enter Agents. Use `↑` `↓` and `⏎` to open an idea, or `⌃N` to start
one. In a wide window, the left list and `⌃↑` `⌃↓` also switch ideas in the same order.

A new idea starts with the first words you typed. Its agent names it once in a few words when
it names its takes. When it needs a decision, the row says what it needs; your next message
answers it.

Next: [Compare animation takes from agents](https://terminal.lottiefiles.com/docs/how-to/compare-animation-takes.md).