Plotra DocsThe AI agent
An assistant that works inside your story and stays under your control. Turning it on, whose model it runs on, the three modes, undoing what it did, and exactly what is sent where.
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: it can open and change only what you can.
Turning it on
Two switches, both off by default:
- The workspace: an owner or admin opens Workspace settings and turns on AI.
- The project: in Project settings, turn on the AI module.
Only people who can edit the project can run the agent. Viewers and commenters never see it.
Whose model it runs on
The agent needs a model. There are four ways to give it one.
| Who pays | Where the text goes | |
|---|---|---|
| Your own key | You, on your provider's bill | The provider you chose |
| A local model | Nobody | Your own machine |
| Hosted AI (Pro workspaces on the hosted version) | The workspace's monthly credits | The provider Plotra uses |
| The instance's key (self-hosted) | Whoever runs the server | The provider they chose |
Your own key
Open your account menu, choose Your settings, then AI. Pick a provider (Anthropic, OpenAI, OpenRouter, or any OpenAI-compatible endpoint), paste a key, and name two models: one for agent runs, and a cheaper, faster one for the inline actions in the editor. Test makes one tiny call on each and tells you what the provider said.
The key is yours alone. It is stored encrypted, used only for your own runs, never shown again and never shared with collaborators. A collaborator who runs the agent uses their own key.
A local model
Choose Ollama (local model), or an OpenAI-compatible endpoint with a local address such as LM Studio'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=trueso 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. 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 your browser and never sent to Plotra. The server still builds the instructions, runs the agent's tools as you, and stores the conversation, as for any run.
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_ORIGINSto the app's address, for exampleOLLAMA_ORIGINS=https://app.plotra.com ollama serve. - 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 larger than that, so on the default the model behaves as if it had no tools. Set
OLLAMA_CONTEXT_LENGTH=16384or more. This applies to a self-hosted Plotra calling Ollama as well.
Limits of a browser-called model: long jobs are not available (they need a model the server can reach), the model has to be at localhost or behind https (a secure page can't call plain http on your network), closing the tab mid-run loses the answer being written (what it already changed can still be undone), and after switching to a local model an open project needs a reload.
Hosted AI
On the hosted version, a workspace on Pro has 1,500 credits a month and nobody needs a key. One credit is 1,000 input tokens; output tokens count five times. Credits reset with the billing period and don't roll over. If you have your own key, your runs use it and spend no credits. See Plans.
Where to find it
- The AI tab in the right sidebar, or AI as a view in any pane: a chat, with every step the agent takes listed as it happens. Type
@to point it at a note. Answers link to the notes they drew on. - In the editor: select some text, or put the caret on an empty line, and press
⌘J(also in the floating toolbar and the/menu): continue, rewrite, shorten, expand, change tone. The answer can replace the text or arrive as a suggestion. - The command palette (
⌘P): "Ask AI…", "AI: Draft this scene or chapter", "AI: Check this chapter", "AI: Carry a change through the project…", "AI: Build the project from a premise…". Each puts a request in the chat box for you to finish and send.
The three modes
| Mode | What it may do |
|---|---|
| Ask | Reads what you can read. Changes nothing. |
| Suggest | Edits to a note's text arrive as suggestions (tracked changes) for you to accept or reject in the Comments tab, shown as "AI, for your name". Anything else, such as moving notes or changing properties, asks you first. |
| Auto | Changes apply straight away. It still asks before moving anything to the trash, before changing canon status, and once when a run goes past five notes. |
When the agent asks, the run stops and shows Allow, Don't and Allow all. Sending another message without answering counts as "no".
Some things the agent can never do, in any mode: change who a project is shared with or who is in the workspace, change workspace settings, read or change API keys, delete anything permanently or empty the trash, or publish the public wiki.
Undoing a run
- The first time a run changes a note's text, that note is saved as a version named "Before AI". These versions count against the workspace's storage; if storage is full, the edit is refused rather than made without a way back.
- Undo run, under an answer, takes back everything that run changed: text, properties, moves, new notes.
- 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.
Replacing a block replaces the whole block. If someone is typing in that same paragraph at that moment, their keystrokes there are lost.
The story brief
A top-level note called Story brief is sent with every run: genre, voice, tense, point of view, the rules of the world, things to avoid. A project without one shows "Add a story brief" in the AI panel, which makes one from a template. It is the most useful thing you can write for the agent; without it the agent guesses the voice from whatever it happens to read.
What it knows about your story
The agent doesn't load the whole project. It looks things up: the binder outline, project search, a note's text, entities and their properties, backlinks, the timeline, relationships, who knows what, open setups, and the continuity checks.
It is told to respect canon: canon status, the spoiler horizon when you ask for something "as of" a release, and what the point-of-view character knows at that point in the story. After writing, it is told to run the continuity checks on what it touched. These are instructions to a model, not guarantees: a weak model ignores them more often.
Long jobs
Drafting an act is too long for one request. Ask for it and the agent saves a list of steps instead. Press Start, and the steps run one at a time; a dropped connection picks up at the next step. Starting the job is your approval of its list, so steps create and change notes without asking, but nothing is moved to the trash and canon is not changed inside a job. Undo all takes back every step.
What is sent, and where
- 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 story brief, and the notes the agent reads along the way. 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.
- 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 thread is there when you come back, and a row per run with the model's name and the number of tokens. Each answer shows its tokens, so you can see what it cost you.
Text the agent doesn't trust
Clipped web pages, imported files, comments from guests and notes from a shared world 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. 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.
Which models
What has actually been tested is listed here, and nothing else is claimed. See apps/app/evals/README.md in the repository for the evaluation set and how to run it against a model of your own.
Canon and the spoiler horizon
Keep a long story consistent and spoiler-safe. The world bible, canon status, releases, reveals, the spoiler horizon, who knows what, and continuity checks.
Project settings
Shape a project to your medium: its type, modules, status workflow, its own words, labels and kinds, and the ribbon you see it through.