# Agents and automation

> How every editor feature is exposed as a validated command that scripts and AI agents can call through the CLI or MCP.

Source: https://feather-engine.com/docs/agents/overview/

Feather 2 is built so that an AI agent or a script can do anything a person can do in the editor.
Every authoring feature is a command in one shared catalog, with a strict JSON schema. The editor's
own panels run the same commands, so an edit made by an agent is validated, undoable and visible in
the editor exactly like an edit made by hand.

The engine does not bundle a language model or provider credentials. You connect your own AI client
through the [Model Context Protocol](/docs/agents/mcp/), or call commands directly with
[`feather-cli`](/docs/agents/cli/).

## How a command flows

| Step | What happens |
| --- | --- |
| 1. Request | A person (editor panel or **Cmd/Ctrl+K**), the CLI or an MCP client sends a command name and JSON arguments |
| 2. Validation | Arguments are checked against the command's schema; unknown fields and out-of-range values are rejected |
| 3. Transaction | The change is applied to a copy of the project, and the whole project is validated, including references between assets, objects and scripts |
| 4. Commit | On success the change becomes one undo step and the revision number advances. On failure nothing changes |
| 5. Feedback | The response reports the result. Agents can then read state, run a [simulation](/docs/agents/simulation/), read runtime logs or capture the viewport |

The catalog currently holds 270 commands; see the [command reference](/docs/agents/commands/).

## Live and headless sessions

| Session | Started with | Works on | Use it for |
| --- | --- | --- | --- |
| Headless | `feather-cli --workspace DIR [--project FILE]` | A document in memory, with no window or renderer | Batch authoring, CI checks, building projects from scripts |
| Live | `feather-cli --connect SESSIONFILE` | The running editor's open project | Working alongside a person, Play, viewport capture |

Headless sessions support all authoring commands, renderer-free play-testing with `game.simulate`
and game builds with `game.export`. Commands that need a real window — `runtime.*`, `viewport.*`,
`editor.*` and `job.inspect` — work only in a live session. A live session connects over an authenticated local connection described by
a session file; see [MCP setup](/docs/agents/mcp/).

## Response envelope

Every command returns the same JSON envelope:

```json
{
  "ok": true,
  "revision": 12,
  "data": { "object": { "id": 4, "name": "My cube" } },
  "error": null
}
```

On failure, `ok` is `false`, `data` is `null` and `error` holds a stable `code` and a `message` that
says what to change.

| Error code | Meaning |
| --- | --- |
| `invalid_arguments` | Arguments do not match the command's schema |
| `not_found` | A referenced object, asset or item does not exist |
| `validation` | The change would leave the project invalid |
| `revision_conflict` | The document changed since the revision you passed |
| `playing` | Authoring is locked while the live editor is in Play |
| `unknown_command` | No command with that name exists |
| `requires_live_editor` | The command needs a running editor; connect with `--connect` |

## Revisions

Every edit, selection change, undo and redo advances the document's revision. Pass the revision you
last read to make an edit conditional:

- CLI: `--expected-revision N`
- MCP: an `expected_revision` field in the tool's arguments

If anything changed in between, the command fails with `revision_conflict` and changes nothing. Read
the current state again before retrying. This lets an agent and a person work on the same project
without overwriting each other.

## Undo

Each successful command is one undo step, including multi-step operations such as `scene.batch`
(up to 64 commands applied atomically). Agents undo and redo with `history.undo` and
`history.redo`; in the editor, the same history is on **Edit → Undo** and **Cmd/Ctrl+Z**.

## Pending editor edits

A person may have unapplied edits in the editor, such as an unsaved script buffer or a Blueprint that
has not been applied. `engine.status` reports them. Before making a conflicting change, call
`editor.commit` to validate and apply them, or `editor.discard` to drop them explicitly.

## Editor layout

In a live session, an agent can arrange the editor for the task at hand. `editor.workspace.get` lists
the workspaces (`level`, `terrain`, `art`, `logic`, `gameplay`, `story`, `ship`) with their panels,
and reports the current workspace and the panels open and in front. `editor.workspace.set` switches
to one; `reset: true` restores its default arrangement. Neither changes the project or its revision,
and switching is refused during Play.

```bash
feather-cli --connect .feather-session.json command editor.workspace.set --json '{"id":"ship"}'
```

## Checking results

| To check | Use |
| --- | --- |
| Project data | `project.inspect`, `scene.get`, and each domain's `.get` command |
| Gameplay and physics | `game.simulate` returns a report without a renderer; see [Simulation](/docs/agents/simulation/) |
| Runtime messages | `runtime.logs` in a live session |
| Visuals | `viewport.capture`, then `viewport.image`; see [MCP setup](/docs/agents/mcp/) |
| Performance | `runtime.stats`; see [Profiler](/docs/shipping/profiler/) |

## Automate it

```bash
# Discover every command and its schema.
feather-cli catalog

# Inspect a live editor before editing.
feather-cli --connect .feather-session.json command engine.status
```

Next: [Command-line control](/docs/agents/cli/) and [MCP setup](/docs/agents/mcp/).