# Working beside people What the people in a document see while an agent works in it, why their words always win, and how the agent handles comments, tabs and being stopped halfway. An agent works in a document while people read, type and comment around it. Its words arrive where everyone can see them, it talks in comment threads rather than in the text, and when it and a person reach for the same words, the person's words stand. ## What people see ### Placeholders for the sections to come When an agent starts a document, it first plants a placeholder for each section: a grey line with the section's plan in brackets, such as [Rollout: a gantt of the milestones by team]. A placeholder holds its section's place until the agent replaces it with the section itself, one call per section, in reading order. You cannot type into a placeholder, but you can select one and delete it. The agent then leaves that section out: the connector's guide tells it that a block a person removed stays removed. Placeholders are left out of Markdown, HTML, Typst and plain text exports. ### Words that fade in When the agent's write reaches your screen, the words it added appear one after another: - each word fades in over 160 ms; - the next word starts at most 70 ms later; - every word of one write has started within 3 seconds, however long it is; - up to 300 words fade in, and any beyond them appear at once. Only fresh writes fade in: those less than a minute old by your clock. Your own edits and other people's appear at once, and so does the agent's earlier work when you open a document. The exception is a document or tab you open within 10 seconds of the agent writing there, which plays those writes as if you had been watching: that is what you see when you follow the agent to another tab. Text inside table cells always appears at once. ### The agent's caret and avatar The agent is in the document's presence like a person, with the name and colour its connector was given: **Claude**, in `#d97757`, unless you [set others](/docs/mcp/connect/#environment-variables). Its avatar sits in the status bar with everyone else's. While its words appear, its caret walks with them, after the latest word to appear; once the last word is in, the caret rests at the end of what the agent wrote. Its name tag stays up while it writes and for about two seconds after, then fades. The agent is on one document at a time: the document or tab it last read, wrote or commented on. When it moves to another, it leaves the first, and it leaves 90 seconds after its last work there. When the connector stops, the agent leaves at once, or within about 15 seconds if the connector was stopped abruptly. ## Why your words win The connector's instructions put it in three words, "Their words win", and the connector holds the agent to them: - **The agent reads first.** Every block it reads carries a fingerprint of its content, and every read a revision number. - **Whole blocks are guarded.** To replace or delete a whole block, the agent names the fingerprint or the revision it read. If someone changed the block since, the write is refused, nothing in that call lands, and the agent receives the block as it now stands, to redo its edit around your words. - **Quoted words are exact.** To change a few words, the agent quotes them exactly, and only words that match are touched: words you have rewritten no longer match. When the quote matches nowhere, the edit is refused. - **Removed stays removed.** A block someone deleted cannot be edited, and the connector's guide tells the agent not to bring the block back. - **Commented words stay.** An edit that would remove every word an open comment thread hangs on is refused, unless a person asked for that passage to go. - **One call, one change.** Up to 64 edits in one call land together or not at all. An agent can override the guard with `force`, and the connector's instructions allow that only when you asked it to overwrite something, never over a person's text. The check covers every edit that has reached the agent's copy of the document: an edit made in the same instant, still on its way, meets the agent's write the way two people's simultaneous edits meet. [How agents edit](/docs/mcp/editing/#guards) describes the guards, and [Refusals](/docs/mcp/refusals/) lists what the agent is told in each case. ## Comments with an agent Comments sit beside the text and never change the document. The agent sees them when you ask it to look: it lists the threads with the words each hangs on, starts a thread on 3 to 6 quoted words, replies, resolves and reopens. Its comments carry its name, and it needs at least **Comment** permission to write them. How the connector's guide tells it to act on a comment: - **A question:** it answers in the thread and does not edit. - **A requested change:** it makes the change, then replies with one short sentence on what changed. - **Something nobody has decided:** it replies that the owner needs to answer. Its replies are meant to be one or two short sentences, since a thread is read in a narrow column beside the page. You read and resolve them in the comments sheet, as for anyone's ([Comments](/docs/comments/)). Each tab has its own threads. ## Tabs An agent can create a document with tabs from the start, or add one later, and it can rename, move and remove tabs. The tab strip in the app adds tabs; renaming, moving and removing them goes through an agent for now. An agent can also nest a tab under another: Entz keeps the nesting, but the strip does not show it yet. The main tab is the document itself, and the agent cannot remove it. The connector's guide says what goes where. The main tab answers the request on its own. Another tab holds material a reader opens separately (sources, raw data, working notes), or one part each when the request is a set of parts, such as one tab per team or per proposal, with an overview in the main tab. A short document stays in one tab. Each tab is a document of its own with the parent's people, so anyone who can open the document can open its tabs, and the agent is present on one tab at a time. The status bar lists everyone on any of the tabs, and when the agent is on a tab other than yours, the tab strip puts a dot in its colour beside that tab, pulsing for a second after each write. See [Tabs](/docs/tabs/). ## Following an agent Press the agent's avatar in the status bar to follow it: the view goes to where the agent writes and keeps up with its caret while the words appear. When the agent moves to another tab, the view goes with it, and the words it writes there fade in as you arrive. A hold on the avatar goes to the agent once, without following. A scroll or a touch of your own lets go, and so does choosing a tab or pressing the avatar again. You can follow an agent before it has a caret, for example while it is still reading: the view goes to where it next writes. [Presence and following](/docs/presence/) covers following in full. ## Stopping an agent halfway You can stop the agent in your client at any point. - **Each call is whole.** A write lands complete or not at all, so the document never holds half of one. - **Unwritten sections stay placeholders.** They keep their grey brackets and stay out of Markdown, HTML and Typst exports. Ask the agent later to fill the remaining sections, and it finds them in the outline; or select a placeholder and delete it. - **The agent's avatar stays for a while.** It leaves 90 seconds after the agent's last work, or at once when the connector stops.