Working with AI Assistants
On Mac, AI assistants such as Claude can read your projects and comment on them through the Model Context Protocol (MCP). An assistant can never change your text. It comments in the margin and proposes edits for you to accept or reject. If you allow it, it can also add drafts, folders, characters and synopses for you to review, or organise the project.
Connect an assistant
Assistants can't connect until you allow them. Open Settings > Agents and turn on Let AI agents read, comment and suggest (MCP). The pane shows what to copy into your assistant: a command for Claude Code, and a snippet for Claude Desktop's configuration. Status says whether an assistant is connected. If Five Rooms isn't running, the assistant opens it in the background.
Assistants on the web or your phone connect through Five Rooms on the web instead, to the projects you choose there: see Five Rooms on the Web.
What an assistant can do
| Can | Can't |
|---|---|
| List projects and read documents, arrangements and structure | Change your text |
| Search, and compare checkpoints | Delete anything, or empty the Trash |
| Add margin comments, anchored by quoting your text, and comments on synopses, filed under your comment categories if you ask | Make or change a category |
| Propose edits, which appear as suggestions | |
| Propose tags and synopses, which you approve in the inspector | |
| Create checkpoints, and new arrangements: a copy of one you have, an outline it proposes, or an empty one | |
| Compile. The file is saved to your Downloads folder. | |
| Add drafts, folders, characters and places, fill in empty synopses and restore items from the Trash, if you allow it | Replace or add to a document you have, or replace a synopsis you wrote |
| Move, convert and rename documents and folders, and set their fields, if you allow it | |
| Move items to the Trash, if you allow that too |
Comments and suggestions show the assistant's name and are highlighted in purple. A comment on a synopsis appears under the synopsis in the inspector and the Scene drawer, and in Revise ▸ Comments, marked On the synopsis; Resolve it there when you've dealt with it. See Margin Comments and Suggestions.
What an assistant can add
To let an assistant write new documents, such as blog posts or scenes, turn on Let agents add to projects in Settings > Agents. Ask the assistant to draft something and it adds a new document to the project's Inbox, or to the end of a folder you name. It can also add an empty document, a scene for you to write. The document's notes say which assistant wrote it and when. Headings and links in what it writes become bold lines and plain words; lists stay lists. Read it, then move it where it belongs, or delete it. Nothing else in the project changes.
With the same setting, an assistant can add folders to lay out chapters and parts: at the end of the manuscript, inside a folder, or right after an item. It can also give a document or folder a synopsis when it has none. If it already has one, or the setting is off, the assistant's synopsis appears under Proposed by agents in the inspector for you to accept or reject; yours stays until you accept.
It can also add characters, places, objects and motifs to the cast, with the other names the text uses for them. A new character gets a study page in Research & Notes as usual, and the assistant can fill it in. If your Characters folder already has a document with that name, it becomes the study page and the assistant leaves its text alone. Names already in the cast are never added twice.
It can also put items back from the Trash, into the manuscript or wherever you ask. Only their place changes. A folder comes back on its own; its documents are separate items in the Trash, which it restores into the folder.
Organising a project
To let an assistant rearrange a project, turn on Let agents organise projects in Settings > Agents. It's separate from adding, and off until you turn it on. The assistant can then move documents and folders into a folder, to the top level or after an item, within the manuscript or between it and Research & Notes. It can also turn documents into folders, or folders back into documents, as Convert to Folder does: in the manuscript a folder of documents is a chapter. And it can retitle documents and folders (in the manuscript titles are chapter headings) and set their fields: status, label, POV, setting, section type, story time, word target, Include in compile and your own. Without this setting, an assistant can only propose field values for you to approve in the inspector. Text never changes, and nothing goes to or comes from the Trash this way. Before its first change in a project, a checkpoint named "Before assistant reorganised items" is recorded: compare it with today in History to see everything it changed.
Let agents move items to the Trash is a separate switch, also off until you turn it on. With it, an assistant can put documents and folders in the Trash, as Move to Trash does. Nothing is deleted: open the Trash to put things back, or ask the assistant to restore them.
To stop assistants connecting, turn the first switch off. Turning any of the others off takes effect at once, even for an assistant already connected.