Working with agents

Parallel sessions

Each session keeps its own conversation, mode, model, and session tools. Sessions in the same project work in the same checkout, so a change made in one session is visible to the others right away. You do not need a separate worktree for every agent.

Sessions run on the server. Closing the app or switching devices does not stop them. The sidebar shows which sessions are working, which have results you have not seen yet, and which are waiting for your answer. If you want a run on its own branch instead, a workflow can give each run its own worktree; see Workflows.

File locks

When a session edits or writes a file, Koyd locks that file until the session's turn ends. If another session tries to change it, the change is refused and the agent is told which session holds the file, so it can work on something else and check again later. A lock on a folder also covers everything inside it.

The lock icon next to the message box shows a count. Hover over it to see which files other sessions hold, which files this session's swarm is using, and which files the current turn holds.

• Agents are told about other sessions' locks. At the start of each turn they get a list of files that other sessions in the project hold, and shell command results carry a notice when other sessions held locks while the command ran. The notice is advice only: it does not block the command or change its result.
• Delegated agents wait instead of giving up. When an agent's edit reaches a locked file, Koyd pauses that change until the lock is released, then asks the agent to re-read the file and try again. Shell commands never wait, and Koyd refuses a wait that could never end, such as two agents waiting on each other.
• Turn on Settings → General → Auto-chain locked sessions to continue a stopped session automatically once the session holding its files finishes. Its waiting message shows Auto-chained. Delegated agents and swarm sessions are never chained this way, and three chains in a row without a clean turn stop the loop.

Good to know · File locks coordinate Koyd's own agent tools on this server. They are not a sandbox. Shell commands are checked on a best-effort basis, so scripts, variables, and unknown MCP tools can still change files without being blocked. External editors, other programs, and other Koyd servers do not see these locks. When you need strict isolation, use a separate worktree or checkout.

Queue and chain prompts

You can send a message while a session is still working. It waits in a queue above the message box and runs after the current prompt. Edit or remove a queued prompt before it starts.

To start work only after other sessions finish, use the chain button in the composer (Chain this message after another running or pending session) and pick the sessions to wait for. The message shows as Pending until they finish, then sends. If one of them fails, the chained message does not send, so you can decide what to do next. Cancel pending puts the message back in your message box.

Queues and chains run on the server. Closing the app does not pause them.

Choose a mode

Pick a mode in the composer before you send. Code has full access to tools for making changes. Ask answers questions and explains code without making changes. Swarm turns the session into an orchestrator that plans and supervises a team; see Swarm.

Create your own modes in Lab → Modes with a name, description, prompt, and category. Readonly modes can inspect and research but cannot edit files or run commands, and they leave out MCP server tools. Yolo modes can run tools and modify files.

Set up Koyd from chat

Choose Koyd Manager in the mode menu and describe what you want. It can create or change skills, MCP servers, modes, prompts, swarm presets, agents, custom providers, and workflows. Workflows are checked with the same rules as the workflow editor before they are saved, in Koyd or in a project.

Koyd Manager does not edit your code or run commands. The only project files it writes are workflows you ask it to save in a project. When it saves something, its reply says what was saved and where to inspect it.

Session tools

Type /tools in the message box to turn tools on or off for the current session: Agents, Ask user, Browser use, and Computer use. The change applies to this session only. Use ↑ and ↓ to move and Enter to switch a tool.

The Tools pill beside Skills and MCPs shows how many tools are on and lists them. It is read-only; change tools with /tools. To choose which tools new main sessions start with, open Lab → Tools. Changing a default does not change existing sessions.

Session tools belong to main sessions. Agent and swarm task sessions keep the restrictions they started with. Shared browser covers Browser use and Computer use.

Answer agent questions

Turn on Ask user in /tools to let the agent pause and ask you when it needs a decision. It is off by default and also works in read-only modes. Agents and swarm tasks started by the session do not get it.

The question appears above the message box. Pick one or more options, or type an answer when the question allows it, then choose Submit answer. Nothing is chosen for you. Stop turn cancels the waiting turn without an answer.

A session with an unanswered question shows a pending indicator in the sidebar, and pending questions are listed first. Opening the session does not count as an answer. The question waits on the server, so you can reload, reconnect, or answer from another device; the first answer counts. Questions and answers stay in the conversation. Knowledge base imports ask for Approve or Decline the same way, even when Ask user is off; see Knowledge bases.

Delegate to agents

Turn on Agents in /tools to let a session hand parts of its task to agents saved in Lab → Agents. Without a mention, the session can pick any saved agent. Type # and an agent's name to limit that message to the agents you mention.

Each delegated run is a regular Koyd session. It appears in the sidebar under its parent with an Agent badge, and you can open it to read its conversation, tool activity, and changes. Agent sessions stay available after the turn ends, even if you delete the parent.

Agents work only during the parent turn that started them, and the parent waits for each agent's final report. If that turn is interrupted, for example by a restart, the parent can list the agent sessions it started earlier, read their saved output, and resume an interrupted, failed, or cancelled agent with its saved context.

• A read-only parent keeps all of its agents read-only.
• Agents cannot start agents of their own.
• Agents of one parent that declare overlapping files to write start one after another. Agents with separate files run in parallel.
• While an agent runs, it may change files its parent already changed in that turn. Other sessions still see those files as locked.

Good to know · Every agent uses provider tokens too. Delegate independent pieces of work with clear file ownership; more agents help only when the work can really run in parallel.

Agent queues and limits

When a session asks for more agents than can run, the extra ones wait. The chat shows a badge such as 2 agents working · 1 queued. Open it to see why each queued agent is waiting, for example for a free slot or for an agent that owns overlapping files. You can cancel one agent there without stopping its parent or the others. Cancelling does not undo files already changed.

Set the limits in Lab → Agents → Agent runtime limits. They apply to the whole server, across projects and devices. Changes affect agents that start later, including waiting ones, and never stop running agents. The defaults are:

• Concurrent agents per parent: 4.
• Concurrent agents across this server: 16.
• Accepted launches per parent turn: 24. Leave it empty for no cap.
• Concurrent agents per provider: no limit until you set one.
• Failed startup attempts per turn: 8.

There is no runtime cutoff. An agent runs until it finishes, fails, or is cancelled, or until its parent stops. The server accepts up to 256 queued or starting requests at once and refuses more with a visible message.

Save reusable agents

Create agents in Lab → Agents. Each one has a Name, a Description, a Category (Read only or Yolo), System Instructions that define its role, an optional Model that overrides the session's model, and the Skills, MCP Servers, and Attachments it should use. Read-only session modes keep an agent read-only even when it is set to Yolo.

The same saved agents are used for delegation, as workers and reviewers in swarm presets, in workflow steps, and by Koyd App assistants. Export, duplicate, edit, or delete an agent from its row. Lab resources belong to the server you are connected to, so another server can have a different setup. To share reviewed agents and other resources with colleagues, see Teams (beta).

Skills and MCP servers

Skills give an agent reusable instructions. MCP servers give it tools from other services. Manage both in the Lab under Skills and MCP Servers, mark the ones you want in every new session as Always On, and switch them for one session with /skills and /mcp. Import Skills brings in skills you already use with other agent tools, such as Claude Code or Codex.

Recommend in Lab → Skills suggests skills for work you repeat. Choose Analyze sessions to read the recent sessions of one project, review each suggestion, and choose Create skill to draft one. Nothing is saved until you choose Create in the skill editor. Analysis sends a summary of those sessions to the model you select.

For project memory and code maps, see Code maps, memory, and context. For document collections that sessions can search, see Knowledge bases.

Good to know · Check what an MCP server can do and which credentials you give it before you turn it on.

Attach files

Add files to a message with the paperclip, or drag them onto the message box. Each file can be up to 100 MB, with up to 32 files per message. PNG, JPEG, GIF, and WebP images go to the model as images. Other files are stored on the server; the agent gets their paths and a short preview, then reads the rest with its tools.

Koyd extracts the text of text files and of PDFs up to 10 MB. Scanned PDFs are not read with OCR, and other binary formats are kept as they are. A session can hold up to 128 attached files and 512 MB. Attachments survive queued prompts, retries, and restarts. Moving a session to Trash keeps them; deleting it permanently removes them.

Token usage and completion sounds

Each reply shows the tokens its turn used: input, output, cache reads and writes, and a total, including any agents the turn delegated to. Next to the message box, Koyd shows how much of the context window is in use and a running total for the session, also including delegated agents.

While Koyd is open, it plays a sound once when a session finishes. Turn it off or pick another Sound effect in Settings → General under Sound.