olai
Plugins

Plugins › Integrations

Talking to an agent from a row or a page

1 min read · 19 notes, one tap away

On this page
  1. What chat needs to work
  2. Where a conversation is drawn
  3. Give a row or a document a chat
  4. Let olai shorten a node agent’s memory
  5. Switching chat off

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 beside › reads Open › there, and puts the row or document in the next tab along.

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

  1. 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. ↩

  2. With no engine available the agent menu says No agent is set up and offers Open plugins. The palette offers no New chat row while nothing can start. ↩

  3. OLAI_AGENT_PATH lists the directories that hold those programs; unset, olai searches PATH. 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. ↩

  4. 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. ↩

  5. 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. ↩

  6. 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. ↩

  7. 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 Enter sends, and an agent picker where more than one agent can start. ↩

  8. 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. ↩

  9. 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. ↩

  10. A document’s chat lives in the --- block at the top of the file. chat-agent-session says which conversation the document is having. chat-opens says 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. ↩

  11. A program editing the file outside olai is outside that fence. A git pull can restore the --- block without the key. The chat page then says plan 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. ↩

  12. The chat page of a document carries Opens, with a switch reading alone or with plan beside, which writes chat-opens. Opening that chat from Chats obeys it: beside draws 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. ↩

  13. 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. ↩

  14. A chat is named after what it is about: a row’s own title, or a file’s name without its suffix, plan for notes/plan.md. A README.md takes the name of its folder, so plugins/swatch/README.md reads swatch. Rename the file or retitle the row and every place that names the chat says the new name. ↩

  15. 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). ↩

  16. 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 sleep is off is refused with sleep is off in this directory's settings. The closed blocks below list everything that line can say, and the settings behind it. ↩

  17. 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. ↩

  18. 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. ↩