This plugin lets you talk to an agent about one row of an outline or one .md file. An agent is a coding assistant such as Claude Code or Codex.
Chat is on by default.1
What chat needs to work
One engine plugin, the plugin that runs one agent program: claude, codex, opencode, pi or omp.23
Where a conversation is drawn
Every chat has a page of its own, at /chat/<the row's id> or /chat/<the document's path>, which a pane shows.45678 Chat adds no tools an agent can call, only instructions.9
Give a row or a document a chat
A row with its own agent is called a node agent: a property whose kind is chat-agent-session, with the rows under it as its memory.10 A document keeps that key in its frontmatter and is its own memory.111213
| Kind | What a value means |
|---|---|
chat-agent-session |
The engine, and after a colon the conversation: claude, or claude:0f3c8d21-…. |
chat-agent-slept |
When olai last shortened that memory. Only olai’s own pass writes it. |
chat-agent-sleep |
on lets olai shorten that memory on a schedule; absent or off does not. |
chat-opens |
On a document: beside opens its chat with the document beside it. |
The + beside Chats and the palette’s New chat ask which node or document a chat is for.141516
Let olai shorten a node agent’s memory
olai can shorten a node agent’s memory, and does nothing until you ask. The line under the conversation carries Sleep, with a switch, and Tidy memory, which runs a pass now.17 A chat about a document has neither.18
Switching chat off
Set on: no on the chat node in _olai/Settings.olai, or use its switch in the plugins panel (settings).19
What chat draws, place by place
| Place | What chat draws there |
|---|---|
| inside a row | The conversation, the line naming the agent, and the box you type in. |
| a node’s page | The agent line under the title, and the conversation and the box after the rows. |
| the chat’s own page | The whole conversation, headed by the name of the row or document it is about. |
| the line at the top of a document | How that document’s chat stands, Chat about this page and Open beside ›, or the box that starts a chat. |
| beside a row | What the row’s agent is doing, or a button to start an agent while one is available. |
| a row’s menu | Start an agent on a plain row; Fresh start, Close the chat and the sleep entries on a row that has one. |
| the breadcrumbs | A mark on an ancestor row that has an agent, on a trail, a day’s row and a search result. |
| the sidebar | The Needs you and Chats sections, with a + beside the Chats heading for New chat. |
| the palette | Every agent, the New chat row and Chat about this page, while an engine can start. |
| a phone’s bottom bar | The Chats button, with a count of how many conversations need an answer. |
Where a pane already holds a conversation, the fold under its row and that row’s page take you to it.
On a phone the chat page fills the screen. The line with the item’s name and its door stays pinned under the app’s bar for the whole scroll; the rest of the head scrolls. With the document as a second tab, that strip is pinned too, and each tab keeps its place. Open
An agent that is working or starting shows a dot that pulses, with a ring around it, so a computer set to reduce motion still shows what the agent is doing. On a screen that forces its own colours, these marks are drawn in your colours rather than olai’s (theme). The words beside them say the same thing either way.
A chat about the document in front of you
Two doors offer a chat where the page in front is a document with no chat yet and an agent this machine can start. They are the box in the line at the top of that document, and Chat about this page in the palette, under New chat.
Sending writes chat-agent-session into the document’s own frontmatter, starts the agent and delivers your message once. The line’s box sends on Enter; the conversation then opens in the pane to the right of the document, once, on that press. A second chat for one document is refused with “plan” already has a chat; no conversation was created, and a path the directory serves nothing at with olai holds nothing at /notes/plan.md to talk about; no conversation was created.
A start the agent refuses keeps your words in the box you typed them in, with the reason beside them, and writes no session into the document. Sending again starts on the same document. A start that stops at sign-in leaves your words waiting for the conversation the sign-in opens.
With a chat about the document, the line says how that chat stands: the agent’s mark and its standing word. It reads nothing, so opening the document wakes no agent.
Pressing the line, or Open beside › at its end, opens the conversation in the pane to the right. While a pane holds it, both read Shown beside and take you to that pane instead.
| Where a document’s chat is named | What you read |
|---|---|
| the sidebar’s Chats and Needs you | the document’s name, with its file’s own kind mark |
| the palette | that name, with the document’s path on the second line, Agents · notes/plan.md |
| a pane’s header, a tab and the phone’s strip | that name and the word chat, plan · chat, so the chat’s column is not the document’s column |
The agent is told in its first message that the conversation belongs to notes/plan.md. It is told that the document is its only memory, and to read it again before every answer. It is also told to change it only when you ask, and to leave the --- block at its top exactly as it is.
A chat on a row is told what a node agent is told: the rows under that row are its memory.
A file’s address is its path. Rename the document outside olai and its chat moves with the file, because the tie is written inside the file rather than anywhere else.
Keep the properties under column names of your own
Say which column holds which kind with one row in _olai/Properties.olai:
{"title":"agent-session","custom":{"type":"chat-agent-session"}}
A plugin may only declare a key carrying its own name, so switching a plugin on cannot take over a column you have been using for something else. You can name a column last-consolidated for chat-agent-slept, agent-sleep for chat-agent-sleep and opens for chat-opens the same way.
What a tidying pass does, and what the Sleep line says
A pass is one turn you can read: one message olai sent, and the agent’s edits under it as ordinary outline changes. Rows are moved under an Archive child, grouped by month, and nothing is deleted. Numbers, dates and names are copied exactly, and a fact that changed keeps its earlier wording in the note.
One pass touches at most about a fifth of the rows and writes only under that row. It commits its own writes as olai: sleep: <title>, so git revert puts the rows back (git). A question asked inside a pass is cancelled after sleep-question rather than shown to you, and one pass runs at a time per directory, so asking for a second is refused in words.
| What it says | What is true |
|---|---|
off in Settings |
sleep is off for this directory, so there is no switch to offer. |
last 3h ago alone |
Nobody has asked for this one. |
no conversation yet |
The node has no conversation to hand a turn to. |
nothing new to tidy |
Nothing has changed since the last pass. |
too little to tidy · 2 of 5 rows |
Some rows changed, fewer than sleep-floor. |
when this chat is quiet |
A turn, a question or an unanswered form is in the way. |
next in 4h if left alone, or due now |
The quiet window is running, or has closed. |
tidying now |
This node’s pass is running. |
last pass failed · not before 14:05 |
A pass failed, and olai waits until then to try again. |
Settings
All of these go on the chat node in _olai/Settings.olai, and each has a field in the plugins panel (settings). A duration is a whole number and a unit out of ms, s, m, h and d, at most 2147483647ms. A duration olai cannot read warns and falls back to the default.
| Setting | Default | What it does |
|---|---|---|
on |
yes |
Whether this plugin runs at all. |
idle-ms |
172800000 |
How long an idle chat keeps its agent running, in milliseconds. |
sleep |
on |
Whether olai may shorten a chat’s memory on a schedule. Each chat still has to ask. |
sleep-after |
6h |
How long a node agent is left alone before olai shortens its memory. |
sleep-floor |
5 |
How many rows must have changed since the last pass before olai shortens. |
sleep-latest |
7d |
How long a changed row may wait before olai shortens anyway. |
sleep-tick |
15m |
How often olai looks for a node agent whose memory it could shorten. |
sleep-question |
20m |
How long a tidying turn may sit on a question before olai stops it. |
sleep-limit |
1h |
How long one tidying turn may run before olai stops it. |
remind-every |
20 |
Every how many messages a node agent is reminded where to write. Zero never reminds. |
What chat refuses to do
Eight node agents are awake at once. Opening a ninth is refused in its own conversation with All 8 agents are awake — put one to sleep in Chats., and that refusal offers no retry button, because the thing to press is Put to sleep on another chat. The attempt waits where it is and is retried the moment a place frees up. A browser tab that closes takes its waiting attempt with it.
A conversation the engine cannot load is a different refusal. It names the machine, shows the engine’s own sentence in a muted line, and offers one button to start a session. It does not heal on its own, and it never waits for a place.
Chat keeps at most 32 choices an agent is waiting on, rejects any an agent tries to write itself, and cancels queued messages when a choice is cleared or replaced. It stores the choice you made and draws how many are waiting, without reading what they mean: kolu and odu draw their file pickers there, and mail draws its switch there.
An action naming a conversation you are not looking at is refused rather than applied to another one, so a read, a send or a retry cannot land on the wrong chat.
What other plugins get from chat
Every plugin that can reach a conversation uses one of seven services chat provides.
| Service | What it offers | Which plugins use it |
|---|---|---|
agents |
Which engines this build can run. | claude, codex, opencode, pi, omp |
deliveries |
A way to send a message into a conversation. | kolu, odu, mail |
session-start |
What to ask this machine when a conversation opens. | kolu, odu |
chat.seating |
Which rows have agents, with the engine and session of each, from one reading of the directory. | xyne-spaces |
watching |
What a plugin that mirrors a conversation is told. | xyne-spaces |
conversations |
Starting a chat on a node or a document, speaking into the one there, and which agents can be started. | vault-plugins |
chat.beside |
Opening an item’s chat in the pane beside the page a press came from. | vault-plugins |
The name conversations belongs to olai’s core rather than to chat, and chat is what stands behind it while it is running. A plugin asks core for it on each call and gets either the service or nothing, so a plugin that can work without chat is never held up by it.
It offers four calls, and every one of them names a node or a document. open starts the chat of that item, gives it an agent and sends a first message. say speaks into the chat of an item, here takes a list of items and answers which of them have a chat, and engines says what this machine can start.
There is no call that reads a conversation: a plugin may start one and talk to it, never hold a copy of what was said.
Chat’s navigation component offers chat.beside, rather than the plugin itself, because opening a pane is a call on the router that component holds. A serve with no router leaves a plugin waiting for it instead of handing over something that does nothing, and the page draws no button. Its open takes the item and the pane the press came from, and chat decides the rest: the pane to the right, or the pane that already holds that chat.
A serve with no chat plugin leaves all seven unavailable, and the plugins panel says so on each plugin’s row, naming what it is waiting for. The runtime resolves that the moment chat is back.
Footnotes
-
Talking to an agent explains how to work with an agent. This page describes the plugin itself: what it needs, what it draws, and what it stores. ↩
-
With no engine available the agent menu says
No agent is set upand offers Open plugins. The palette offers no New chat row while nothing can start. ↩ -
OLAI_AGENT_PATHlists the directories that hold those programs; unset, olai searchesPATH. Switching one engine plugin off, or emptying the path to its own program, makes only that engine unavailable. The other engines that are switched on are still found, and conversations carry on. ↩ -
A chat’s page is headed by one line that stays in view: the name of the row or document it is about, how the chat stands, and Open
beside › . The path and the agent line scroll with the conversation, whose box is pinned at the foot. There are no breadcrumbs. With no chat yet, a box reading Ask about… stands in its place. ↩ -
The Open beside › button opens the conversation in a new pane to the right, taking no pane already open. Where a pane already holds that conversation, every other place draws one line reading Shown beside, which takes you to that pane. A link clicked inside a chat pane opens in the pane beside it. ↩
-
Chat draws in ten places, from inside a row to the phone’s bottom bar. The closed block below says what it draws in each. ↩
-
A document’s page carries one line at the top, under the path: the agent’s mark, how its chat stands, the words Chat about this page, and Open beside ›, which opens the conversation in the pane to the right. No other page has one, not an outline, a day, the Agenda, the Trash or a file olai only shows.
Without a chat about that document, the line holds a box reading Ask about plan… where
Entersends, and an agent picker where more than one agent can start. ↩ -
Every row a conversation names is a link you can click. A reference an author wrote, the result of a write, and an id in backticks all select that row in whichever outline is showing it. A sidebar row, a Needs you row and an agent in the palette open the chat’s own page instead, so that you can read the whole chat. ↩
-
The paragraph chat adds to every conversation tells the agent three things. A person reads the answer in the pane beside the outline. An id in backticks is clickable, while one in a code fence is a quotation. A link to an address inside olai is opened in place. The mcp plugin puts this paragraph into the instructions an agent receives when it starts. ↩
-
What a node agent writes under its row goes into your files. Each kind claims the property key spelled the same way as itself, so you need not declare any of them. olai never adds the property for you, and it never treats an undeclared column as one of these kinds. An agent may write none of them: an agent that gave itself the property would be deciding on its own that olai may wake it.
The closed block below shows how to use column names of your own. ↩
-
A document’s chat lives in the
---block at the top of the file.chat-agent-sessionsays which conversation the document is having.chat-openssays where that chat opens. olai refuses a write by an agent that changes or drops either of them, so an agent rewriting the file through olai keeps that block as it is. ↩ -
A program editing the file outside olai is outside that fence. A
git pullcan restore the---block without the key. The chat page then saysplan no longer names this conversation, that the conversation is untouched, and offers Tie it to plan again, which writes the key back. That offer stands while the pane stays open: a reload takes it away, and so does Close the chat in this tab. A second tab holding that page keeps it. ↩ -
The chat page of a document carries Opens, with a switch reading
aloneorwith plan beside, which writeschat-opens. Opening that chat from Chats obeys it:besidedraws the document and the conversation side by side, as one address, so a reload brings both back. A node’s chat always opens alone, because a row has nowhere to keep the switch. ↩ -
The first step lists Here, the chats you were last in under Recent, and every matching node and document under Nodes and Notes once you type. Nothing is created but the chat itself: it belongs to the node or the document you choose. An item that already has a chat reads
has a chat, and choosing it opens that conversation. The second step takes your first message, and the agent to start where more than one can. ↩ -
A chat is named after what it is about: a row’s own title, or a file’s name without its suffix,
planfornotes/plan.md. AREADME.mdtakes the name of its folder, soplugins/swatch/README.mdreadsswatch. Rename the file or retitle the row and every place that names the chat says the new name. ↩ -
A conversation is listed only where a row or a document names it. Close the chat takes the key off, so olai lists that conversation nowhere afterwards, and a conversation you started outside olai is on no list for the same reason (node agents). ↩
-
The switch reads On or Off. The row menu’s Sleep when idle and Stop sleeping when idle write the same property, and the palette offers the same choice for the conversation on screen. Asking for a pass while
sleepis off is refused withsleep is off in this directory's settings. The closed blocks below list everything that line can say, and the settings behind it. ↩ -
Asking olai to tidy a document’s chat, or to put that chat to sleep, is refused with
a note's chat keeps its memory in the note itself, so olai never tidies it or puts it to sleep. ↩ -
To stop using one agent, switch that engine’s own plugin off instead. Turn chat off when a deployment asks for it, or when this serve should not be a chat for a while.
Switching it off removes the conversations, the chat pages, the sidebar sections, the palette rows, the line at the top of a document and everything in the closed block below, including any New chat step you had open. Every page is then whole, outline and document editors already on screen keep working, and switching chat back on restores what it draws. ↩