Yard Docs
Sign in
On this page

Chat

Talk to the workspace agent and project agents, each chat in the room of its place, with your own chats in tabs, context from docs and canvases, attachments, a queue and question forms.

Updated November 6, 2026 · 36 min read

On a canvas tab, the chat is a box floating at the bottom right of the page, over the canvas, so the canvas always keeps its full width. The button in that corner (it names the agent, what it is doing and how many messages you have not read) opens it; Minimise chat in its header, Escape inside it or ⇧⌘J puts it away again. Drag its left edge to resize it; the width is kept per browser. It is the same box on a narrower window; on a phone the chat is the bar under the page and a full-screen sheet.

On other pages, on a window 1150px wide or wider, the chat is a column at the right of the page; drag its left edge to resize it. On a narrower window it is docked on the bar under the page: open, it is a panel standing on the bar's bottom edge at the right, 440px wide. Your chats and everyone else's are tabs inside the panel, under its header: the open one is outlined, a dot shows a chat whose agent is working, and + starts a new chat of your own. One chat is open at a time. A tab can be dragged onto the Start work composer to give it the chat as context.

The list button at the end of the tabs shows every chat as a list in place of the conversation: whose it is, when it was last active, the messages you have not read, and Working, Needs you or Failed while its agent works, waits for your answer or stopped on an error. Its heading counts the chats that are working and the ones that need you, and a dot on the button shows that an agent is working while the list is closed. Pick a chat to open it; press the button again to go back.

As a column, the chat collapses the way the left sidebar does: the Collapse the chat button in its header (or ⇧⌘B, Ctrl+Shift+B elsewhere) folds it to a narrow rail. The rail holds the button that opens the column again, + for a new chat, and one avatar per chat with a dot while its agent works (blue), needs you (amber) or failed (red). Pick an avatar to open the column on that chat. Whether it is collapsed is kept per browser.

The header has two buttons. Expand (a square) makes the panel 640px wide, from just under the toolbar row to the bottom; Shrink (two squares) brings it back. The × minimises the panel (so does ⇧⌘J, Ctrl+Shift+J elsewhere, which also opens it again). It never closes a chat: for that, use the × on the chat's tab (see below). The header's … menu holds Clear conversation and Start my own chat from this one.

While the panel is minimised, the bar shows one chat button at its right end. It names the agent, says what it is doing (Working, Waiting for your answer or Ready) and counts the messages you have not seen, in all chats together. Press it to open the panel. While the panel is open the bar shows the canvas tabs only.

To resize the panel, drag its left edge, its top edge or its top-left corner. It stays in the bottom right corner, is never smaller than 320 by 320px and never larger than the page. Expanded, only the left edge resizes, and that width is kept separately. The handles also take the keyboard: Tab to one, then the arrow keys move its edge 16px at a time. Double-click a handle (or press Home on it) to go back to the default size. The size, and whether the panel is open, expanded or minimised, are kept per browser.

On a phone the bar's chat button is an icon with the count, and always in view. Tap it to open the chat as a full-screen sheet with the tabs and the composer; the composer stays above the keyboard while you type, and the sheet stays open after you send so you see the reply. Close chat at the top right takes you back.

Rooms: whose chat this is

Every chat belongs to one place: the workspace, a project, a doc, a prototype (or a stat), a canvas or a goal. That place is the chat's room. A band at the top of the chat names it: a tag with the kind (Workspace, Project, Doc, Prototype, Canvas, Goal), the place's name, and under it where the place is ("useyard.app › Work › Fix invite emails"). The workspace's own room is drawn in the dark stone of the frame and says "The workspace's own chat".

While a place is open (a project's page, a canvas, a doc), a switch under the band offers its two rooms: Workspace and the place (This project, This doc, "Dev canvas"). Each side has its own tabs: a project's tabs never list the workspace's chats, and the other way round. A doc's chats are its own room too: the workspace's room does not list them.

Selecting a block does not change the chat. A prototype's or a stat's own chat opens from the block (Open its log); its band has a back arrow that returns to the room it was opened from.

A project's chat switcher opens another of its rooms wherever you are, and says how many messages there are new. All chats lists every chat you may read, grouped by Workspace, Projects, Docs, Prototypes, Canvases and Goals, each with what it is doing (answering, working, needs you, or when it was last active). Pick one to open it in its place.

Pages with their own chat

Four pages have their chat as part of the page: a spec to review, a project, an investigation's tab and Insights. An investigation's tab is a canvas: its chat is the floating box of every canvas tab. On the others, from 1150px, the chat is a fixed column at the right. It has no minimise button and cannot be floated; only its left edge resizes it. On a narrower window the chat button opens it as a sheet over the page.

  • A spec to review shows the project's agent: a message there changes the spec. Beside Chat there is a second tab, Context N, which lists what the spec is written from. See the spec page.
  • A project shows its agent in the project's room, with the project's status at the right of the band ("Working"). See the project page.
  • An investigation's tab shows the investigation's one chat, its band tagged Investigation and named by the question. It has no row of chat tabs.
  • Insights shows the workspace's room, "Ask about Insights" under its band. Its send button reads Ask, and Edit context under the chips adds a repository or blocks to the question.

Project chat and chats beside things

There is no workspace chat. Anything you start from the workspace overview or the context box is a project, with its chat on the right of its page. A doc, a file, a sheet, a block and a goal each have a chat beside them, about that thing. Old chats with no place of their own became projects, folded under Earlier until their next message.

In a project's chat, a file, doc or other thing named in a reply opens over the chat, not in a new tab (see what opens in place). Ctrl or ⌘-click still opens a new browser tab; on a file with a GitHub link it opens it on GitHub.

Your chats and everyone else's

Chats belong to a person. The tabs at the top list your own chats first, each named by how it started, then everyone else's by name; a dot shows a chat where the agent is working. Everyone with access can read every chat, live.

The workspace opens on your own chat. A project opens on yours if you have written there, otherwise on the one that was active last.

Only a chat's owner writes in it: it keeps one agent session on their own agent account. In someone else's chat the composer is replaced by a note with Summarize and continue in a new chat: your own agent summarizes the conversation, and a new chat of yours starts from that summary, linked back to theirs. Start my own chat from this one in the chat's … menu (or /fork) is the quick way without a summary: your message goes to a new chat of yours that quotes theirs as text. Viewers can read chats but not write in them. Only the chat's owner can close, clear or retry it.

A chat started on a doc belongs to the workspace and to that doc (a doc kept apart for some people keeps its chats with it): the doc's chat column lists its chats (see chats belong to a doc), and a chat started elsewhere takes the doc of its first message. A doc (or some of its sections, by heading) can be given as context: the agent gets its file and everything it references or shows, all the way down (see context is files).

Several conversations, and clearing one

You can have several chats of your own, in the workspace and in each project. Each is a separate conversation: the agent in one knows nothing of what was said in the others, and they can work at the same time.

  • New chat (the + before the tabs, or /new) opens an empty chat in a new tab.
  • Clear conversation (in the chat's … menu, or /clear) empties the chat you are looking at. Yard asks first; after that the agent no longer knows what was said.
  • Compact (/compact) asks the agent to summarize the conversation, then clears it and starts the chat again with that summary as its first message, so the agent continues with the important context and a short history.
  • The × on a tab closes that chat. Its tab goes away for everyone. A chat with messages asks first. When you close your last one, a new empty chat takes its place.

Files and changes the agent made stay in all three cases. A chat cannot be cleared or closed while its agent is working: stop it first. Only you can clear or close your chats.

Context

Every chat has the same composer. The room's own chip comes first in the box and stays; the placeholder names the place ("Message the Fix invite emails project…"); a line under the box says what the chat reads. The chips after the first show what the agent will also look at:

  • With blocks selected on a canvas, each one is a chip. Remove a chip with its × to leave it out.
  • With nothing selected in the workspace, the agent gets your message and nothing else: no block of the canvas goes along. (If you chose The whole workspace for your account, it reads "Whole workspace" and the agent gets a list of every block on the canvases you may open; see account preferences.) The agent is told which doc or canvas the message was sent from.
  • With nothing selected in a project, it reads "whole project" and the agent gets a list of everything linked to the project. (If you chose Only the spec and what I select for projects, it reads "the spec, and what you select" and the agent gets only the spec.)
  • Something from outside the room (a doc in a project's chat, a goal, another project) is attached as a link: its chip is dashed, with a link icon and where it came from ("Pricing notes · from Docs"). It stays where it is and is not added to the place; the agent is told what it is, its state and where to find it.
  • Blocks are context only when you select them (or pick them with +): nothing goes along by itself. Each message tells the agent which doc or canvas it was sent from, so one chat follows you from page to page. Your sidebar Pinned items are yours to open quickly; the work composer offers them as a Pinned chip you can unselect per message.

For repositories, the lines you highlighted are marked as worth particular attention.

Context is files

Whatever you give a chat (a block, a doc, a canvas, a prototype, a file, a repository, a monitor, a stat), the agent is given files, not pasted text: a list of each thing with its files and, under it, the files of everything it depends on. What each thing is as files:

Given The agent gets
A doc Its file in docs/, and everything it references or shows: blocks, other docs, prototypes, files, repositories, followed all the way
A prototype Its manifest, the pages and pictures of its kept screens (or the ones you picked), and its block file with the comments, replies, pins and change log; plus what the comments attach
A note or spec Its Markdown file and block file, and what it attaches or references
A group or a canvas Each block inside it
An image or file The file
A code excerpt or repository The repository's checkout, with the excerpt's lines named
A monitor or stat A file Yard writes for the turn (a stat's values of "Only people" columns are left out of it)

The same thing gives the same files wherever you give it: in the workspace chat, a doc's chat, a prototype's own chat, an investigation, a goal or a new project, and whether it came as a chip, a drop or a pick in Edit context. A thing on a canvas or doc you may not open is named as left out, with nothing of it given. A message can also give files by their path; each is read as the thing it is (a doc's file is the doc).

On Insights the first chip is Stats: Every canvas: the agent gets each stat's title, its query and its last result. Values of columns set to "Only people" are left out before the message reaches a model. An answer that was given stats ends with a line Yard writes, not the model: "Read: Newest customers. Not read: name and email, which are set to "Only people"." Remove the chip to ask without the stats. Edit context there opens the same context picker as the work composer, so a question can take a repository and blocks from any canvas. See what the AI may read.

Attachments

Attach files with the composer's Attach button, by pasting, or by dropping them on the composer. The button opens the same menu in every chat: This device, A workspace file (starts an @ search), A screenshot of a screen, window or tab you share (where the browser can), and then a search over the workspace's docs, blocks, prototypes, canvases, goals and projects. Its results come in two parts: what is in this place, and Elsewhere in the workspace · attached as a link.

Anything dragged from the sidebar or a canvas onto any chat's composer is attached the same way; nothing is refused. While you drag, the box says it stays where it is. On a canvas, dropping blocks on a project's block (the spec it was made from, or its report) links them into that project, as dropping them on its row in the sidebar does; hold ⌥ (Alt) to attach them to the next message in that project's chat instead. They upload into the workspace and the agent can open them. A file can be at most 50 MB, or 200 MB when the organization has a storage bucket. In a doc's chats, what you attach also lands in the workspace's Uploads. Files already in the workspace or a project are attached by typing @ and part of the name (see below); nothing is uploaded, the agent is told where they are.

In a project's chat A repository picks a repository to add to the project, and Blocks into this project picks blocks from a canvas. A block or repository you pick is linked to the project and shows as a chip in the composer; your next message tells the agent it was newly added.

Commands, files and dictation

  • Type / at the start of a message for commands: /stop stops the agent's turn, /model opens the agent and model picker, /attach opens the file picker, /screenshot (in a doc's chats) attaches a screenshot, /spec <what it should do> opens the work composer on Work with Create a spec first, with that text and the selected blocks as context (see projects and specs), /new starts another chat in a new tab, /clear clears the conversation, /compact summarizes it and continues in a fresh chat, and /discard empties the message, its attachments and context.
  • Type @ and part of a name to attach anything listed under Resources in the sidebar (docs, prototypes, sheets, repositories, research) or a file from the chat's directory (the workspace, or the project with its worktrees). Resources come first, each with its kind's icon and folder; this place's own things lead, then each folder in order. A name matches from its start or from the start of any word (@road finds "Product roadmap"). A resource you pick becomes a chip, the same as dragging its row onto the composer; a read-only chat offers none.
  • The microphone button dictates into the message. With a Mistral key connected under Integrations (yours, or your organization's) it records until you press it again, then the text appears; any browser that can record works. Without one it uses your browser's speech recognition (Chrome, Edge, Safari; the browser may send the audio to its own service), and where there is none the button is not shown.

↑/↓ move through the list, Enter or Tab picks, Esc closes it.

Moving through a long chat

With two or more messages from people in a chat, a slim rail runs down the left of the conversation, with one tick per message. The longer, coloured tick is the turn you are reading: the message and everything up to the next one. Hover a tick to see the message's first line and time, and click it to put that message at the top of the chat. If a reply is coming in, the chat stays there and offers New messages.

From the keyboard, Alt+Up and Alt+Down go to the previous and next turn while focus is in the conversation. Tab to the rail, then use Up, Down and Enter to pick a tick. The rail covers what is loaded: its up arrow brings in earlier messages, as Load earlier does. It does not show on touch screens.

Sending, queue and stop

Enter sends; Shift+Enter starts a new line. A long message scrolls inside the composer, so the chat above it and Send stay in view. A chat runs one message at a time. While the agent works, Send becomes Stop, and once you type something (or attach a file) a Queue button appears next to it; on a phone or in a narrow panel it is an arrow. Queue or Enter puts the message in a Queued list above the composer and leaves the running turn alone. Queued messages start one at a time, in the order they were sent, when the turn ends, also after Stop. Take one back with ×, or all of yours with Clear all (shown with two or more; the workspace owner clears everyone's). When the runner is busy with other turns, the chat shows your place in its queue ("Queued: position 1 on the runner"). Start now next to it runs your turn right away, on top of what the runner is already doing. Change limit opens the runner's settings on Agents and load, where Agents at once says how many turns it runs before the next ones wait; the link shows for people who manage the runner (organization admins, or its owner for a personal runner). On a runner Yard shares between organizations, turns start in order and neither link shows.

Steering a queued message

To tell the agent something while it works, without stopping it, steer the message into the running turn. Steer on a queued message (an arrow on a phone) sends it now: it leaves the queue, the reply so far stays where it is, and your message follows it in the chat, marked "steered". The agent reads it at its next step (after the command or edit it is on) and its reply goes on from there; nothing is lost and no new turn starts. To skip the queue for a new message, press Steer next to Queue, or ⌘/Ctrl+Enter; Enter still queues.

Steering works with Claude Code, on runners from version 0.17.0. It is not offered while the turn waits in the runner's queue, for Codex or Cursor (their CLIs read nothing after the prompt), or for messages waiting for AI usage, "carry on" turns and spec or implementation runs. If the agent cannot take the message at that moment (its turn is just ending), it stays queued and runs next, and a notice says so. You steer your own messages; the workspace owner can steer anyone's.

When the runner's machine is overloaded (its CPU or memory is over the threshold set in the runner's settings), new turns wait too, and the chat says so: "The runner is under heavy load (CPU 94%). Your message is queued (position 3) and will start automatically." The line keeps your place up to date and changes to "Runner load is back to normal. Your message has started." when it starts. The queued line and the composer show Runner busy meanwhile. Start now still works, but asks first, because it adds to the load. When the runner pauses a workspace that nobody is using to free the machine, its chat says so, and again when it restarts by itself.

If your agent account runs out of AI usage, the turn does not fail: the message waits (it shows as "Waiting for AI usage" in the queue), and so do your other messages on that account, in every chat. They start by themselves when the limit resets, or press Resume in the chat once usage is back.

A reply that ended with an error has Retry: it sends the same message again, and the agent carries on from the conversation so far. The Resources tab of the workspace settings lists the workspace's turns on its runner (running, waiting, failed), with Retry all failed.

The work goes on when you close the page. When the runner's connection drops for a moment (its machine slept, the network blinked), the agent keeps working, and the chat picks it up again once the runner is back, for up to five minutes. A turn that is cut off anyway (the runner or Yard restarted, or the runner stayed away longer) carries on by itself once the runner is back, ahead of anything sent meanwhile; a turn you stopped does not. Messages that were already queued when the runner went offline run once it is back. While the runner is offline, the chat is read-only.

A turn that keeps being cut off is carried on three times in a row at most. While it is, one line in the chat counts the attempts ("Retrying when the runner is back (attempt 2 of 3)") and is rewritten in place; the replies in between show no error and no Retry. A runner that drops off just as a turn starts ("The runner disconnected.") counts as a cut-off too. When the attempts run out, the line says Yard stopped retrying, and the reply ends with "The agent stopped with an error." and the reason, with, for the chat's owner, Resume beside Retry. Resume picks up where the agent left off: the agent is told to check what it already did and finish the rest, and your message is not sent again. Retry sends the message again. Pressed while the runner is still offline, Resume waits in the queue and starts when the runner is back. Retry after a continuation failed sends the message you wrote, not Yard's "carries on" line; when you wrote nothing since the last reply that went through, it carries the turn on once more instead. In a project, Resume on the project's page and Resume on its row on the Projects page do the same.

By default Yard also does this by itself: when the runner reconnects, chats whose turn was cut off carry on, once per reconnect, so a turn that keeps taking its runner down does not loop. Turn it off in the workspace settings, under General, Automation: Carry on interrupted work when the runner is back; the chat then waits for its owner to press Resume.

AI usage

A ring in the composer, before Send, shows the AI usage. Press it for the details: what the conversation used (input, output and prompt-cache tokens, the number of turns, and the cost when the agent reports one, as Claude Code does). The details start with the agent account in use and the provider account it is signed in as ("Claude 2 · [email protected]"). The ring appears once the conversation has used something.

When your agent account reports its plan limits (a Claude subscription: the 5-hour and weekly windows), the ring fills with the window that is closest to its limit, and the details show each window's bar and when it resets. They update while a turn runs, and are as of the last turn: Yard does not ask the provider between turns. The ring turns yellow above 80% and red when a window is used up. Only you see your plan limits; someone reading your chat sees its tokens and cost, and an empty ring. Accounts on an API key, Codex and Cursor show tokens (and cost when reported) only. See agents.

Replies

Resting the pointer on a message, yours or the agent's, shows how long ago it was sent and, for a reply, what that turn used ("5m ago · 3.2k tokens"); the full date is in its tooltip.

A reply shows the agent's text and, folded underneath, the steps it took (files read and changed, commands run) and its plan. When the agent looked at a picture, its step shows that picture. File names in a reply that exist in the workspace open in Files, at the line when one is given. A data model the agent writes as a schema block shows as tables, the same way it does in a note or spec.

Pictures in a reply

Agents show the screenshots and images they make in the reply. Pictures in a row form a gallery of thumbnails; pictures the turn made but only named (a path in the text, a file a command wrote such as a yard-shot capture) are added under the reply as Images from this turn, once each file exists.

Click a picture to open it in the image viewer, the same one a prototype's screens open in. The reply's pictures are in a strip at the top; ← and → step through them. Zoom with the buttons under the picture, the wheel, a pinch or + and −, drag to move, and 1:1 shows it at its own size. Esc closes, and Open in Files opens the file. Pictures in a project's report open the same way. From the viewer you can:

  • Reference in message: attach the picture to the message you are writing, so the agent knows which one you mean.
  • Comment: write what should change and press Add comment (or ⌘/Ctrl Enter). The picture is attached and a line On `uploads/today.png`: … is added to your message. Step to the next picture and comment on it too, then send them together.

Hold ⌘ or Ctrl when clicking to open the file instead of the lightbox.

Files to download

When an agent makes a file for you to take away (a PDF, a spreadsheet, a slide deck, an archive) it links it in the reply, and a Download button (the arrow) follows the link: one click saves the file under its own name. The same button follows a file named in code (`out/menu.pdf`) when the file is there. Code and Markdown files only open in Yard, unless the link asks for a download ([spec](spec.md "download")). Links in Markdown files shown in Yard, such as a project's report, get the same button.

Agents name repository files, pull requests, issues and commits by their address on GitHub, so what they write still works when it is copied out of Yard. A link to one of the workspace's repositories shows as a chip: a file with its lines, a pull request or issue with its state, a short commit. Resting on a chip shows a card with the details (title, author, branches, changed lines). A file chip opens the file in Yard, in the project's worktree when it has one; hold ⌘ or Ctrl to open it on GitHub instead. The same chips appear in notes and specs, where the link stays an ordinary Markdown link.

Mentions in messages

What a message names is drawn as a highlighted chip. In your own messages an @file you picked or attached becomes a file chip, and @Name of someone in the chat a pill in the colour of their avatar; an email address or an @word that names nothing stays text. Under the message, what it was sent with (docs, blocks, repositories, monitors, files) is a row of chips grouped by kind; past six, +N more shows the rest. A file already named in the text is not repeated there. In a reply, a reference to a block, a doc, a prototype, a file, a picture or a web address is a chip too; a block that was deleted shows as missing.

Resting on a chip, or reaching it with Tab, shows a card: what it is, where it lives, a short preview (a doc's first lines, a monitor's last run, a repository's default branch) and Open. A file's chip shows the file's first lines, as file links do. Escape closes the card and leaves the chat open. On a phone, a tap on a chip shows its card; tap Open to go there.

If your agent account was signed out, the reply says so with Sign in again, which opens the sign-in dialog right on the chat's page for that account. Once the account is signed in again (there, or from settings in another tab), the notice turns into "Signed in again" with Try again, which sends the message once more.

Subagents

An agent can hand parts of its work to subagents (Claude Code's Agent tool), in the foreground or in the background. While any runs, the turn shows Running agents above its steps: what each was asked to do, its kind, whether it runs, is done, failed or was stopped, and how long it has run. The list comes back after a reload.

What a subagent does stays out of the main reply and step list: there the hand-off is one step, Delegated: …. Press a subagent in the list, or its Delegated step, to open its own thread in place of the chat: what it was asked, its steps (each opens to show what it sent and got back) and what it answered. Chat or Esc goes back to where you were. Finished replies keep their subagents, so their threads open afterwards too, read-only.

Stop on a subagent ends that subagent only: the agent is told it was stopped and carries on with its turn. The chat's own Stop still ends everything. Stopping one subagent works with Claude Code; Codex and Cursor do not report subagents.

Pushes and pull requests in the chat

A project's chat records what happens to its branches, as short lines between the messages: a push (with how many commits and who pushed), a pull request opened, merged, closed or reopened, and a pull request that now conflicts with its base. The pull request number opens it on GitHub. It does not matter where it happened: the Done bar, a worktree's Git card, the agent or a terminal pushing, or someone merging on GitHub. Each change is recorded once. The line goes into every open chat of the project that has messages, and the agent reads these lines too, so it knows a pull request was already merged.

When the agent creates a follow-up project (yard project create), a line in the chat it was asked in says so, with Open project to go to it.

When the agent sends a message to another project (yard project message), a line says "Message sent to …" with Open project. In the other project's chat the message shows who sent it, with a "From <project>" line linking back.

Memory kills in the chat

When the kernel ends a command in the project's container because the container reached its memory limit, the chat of the turn that ran it gets a line naming the command, the limit and the peak (when no turn was running: the project's recent chats). Workspace owners see a Raise memory limit link with it. The agent reads the line in its next turn. See agents.

Questions and action cards

When an agent cannot continue without you, it ends with questions. They show as a form: pick one option, tick several, or type an answer, then choose Submit. A chat on a doc asks what is still open about the doc in the doc itself instead, in the section it is about; the step reads Asked in the doc · <section> · N, and your picks there come back to the chat together, as "You answered in the doc: …", when you choose Send answers under the doc. See the agent asks in the doc. In a project, the project shows Needs input until you answer, and the person who started the work is notified.

When the choice is between things to look at, such as design directions, mockups or charts, the agent can give each option a picture. The options then show as cards, the picture over the option's name: press a card to choose it (or tick it, when you may pick several). The expand button at the top right of a picture shows it large, with Choose this. A picture is a PNG, JPEG, GIF, WebP or SVG file, or a small HTML page from the workspace (up to 256 KB). An SVG is drawn as an image, and an HTML page in a sandboxed frame: neither runs scripts or loads anything from the internet. Only the page's own stylesheets and images, beside it in the workspace, are shown with it.

An agent can also end with an action card:

  • Connect cards lead to what is missing (an agent, GitHub, storage or a runner) and say "Connected ✓" once it is.
  • Suggest this to the Yard team opens a short form, pre-filled, that sends a feature request to the people who run Yard. The same goes for an integration Yard does not have yet ("Suggest it"). See feedback.
  • Write spec cards come from the workspace agent when the work needs a project, for example a change to a repository. The card lists the blocks it names; press one to see it on its canvas. Write spec… opens the Write spec dialog already filled in with its instructions, those blocks, the repositories to work in and any files to attach, without changing what is selected on the canvas. Check it and choose Create project. A block that is no longer in the workspace is left out, and the card says so. Once a project is made from it, the card says Spec created with the project's name and Open project, for everyone in the chat and after a reload. Create again… makes another one. A reply can hold several of these cards, each on its own.
  • Suggested next step cards end an investigation's reply: what to do, one sentence on why, and Start work, Write spec and Build prototype, with the one the agent suggests first. Each makes its result with the investigation's tab as context and the card's title as the request.
  • Change a setting cards point to a workspace setting that would let the agent do what you asked, for example turning on the runner's GPU or moving the workspace to another runner. Open settings opens the workspace settings on the right tab (Runner or Resources). If you cannot change workspace settings, the card says that a workspace owner or admin can, without the button.

When the box lacks something

Agents work in a box with a fixed set of tools and no administrator rights. When a command fails because something is missing there (a system package, a GPU, a device), the agent does not quietly give up. It tries, in this order:

  1. To fix it inside the box, without administrator rights, for example with a Python virtual environment or a tool installed in the home folder. It says what it installed.
  2. To point you to a Yard setting that helps, with a Change a setting card.
  3. To offer a Missing in the environment card: a pre-filled report to the Yard team, naming what is missing and the command that failed. Yard adds the runner's details itself, so the team can add what is missing (for example to the box image) without anyone logging into the machine. See feedback.

Agents never ask you to log into the runner machine, change its Docker setup or use administrator commands to work around it.

The agent in a terminal

In your own Claude Code or Codex chat, you can run the agent as its own interactive CLI in a terminal session on the box. Until you do, each message runs on its own and its reply streams into the chat as it is written.

Open in terminal (the terminal icon in the chat's header) starts the session (carrying the chat's conversation on) as an Agent tab in the bottom panel (on a phone, full screen), and you can type into it as into the CLI on your own computer. Every message after that goes to the same session, with the same context a message always carries. Messages you send while the agent answers wait in the queue until it is done. It's in every chat of your own: the floating chat, the chat beside a project page, Home or Insights, and a doc's chat column. A block's, a prototype's or an investigation's chat has none.

While the session runs, the chat reads as it always does, with Show terminal (and End session, in your own chat) above the composer:

  • What you send from the chat shows as your message, with its attachments and context, and is answered in the terminal. The terminal shows it as one pasted block, because it carries the context the agent is given; the chat never shows that context as text.
  • What you type in the terminal shows in the chat as your message, marked Typed in the terminal, and the agent's answer streams in with its tool steps, plan and subagents.
  • With Claude Code, the reply streams in line by line as the agent writes it in the terminal. While it is being written it can look plainer than the final message (it is read from the terminal); once each part of the reply is finished, it shows exactly as the agent wrote it, formatting included. With Codex, the reply arrives one finished part at a time.
  • Stop interrupts the agent (as Esc does in the CLI). The session goes on.
  • Closing the terminal's tab only puts it away: the session keeps running. Show terminal brings it back, redrawn for your window, after a reload too. End session (above the composer, or in the tab's menu) closes the CLI to free the runner.

When the CLI exits (End session, Ctrl+C twice, /exit, or 10 minutes with nobody watching and the agent idle), the chat says the session ended. Your next message runs on its own again and carries the same CLI conversation on; Open in terminal resumes it in a terminal. Work on a spec, Yard's own carrying on of a cut-off turn and messages from another project run without a terminal: one arriving while the session lives ends it first. Rich chat messages (cards, question forms) show in the chat only; the terminal shows the CLI as it is.

If the agent is working on a message when you choose Open in terminal, nothing is stopped: Terminal opens after this turn shows above the composer, the agent finishes and its reply reaches the chat as usual, and then the terminal opens on its own, carrying the same conversation on. Messages you send meanwhile are typed into the terminal once it is open. Stop ends the turn early (the terminal then opens at once), and Don't open takes the request back.

Other people see that the agent runs in a terminal and can watch it, but cannot type in it. Cursor has no terminal mode. On runners older than 0.36.0, messages you send while the terminal waits for a turn run after the terminal session ends.

Keeping a conversation

A project's chat can be put on the workspace's canvas as a chat log block with Add chat log to the workspace in the project's More menu or in the menu of its row on the Projects page. See projects and specs.

Agents working together

An agent's message says which agent wrote it, its model and effort, and the rule that picked it. Ask another agent under a reply puts a question to a second agent in a thread of its own: the first agent sees nothing of the answer until you press Send, and you can also Ask a follow-up or Dismiss it.

When an agent proposes steps you can change their words, who does each and what waits for what, then Start them. Each runs as a child thread under the project in the sidebar, with Stop. Findings show who found what, with the reviewer's verdict.

The two rings beside the model are this chat's context and your subscription's fullest window. Each is only there when the agent reported it. Press one for the numbers per model and period, with /compact and /clear.

Was this page useful?
Edit this page