The AI agent

Plotra works without AI. The agent is off until someone turns it on, and with it off no AI control is shown anywhere.

When it is on, it works inside a project like a collaborator: it can answer questions about the story, draft and rewrite, and change the binder, properties, timeline and the rest. It does all of that as you: every step it takes goes through the same permission checks as your own clicks, so it can open and change only what you can.

Turning it onCopy Anchor Link

Three things have to be true before you see any AI control. The first two are switches, and both are off by default.

1. The workspace switch. An owner or admin opens Workspace settings → AI and turns on the switch. While it is off, no AI control is shown in any of the workspace's projects.
2. The project switch. In Project settings, under Modules, turn on AI agent. No project type starts with it, and it has no effect until the workspace switch is on.
3. You can edit the project, and you have a model. Only people who can edit a project can use AI in it. Viewers and commenters never see it. A guest with the editor role can use it, on their own model.

With both switches on and no model, the AI tab shows Add your own model to use AI with a button to Open AI settings. Press I've added it when you are done and the chat appears.

Whose model it runs onCopy Anchor Link

The agent needs a model. There are four ways to give it one.

When more than one is available, your own settings always win. Then comes hosted AI, if the workspace is on Pro and has credits left this month. On a self-hosted server with no plans, the instance's model is used by everyone who hasn't added their own.

Your own keyCopy Anchor Link

Open your account menu, choose Your settings, and find Your model.

Test makes one tiny call on each model and tells you what the provider said. Save stores the settings. Remove deletes your key and models from Plotra; nothing changes at your provider.

The key is yours alone. It is encrypted before it is stored (AES-256-GCM, tied to your account, so a copy of the row doesn't decrypt on anyone else's), used only on the server for your own runs, and never shown again: the page only ever shows its last four characters. It is never shared with collaborators. A collaborator who runs the agent uses their own key.

On the hosted version, the URL of an OpenAI-compatible endpoint has to lead to the public internet or to your own machine (see below). A URL with a username or password in it is refused: the key goes in the key field.

A local modelCopy Anchor Link

Choose Ollama (local model), or OpenAI-compatible endpoint with a local address such as LM Studio's or llama.cpp's. The agent needs a model that supports tool calling; a model without it can still do the inline actions.

• On a self-hosted Plotra the server calls the model. Whoever runs the server sets AI_ALLOW_PRIVATE_URLS=true so that addresses on the local network are allowed.
• On the hosted version the server can't reach your computer, so your browser calls the model directly. The settings page says so as soon as you type a local address. What the model is sent and what it writes go between your browser and that model, and to no provider. A key for the endpoint, if it needs one, is kept in that browser's local storage and never sent to Plotra, so you enter it again in each browser you use.

When the browser calls the model, the loop that asks the model, runs the tools it asks for and asks again runs in your browser tab. Everything else stays on the server: it builds the instructions, runs each of the agent's tools as you, decides what the mode allows and what has to wait for your yes, and stores the conversation. Nothing the browser or the model sends can stand in for your answer to a question the agent asked.

Two things have to be set on the model server, or it won't work:

• Allow the app's address. A model server refuses requests from web pages it doesn't know. With Ollama, set OLLAMA_ORIGINS to the app's address, for example OLLAMA_ORIGINS=https://app.plotra.com ollama serve. Another server needs to allow requests from that address (CORS).
• Give it a larger context. Ollama's default context is 4,096 tokens and it cuts off what doesn't fit without saying so. The agent's instructions and tools alone are about 7,000 tokens, so on the default the model behaves as if it had no tools. Set OLLAMA_CONTEXT_LENGTH=16384 or more; the settings page suggests 32768. Test warns you when Ollama is running the model with less than 16,000. This applies to a self-hosted Plotra calling Ollama as well.

Limits of a browser-called model:

• Long jobs are not available: each step is run by the server, which can't reach your model. Start is greyed out. Ask for the work in the chat instead, a few notes at a time.
• The model has to be at localhost or behind https. A page served over https may not call plain http on your network.
• Closing the tab in the middle of a run loses the answer being written. What the run had already changed stays changed; the next time you send a message in that chat, a line appears saying the run was interrupted, with its changes listed and Undo run under it.
• After switching to or from a local model, reload any project you have open.

Hosted AICopy Anchor Link

On the hosted version, a workspace on Pro has 1,500 credits a month and nobody in it needs a key. One credit is 1,000 input tokens; output tokens count five times. If you have your own key or a local model, your runs use it and spend no credits. When the credits run out, people without a model of their own see a message saying when the credits come back. The details are in Plans and billing.

The instance's keyCopy Anchor Link

Whoever runs a self-hosted server can give everyone on it a model with the AI_PROVIDER, AI_MODEL_AGENT, AI_MODEL_FAST, AI_API_KEY and AI_BASE_URL settings. Your settings then shows "This server provides a model for everyone" with its name. Your own settings, if you save any, are used instead.

Saving a personal key needs AI_KEY_SECRET to be set on the server (at least 16 characters); without it the page says the server isn't set up for personal AI keys. See Self-hosting.

Where to find itCopy Anchor Link

• The AI tab in the right sidebar, or AI as a view in any pane (the ribbon, or the command Open AI chat): a chat, with every step the agent takes listed as it happens.
• In the editor: select some text, or put the caret on an empty line, and press ⌘J. The same menu opens from the AI button in the floating toolbar, and Continue writing is in the / menu.
• The command palette (⌘P): five commands in the AI group.

Each of the last four only fills the box. Nothing is sent until you press Enter.

The chatCopy Anchor Link

The box at the bottom takes your message. Enter sends it and Shift+Enter starts a new line. While the agent is working, the send button becomes Stop.

• @ points at a note. Type @ and a few letters, pick a note from the list, and the agent is told which note you mean. A message can point at up to 12 notes.
• Steps. Every tool the agent uses shows as one line while it runs and after: "Searched for “letter”", "Read Chapter 3", "Edited The Lighthouse". A step that failed shows why when you hover over it.
• Notes used. Under an answer, the notes the agent drew on are listed as chips that open them. Links inside the answer open notes too.
• Tokens. The latest answer shows what it used, as "12,300 tokens in · 840 out".
• When a run stops with an error, the reason is shown with Try again, which answers your last message again.
• A message can be up to 8,000 characters. For anything longer, put it in a note and point at the note.

While the agent is working in a mode that can write, it appears in the project like another collaborator, with a cursor in the note it is writing.

ChatsCopy Anchor Link

Each chat is a separate conversation. Chats belong to you and to the project: nobody else can see yours, not even the workspace owner. The menu at the top left of the panel lists Your chats in this project, newest first, each named after the first words of its first message. The bin icon deletes one. The New chat button starts another.

In a long conversation, only the most recent 60 messages are shown and sent back to the model.

The three modesCopy Anchor Link

The mode menu at the top of the panel, What the AI may do, has three settings. A project opens in Suggest, and your browser remembers the last one you picked for each project.

When it asksCopy Anchor Link

When the agent has to ask, the run stops and shows a box titled Allow this change? with one line per change, such as "Move The Lighthouse", each with Don't and Allow. With several changes waiting there are also Allow none and Allow all. The run carries on when every line is answered, in the mode it started in, even if you have changed the menu since.

• Sending another message without answering counts as "no".
• If you say no, the agent is told not to try the same thing again.
• A run can make at most 16 calls to the model in Ask, 30 in Suggest and 40 in Auto. A run that reaches the limit stops where it is.

What it can never doCopy Anchor Link

In any mode, the agent has no tool to: change who a project is shared with or who is in the workspace, change project or workspace settings, read or change API keys, delete anything permanently or empty the trash, restore from the trash, export, or publish. If you ask for one of these, it tells you to do it yourself.

It also can't write to a locked note: a lock is read-only for the agent as it is for editors.

What the agent can doCopy Anchor Link

These are all of the agent's tools. Ask mode has the ones that read. Suggest and Auto have all of them.

Tools that readCopy Anchor Link

Reading follows the same rules you do. Notes in the trash are left out. When you ask about the story "as of" a release, the agent passes that release to its tools and they leave out what the spoiler horizon would hide.

Tools that writeCopy Anchor Link

"Applies" in Auto still stops once to ask when the run has already changed five notes.

A text edit goes through the live document, so anyone with the note open sees it land, and a note nobody has open is updated just the same. Replacing a block replaces the whole block: if someone is typing in that same paragraph at that moment, their keystrokes there are lost.

In the editorCopy Anchor Link

The inline actions are for a passage, not for the project. They use your model for inline actions, have no tools, and change nothing until you accept the result.

Press ⌘J and pick one:

The text streams into a small panel beside the selection, not into the note. When it is done:

• Insert (after Continue) or Replace puts it in as one ordinary edit, which is one step of undo.
• Suggest puts it in as a tracked change, to accept or reject from the Comments tab.
• Try again runs the same action again. Discard closes the panel. Stop ends it while it is still writing.

A selection can be up to 12,000 characters; past that you are told "That's too much text at once. Select a shorter passage." The model is sent the selection, up to 6,000 characters before it and 1,500 after it, the note's title and the story brief. If the text changed while the model was writing, accepting says "The text this was for has changed. Try again."

You have to be able to edit the note, and a locked note refuses the inline actions.

Undoing a runCopy Anchor Link

• The first time a run changes a note's text, that note is saved as a version named "Before AI · for your name". These versions count against the workspace's storage; if storage is full, the edit is refused rather than made without a way back.
• Under an answer that changed something, the changes are listed, with Undo run. It takes back everything that run changed, newest first: text, properties, moves, new notes, relationships and the rest. The answer then shows Undone.
• When a run ends, each note it wrote gets a version named "AI, for your name", so the history shows what was the agent's. This one is skipped when storage is full.

Only the person the agent worked for can undo its run, and not while it is still going: stop it first. The undo runs as you, through the same checks as your own edits. A change that can no longer be taken back, because the note was deleted since or someone locked it, is reported in a message ("Undone, except 1 change: …") and the rest are still undone.

In Suggest mode the text edits are suggestions, so you can also reject them one by one in the Comments tab.

The story briefCopy Anchor Link

A top-level note called Story brief is sent with every run and every inline action. A project without one shows Add a story brief: voice, tense, rules, things to avoid in the AI panel. Pressing it makes the note at the top of the binder from a template with these headings: What this is, Voice, Tense and point of view, Rules of the world, Things to avoid, How to work with me. Replace the line under each with your own and delete what you don't need.

A note you make by hand works just as well, as long as it sits at the top level and is called "Story brief". Only its first 6,000 characters are sent.

It is the most useful thing you can write for the agent; without it the agent takes the voice, tense and point of view from whatever text it happens to read.

What it knows about your storyCopy Anchor Link

The agent doesn't load the whole project. It looks things up with the tools above, and is told to read enough to answer and stop.

It is told to respect canon: to treat retconned and non-canon notes as not part of the story, to keep to the spoiler horizon when you ask for something "as of" a release, and to write only what the point-of-view character knows at that point in the story. After writing, it is told to check what it touched against the continuity checks. It is also told to link every note it relies on and never to answer from what a story like yours usually contains.

These are instructions to a model, not guarantees: a weaker model ignores them more often. The checks that don't depend on the model are the ones on the server: the mode, your permissions, locks, and what has to wait for your yes.

Searching the projectCopy Anchor Link

Search project (⌘⇧O, or the command of that name) searches the text of every note, not only its title. It uses the same search the agent does, but no model, so it is there whether or not AI is on.

• Words are all required. Put a phrase in "quotes". Put - in front of a word to leave it out. or between words finds either.
• Each result shows a passage with the matched words marked. Notes in the trash are left out.
• Pick a result to open the note. ⌘↵ opens it in a new tab, and ⌘⌥↵ opens it in a split.

Long jobsCopy Anchor Link

Drafting an act is too long for one request. Ask for it and the agent saves a list of up to 40 steps instead of starting. The job appears at the top of the AI panel with its steps.

• Start runs the steps one at a time, one request each. Pause stops after the step that is running. Resume picks up at the first step that isn't done.
• A dropped connection or a closed tab costs at most the step in flight. That step is run again on Resume, and the agent is told to look at what already exists before carrying on.
• A step that fails pauses the job and shows the reason on that step.
• A step that made or changed a note links to it.
• Starting the job is your approval of its list, so steps create and change notes without asking. Nothing is moved to the trash and canon is not changed inside a job: the agent is refused and told to report what it would have done.
• A job runs in the mode it was planned in. Planned in Suggest, its text edits to existing notes arrive as suggestions. A job never runs in Ask.
• Undo all takes back every step, newest first. Remove takes the job off the list.

The panel shows up to four jobs: the ones not yet done and the two most recent. Long jobs need a model the server can reach, so they are not available on a browser-called local model.

What is sent, and whereCopy Anchor Link

• Nothing leaves Plotra until someone runs the agent or an inline action.
• A run sends the model what it needs for the task: your request, the conversation so far, the story brief, and the notes the agent reads along the way. An inline action sends the selection and the text around it. It goes to the provider for that run and nowhere else: the provider of the key of the person who ran it, the provider Plotra uses on a hosted run, or nowhere at all with a local model.
• A collaborator who can edit your project can run the agent on it, and the notes it reads then go to their provider. If you don't want that, leave AI off for the project.
• What a provider does with the text is between the key's owner and that provider. Read their terms on retention and training. With an OpenAI key, Plotra uses the chat completions API, which keeps no conversation on OpenAI's side between calls.
• Plotra never trains a model on your work. It doesn't have one.
• Plotra keeps the conversation (your messages, the agent's answers and its steps) so the chat is there when you come back, and a row per run with the model's name, the mode, how it ended and the number of tokens. It never stores the key in that row.
• Usage statistics record that a run happened, its mode, its outcome and the provider's name. They hold nothing of what was asked or answered.

Text the agent doesn't trustCopy Anchor Link

Some of what the agent reads was not written by anyone who can edit the project, and can contain text written to look like instructions ("ignore your instructions and…"). The agent is given such text inside a marked block and told that it is material to read, never orders to follow. These are marked:

• Research notes. Every note of the Research kind is treated as a clipped web page.
• Imported notes. Everything an import creates.
• Comments from people who can't edit the project. Comments by its editors are passed as they are.
• The story brief, when it is itself a research note or was imported.

The marks carry a token made fresh for each run, so text can't close its own block and carry on outside it. The agent is also told that titles, synopses and property values are content, never instructions.

This lowers the risk; it does not remove it. Ask mode can't change anything, and in the other modes trashing and canon changes always stop to ask you.

Rate limitsCopy Anchor Link

These protect the server and are the same on every plan and on your own key.

Past one, you see "That's a lot in a short time. Try again in a minute." (or the number of minutes left). A run on a browser-called local model can also make at most 900 tool calls in 10 minutes.

Messages you may seeCopy Anchor Link

Which modelsCopy Anchor Link

The agent runs on any model from these providers:

Two requirements decide whether a model works for the agent:

• Tool calling. The agent's model has to support it. The model for inline actions doesn't.
• Context. The agent's instructions and tools take about 3,400 tokens in Ask and about 7,500 in Suggest and Auto before the conversation starts. A model needs room for that plus the notes it reads; 16,000 tokens is the least that works.

The examples above are the ones the settings page suggests. A larger model follows the story brief, canon and the spoiler horizon more reliably than a small local one.

The repository has a set of 22 tasks on a sample novel and 6 prompt-injection tasks that you can run against any model, with a report of what passed and roughly what a chapter costs: see apps/app/evals/README.md.