Agents
Connect Claude Code, Codex, Cursor or Grok with your own account, set up the workspace's agents and rules, and know what an agent sees and where it runs.
Yard works with Claude Code, Codex and Cursor, and with Grok as Experimental, through the generic ACP bridge and an API key only. They do the writing in chats and the building in projects.
On a Windows runner in direct mode
agents run on the PC itself, in Git Bash: the programs they start open their
windows on your screen, and they look at them with yard-shot screen --window "<title>".
Your own account
There is no shared organization key. Each person signs in to the agents they use, and every message runs with the account of the person who sent it. If you send a message without a connected agent, the chat shows Connect an agent to chat with the same sign-in options, and keeps your message until you are connected.
Connect an agent
Under Account settings, Agents, choose Add agent. For each agent you can Sign in with your account or Use an API key.
Signing in runs the agent's own sign-in on one of your organization's runners, so a runner must be online. Started from a workspace's chat, it runs on that workspace's runner when that one is online; otherwise on your own runner first, then your organization's, then an official one. If it fails, Start again lets you pick another runner.
- Choose Open the sign-in page and approve Yard there.
- Claude Code and Cursor show a code: paste it into Yard and choose Submit.
- Codex uses a device code instead: copy the code Yard shows, enter it on the sign-in page, and Yard notices once you approve it.
If your connection drops for a moment, the sign-in waits for you. If it takes too long, choose Start again.
An API key, like a sign-in, is sealed to your organization's vault: only its runners can open it, Yard's servers cannot. The runner opens it only for the turn. It is never shown again. A key account is marked "API key" and has Replace key instead of Sign in again.
You can connect more than one account of the same agent, and bind them to a workspace in order under the workspace's Agents settings, each limited to the rules it may serve. Outside a workspace's order, Use this picks the one that runs your work. Its status reads "Not signed in", "Sign-in expired" or, for a key, "Key rejected" when it needs your attention. Remove forgets it.
Each signed-in account shows the provider account it is signed in as (its email), read after sign-in. Rename gives an account another name (up to 60 characters). Signing an account in again as a different provider account is refused and the old sign-in is kept: "Signed in as x@…, but this account is y@…. Add it as a new account instead."
When a turn is refused because an account needs signing in again, the chat says so with Sign in again, which opens the sign-in right in the chat's page. Once it is signed in again, there or from settings in another tab, the notice reads "Signed in again" with Try again (see chat).
Workspace agents and rules
Agents and rules belong to the workspace; accounts stay personal. The Agents tab of the workspace settings lists each agent with its model, effort and instructions, and the accounts you bound to it. A new workspace starts with one agent per provider and a default rule. Everyone in the workspace can read them, so instructions must not hold secrets.
A rule says who does a kind of work: an ordered list of agents, one is
fine, and instructions of its own. In order takes the first agent on the
list that can work: one that is off, signed out or out of usage across your
accounts is walked past, and the next takes over. At the end of the list the
workspace's setting decides whether it asks you or waits. Agent picks lets
the lead agent choose, only from the list. An agent's and a rule's instructions
reach every turn, also in a terminal. A project can change a rule for itself in
its Crew tab, which then reads Changed for this project, with Reset
to the workspace. Each rule's ⋯ menu there has Rename, Edit rule
(its name, what it is for, its agents in order, for This project or The
workspace), Duplicate (a copy in the workspace) and Delete rule…,
which asks whether to delete it Only in this project (Reset brings it
back) or In the whole workspace. Work a deleted rule would get goes to the
default rule, which cannot be deleted. Changing the workspace's own rules
needs a workspace owner.
Your account is never used for someone else's turn, and theirs never for yours.
An agent can hand part of the work to a rule with
yard crew run. The child gets only
the task it was given, and when it finishes it wakes its parent without ending
the parent's turn. By default at most 5 children run at once per turn, one
level deep; both are settings on the Agents tab. When the next turn runs on
another agent or account, it is told what it has not seen, and the chat shows
that as a line.
Who builds, who reviews, ask before
The top of the Agents tab has four rows, and changes save as you make them:
- Who builds: the model used when nobody picks an agent in the composer.
- Who reviews: an agent of the workspace, or Nobody (the default). When a turn of a project's agent ends having changed the project's diff, the reviewer reads that diff before you do, in the project's container, on the account of the person whose turn it was. It leaves its comments on the lines they are about, as ordinary diff comments written in its name, which you answer, send to the project's agent or resolve on the Changes tab, and the project's chat gets one line saying how many it left. While it reads, Changes says "Codex is reviewing…"; if it cannot (no account of yours for that agent, an answer it could not read), it says why. One review runs at a time per project, a turn that leaves the diff as it was is not reviewed again, and nothing ever waits on a review.
- Accounts: the accounts agents run on here.
- Ask before: what agents stop and ask about on every project, in the same words as a goal's Always asks. A new workspace starts with Deleting data, New secrets and Merging to main; + Add types your own, and × removes one. Every project's agent is told the list with every turn (a goal's own list adds to it). With Merging to main on it, a finished project waits for a person's Merge: a goal on Autopilot does not queue it for merge, and the API refuses a merge nobody pressed. Editors change these two rows; the limits below stay the owners'.
Models and effort
Pick the agent and model from the model button in any composer: the chat's, the work composer's, or the Write spec dialog's:
| Agent | Models | Effort |
|---|---|---|
| Claude Code | Fable, Opus, Sonnet, Haiku | low, medium, high |
| Codex | Default, then the models its CLI offers your account | what the CLI offers (low to xhigh) |
| Cursor | Auto | none |
When a person has not picked one, the workspace's default applies (in the workspace settings under Agents), then the organization's (under Settings, Models, set by admins). When none of those names a model, the agent's default model (in bold) is used. The model button always names the model a message runs with.
Codex lists the models its CLI offers the account you signed in with: a ChatGPT plan offers fewer than an API key. Yard asks the CLI when you sign in, and again after a turn once a day. Default passes no model, so Codex runs the default of your plan; the reply then names the model it ran. A model your account is not offered (one picked before, or a workspace default) gives way to the default, and the chat says so.
Agents run only in containers
An agent never runs on Yard's servers or directly on the runner machine. It runs inside a container on the workspace's runner. Your sign-in is handed to the container for one turn and removed when the turn ends.
There are two kinds of agent:
- The workspace agent answers the chats beside docs and sheets. It works in the workspace's own container, in the workspace's files: it can write notes that appear on a canvas, look at uploads, and read the repositories, which are read-only reference copies there. It does not change code; code changes happen in a project.
- A project agent belongs to one project and works in that project's
container. It writes the spec, then changes code in the project's
worktrees and commits it. It never pushes or opens pull requests: people
do that from Yard after reviewing the work, or Yard does it when the
agent finishes, if the workspace's
automation is on. It can read from GitHub
(
git fetch) to bring in the base branch; it has noghaccess, pull requests are managed in Yard, which is how Resolve with the agent fixes a pull request that conflicts. See repositories and git.
Agents can take screenshots of what they build with a headless browser.
In the workspace the pictures they save land on a canvas; a project's agent
saves them to .yard/screenshots/, and the project's page shows them under
Screenshots.
Both kinds put things on a canvas in a tidy way: a repository file goes on as a linked, read-only code block rather than a copy, a note opens sized for what it holds (wide when it has pictures or tables).
How big an agent's container is
Each container gets the CPU cores, memory and /dev/shm (shared memory, which
browsers and parallel test runners use) set in the workspace settings under
Resources. The
workspace's limits apply to every container; under Projects, an owner can
give one project's container more (or less) of each, and that container
restarts to apply it. /dev/shm defaults to 1 GB, at most half the memory
limit.
Inside the container, nproc and free report the container's limits, not
the whole machine's, and YARD_CPUS and YARD_MEMORY_MB say them plainly.
The agent is told the same in its instructions, and runs heavy checks one at
a time when there is less than 8 GB.
When a project's container starts with less than 8 GB of memory, under 4 CPUs
or under 512 MB of /dev/shm, the project's chat gets one line saying so,
with a Resources link for workspace owners to that project's limits. It
is said again only after the limits change.
When a command runs out of memory
A workspace can cap how much memory each of its containers may use
(in the workspace settings under Resources, Limits). When a command an agent runs (a type
check, a test suite) pushes its container over that limit, the kernel ends
it. Yard says so by name instead of leaving a bare Killed:
- In the command's own output, which the agent reads:
yard: `bun run check` was killed: the box hit its 4 GB memory limit (peak 4.0 GB). Run the tests in smaller batches or one file at a time. - In the project's chat, as a line with the command, the limit and the peak, and, for workspace owners, a Raise memory limit link to the limit (in a project's chat, to that project's own limits). Several kills within a few seconds are one line. The agent reads this line in its next turn too.
- When the agent program itself is ended for memory, its turn's error says so, with the limit and the peak. When it was stopped any other way, the error does not mention memory.
Agents are told not to just run the same command again, but to run tests in smaller batches or one file at a time, or to borrow memory for one command:
yard run --memory -- bun run check
yard run --memory 8g -- bun test
That works when an owner has set Check runs may use up to under the
memory limit. A workspace without a memory limit has nothing to borrow:
yard run --memory then says the command can use what the machine has,
and runs it. The container's limit is raised in place while the command
runs (it does not restart) and goes back afterwards, after an hour at the
latest. It is raised only when the runner has the extra memory free, plus
1 GB, and is not under heavy load; otherwise the command runs at the normal
limit and says why. The command always runs, and yard run ends with its
exit code.
When a command is killed for another reason
Exit code 137 means a process was ended with SIGKILL, and memory is only one of the reasons. Whatever ended a command, its own output says which, so the agent does not guess:
- The container's task limit. A container may run 8,192 processes and
threads at once. Past that nothing new can start, and test runners or
Chromium's tabs crash:
yard: `bun run check` failed: the box reached its limit of 8192 processes and threads, so some could not start. Run fewer test files at once. - Yard stopped it, and why: an earlier session left it running when a
new turn started, someone stopped it from the chat, the agent's turn was
stopped, or the container was stopped (idle, paused under load, replaced
for new settings):
yard: `bun test ./e2e` was stopped by Yard: an earlier session left it running, and a new turn started in this box. - A signal from inside the container, when none of the above explains an
exit 137: a tool's own time-out or a
kill -9. It was not memory and not Yard.
When a container itself ends without Yard stopping it (the machine ran out of memory, Docker restarted), the chat of the turn running there says The box stopped unexpectedly, with what Docker reports.
Checks started with yard run are not tied to the shell that started them:
when the agent's shell is ended (at the end of its turn, or by its own
time-out), the check goes on, Yard shows how it ends, and a new turn does
not stop it. Ctrl-C, a stop from the chat or --timeout ends it. A run
killed with SIGKILL reads Out of memory only when the container's memory
was the cause; otherwise it reads Killed, with the cause.
The Resources tab of the workspace settings shows each container's peak memory and how many processes were ended for memory in the last 24 hours, with the most recent command.
Dependencies an agent installed in a worktree are kept: when a project's
worktree is removed (the project is done or closed) its node_modules are
put aside and come back when it is checked out again with the same
lockfile, and a new project on the same repository and lockfile starts with
a linked copy of another project's. Package caches (bun, npm, pnpm) live in
the workspace's home and move with the workspace. Agents are told to
install only when the lockfile changed or a module is missing.
What an agent is told
With every message, the agent gets:
- where it is, which repositories are there and which of them it may change;
- the blocks you selected (with the text of notes) or, with nothing selected, none (in a project: a list of everything linked to it; see chat for the account setting that changes this);
- the lines you highlighted in a repository (repositories and git);
- files you attached;
- the recent conversation and your message.
A project agent also gets the instructions and spec.md. Highlights set
priority, but the agent can still read the whole repository.
Every agent is told to write a data structure (database tables, an API payload, a config file) in a spec, plan or doc as a Schema block rather than as nested lists, and other tabular facts as a Markdown table.
It is also told to judge test and typecheck failures with yard tests compare, and to fix only the new ones: what already fails on the base branch
is not its to chase (test baselines).
Every agent is told how to change files: its own edit tool for one or two
edits, yard edit for more in one
call, its write tool for a new file, and never a throwaway script.
yard edit checks every edit before it writes anything, so an edit that no
longer matches fails loudly instead of being skipped. Claude Code is also
stopped when it runs Python that rewrites files, and told to use yard edit
or its edit tool instead; Codex and Cursor get the rule only.
When you ask a project's agent for a follow-up round, for example after its
pull request was merged, it creates the follow-up project itself with
yard project create instead of
offering a card, and says what it created. The new project starts from the
default branch as it is on GitHub, keeps the project's repositories and
linked blocks, and its spec.md already holds the agent's instructions, so you
see them on its spec page as soon as it is created. It is not started: its
agent turns that draft into a full spec once you open it and send a message
or edit spec.md.
To hand work to another open project, or coordinate work that overlaps, a
project's agent writes to that project's agent itself with
yard project message, or leaves a
note on its canvas with yard project note. A message starts the other
agent on it (after its current turn when it is busy) and the other agent can
answer the same way; an answer from a turn a message started never wakes
the sender back, so two agents cannot keep each other running. Inside one chat,
a message to another agent shows as a card with its attachments, its reply does
wake the sender, and the exchange stops at the workspace's turn limit (4 by
default), or does not start when Agents can message each other is off. A project
that is not started yet only gets the message, and is not started by it:
the message also lands on its canvas as a note, so its agent has it in full
when someone starts the project.
Because each message carries its own context, a conversation can continue with another person's account, another agent, or on another runner.
Which repositories the agent reads
In the workspace, the agent works only with the repositories that are part of your request:
- the repository blocks you selected;
- the repositories of code excerpts in the context;
- a repository your message names;
- for an investigation, the repository blocks on its tab, and for Draft monitors, the repositories you chose in the dialog.
"The repo" in your message means those. The other repositories of the workspace are named to the agent but it is told not to open, search or quote them, and to put nothing from them on a canvas or in a doc. When your request needs one, the agent asks first with a question card that names it. Once you agree, it can use that repository for the rest of the chat. With your context setting set to the whole workspace, the repository blocks of every canvas count.
This is an instruction to the agent, not a lock: the workspace's copies are all in the same box. A project's agent only sees the repositories of its project.
Work left running in the background
An agent can start a long command and end its turn without waiting for it: "the full test run is going in the background, I'll pick up when it finishes". Yard notices every process the turn left running in the project's container, and the project reads Working in background instead of Done. The sidebar, the toolbar, the project's block and the bar under the spec name the command and how long it has run; the chat lists each one under the agent's last reply, with a Stop button for each.
- A process that listens on a port (a dev server, an API) is a server: it
gets an Open button (the page opens in a new tab at a private address,
signed in to Yard, see Open a server running in a project), and
nobody waits for it. A project with only servers left running reads
Done, the chat lists them under Serving in the box, and the agent is
not woken when one ends or is stopped. A server stays up across later
sessions until someone stops it. A database started with
yard pg startoryard redis startbelongs to the box and is not listed at all. When a port starts listening while you have the chat open, the chat asks under the list whether to publish it at an address of its own; a published one says where ("Public at …"). - When the last of the others ends (or is stopped), the agent carries on in the same chat by itself: Yard tells it which commands finished and when, and which were stopped and by whom. It reads their output where it sent it (Yard cannot know an exit code). Only that turn decides whether the project is done.
- A message you send meanwhile runs as usual; the agent is told what still runs, and the work stays followed.
- Stop on the project, or in its chat once the turn has ended, also stops its background work, and nothing is picked up after. A project whose progress file says the work is finished is then done, not a draft.
- Pull requests are not merged, and the project is not offered for closing, while background work runs (servers aside): merge once it has ended, or stop it first.
- A restart of Yard does not end the work: the project still reads Working in background, and a turn the restart cut off carries on once the runner is connected.
- Before a new session starts in a project, processes an earlier session left behind are stopped, so they do not fight the new one for ports, the database or memory. The chat says which ones were stopped. Work a chat is still waiting on, in this or another chat of the project, is kept.
- A turn cut off by its runner carries on by itself, up to three times. The
chat line says why when Yard knows: the runner stopped answering for
35 s, the runner restarted (after it was killed for memory when
it was), or the box ran out of memory; otherwise the runner lost its
connection, or the box stopped unexpectedly when its container ended
without Yard stopping it. The agent that carries on is told which of its
commands were stopped; checks started with
yard runkeep running, and a new session never stops them either. - Claude Code keeps its own background shells (
run_in_background) open in the same turn; the project shows the same background state, and the agent continues in its own session when they finish (for up to 6 hours, after which they are followed like any other process).
A process that clears its own environment, or a service started outside the container (an app the runner's hosting runs), is not followed.
When an account runs out of usage
When an agent account hits its AI usage limit, its turns wait instead of failing, in every chat that uses it; other people's accounts carry on. They start again by themselves when the provider said the limit resets, or with Resume in the chat. See chat.
Plan limits
What each agent tells Yard about its account's limits, shown in the chat's usage indicator:
| Agent | Tokens | Cost | Plan limits |
|---|---|---|---|
| Claude Code, signed in with a subscription | yes | yes | 5-hour and weekly windows (and per-model weekly ones when Claude has them), with their reset times |
| Claude Code with an API key | yes | yes | none |
| Codex | yes | no | none (not reported by codex exec) |
| Cursor | no | no | none |
Limits are what the agent CLI reports during a turn, kept with the time they were seen. When a window is used up, its reset time is when waiting turns start again, if the error itself did not say.
When an agent needs you
An agent can end its reply with questions, shown as a form in the chat, or with an offer to connect something that is missing. See chat.
The workspace agent asks what is open about a doc in the doc itself instead, in the section the question is about; questions about anything else still come as the form in the chat. See questions from the agent. This needs runner 0.31.0 or later; with an older runner the agent asks in the chat.