Open, stop, and review provider-supported background tasks.

  Background task conversations

Some coding agents start smaller tasks inside a conversation—for example, an agent investigating one part of a codebase or a command running in the background. Clay Studio can display these provider native tasks when the provider exposes them. They differ from  Split Workers  /docs/drivers workers , which are separate linked work sessions managed by a Driver.

   Inspect a task

When background task tabs appear in the session:

1. Open the task you want to inspect.
2. Read its status and available conversation or output.
3. Use   Refresh   if the display needs updating.
4. Return to the parent conversation to steer the overall request.

For supported Claude background agents, the viewer shows recorded conversation pages and tool activity. A shell or monitoring task shows a limited portion of its output instead. Other providers may show that inspection is unavailable.

Recent assistant messages can appear as brief previews beside task tabs. Hover or keyboard focus recalls the latest preview; open the viewer for the surrounding work.

   Understand the task list's lifetime

Completed tasks can remain listed while the same provider execution context is available, including after refreshing the page. Reinitializing the provider clears the list. It is a temporary view, not a permanent archive of every task.

If a tab disappears, use the parent conversation and changed files to inspect the result. Its disappearance does not undo work. After repeated refresh failures, automatic refreshing stops; use Refresh after resolving the connection problem.

   Stop or continue

Use the task's   Stop   control when it is offered. Check whether you want to stop one task or the parent session. Stopping does not undo saved files or commands that already ran.

Give follow up instructions in the parent conversation unless the task UI offers input. Not every native task accepts messages or can resume after an interruption.

Clay can observe task counts, but cannot currently open, read, or stop an individual native task through its workspace control tools. Use the task viewer for those actions. For recovery after a connection loss, see  Stop and recovery  /docs/stop recovery .


Background task conversations

Understand projects and Mates, and how Clay helps coordinate your work.

  Projects and Mates in Clay Studio

  Clay Studio   brings together the work you organize in   projects   and the collaborators you keep as   Mates  . A project gives work a place; a Mate gives you a continuing working relationship. You can use both for the same task.

   Projects: organize the work

A project connects to a directory on the machine running Clay Studio. Its sessions let you investigate, edit, test, and review work in that directory. Logs, Issues, Notes, and repository instruction files keep useful information with the work.

Choose a project session when the request belongs to a particular repository: “Fix the export error in this application, run the relevant checks, and show me the diff.” The session gives you a clear place to follow the changes and return to the task later. Projects can support collaboration with other people through their access and session sharing settings.

Start with  Your first project  /docs/first project , or read  Projects and working directories  /docs/projects working directories  when choosing where changes should happen.

   Mates: keep a collaborator

A Mate has a persistent identity, working instructions, Knowledge, and private conversations. Shape one around a role you want to keep: a research partner, a technical reviewer, or someone who helps you plan.

For example, create a reviewer Mate and explain how you want proposals evaluated. Give it your review checklist in Knowledge. You can return with a different proposal next week without defining the role again.

Mates can also help with project work. Within the available tools and your permissions, they can find project sessions, read conversation history you can access, and propose a reviewed assignment or follow up in a project. A Mate is not confined to discussing only material you paste into its chat.

Use  Create and shape a Mate  /docs/mate creation identity  to set up that relationship. Conversations with Mates remain private to their owner, even when they concern a shared project.

   Clay: your lead Mate

  Clay   is the built in lead Mate within Clay Studio. Clay is its name;   Clay Studio   is the product's name.

Click Clay's icon in the rail to open its conversation; click again to enter its full workspace.

Talk to Clay when you want help finding your way through ongoing work or coordinating across it. For example: “Find the export investigation I worked on recently and help me decide what to do next.” Clay can search workspace conversation history and activity, draw on Knowledge held by your other Mates, and use supported workspace controls.

Other Mates keep their own roles and expertise. They share useful capabilities with Clay, including project context and reviewed project assignments; Clay adds coordination and product controls described below.

   Clay and other Mates compared

Both can help you understand project work and propose an assignment. Review the proposed project and task before it starts. Clay also has controls for specific workspace actions; available tools still depend on your provider, connections, and access.

| Capability | Clay, the lead Mate | Other Mates |
|     |     |     |
| Persistent identity and private conversations | Yes; its built in role is managed by Clay Studio | Yes; shape their roles through interviews and instructions |
| Use available tools, such as shared Browser and connected services | Yes, where supported and authorized | Yes, where supported and authorized |
| Find project conversations you can access | Yes | Yes, project by project |
| Ask a project agent to start or continue work | Proposes an assignment for your review | Can propose the same kind of assignment |
| Find recent work across projects | Can search workspace history and activity | Searches through project specific tools |
| Work with Mate Knowledge | Can read across your Mates to coordinate their expertise | Maintains its own Knowledge |
| Use built in workspace controls | Supported actions include session management, saved View arrangements, and selected project records | Does not receive Clay's product control tool set |
| Use  Me  /docs/mate knowledge memory me  knowledge about you and report observations | Yes | Yes |
| Decide which reported observations to save in Me | Reviews and maintains saved knowledge | Reports observations for Clay to review |

Clay's workspace controls cover specific operations rather than every button in Clay Studio. Server Settings and User Settings remain controls you operate yourself.

   Move from advice to project work

Your reviewer Mate might identify a problem that needs a code change. Ask it to propose a bounded task in the relevant project, then review the assignment before it starts. Continue implementation in the resulting project session and bring the result back to the reviewer when useful. The  Driver  /docs/drivers workers , the project agent responsible for the task, manages execution and any Split Workers.

  Me   holds owner private knowledge about you across projects and Mates. Mates can consult relevant entries and report preferences or corrections; Clay reviews those observations and curates the saved knowledge. It is separate from a project's reference documents or a Mate's own Knowledge. See  Knowledge, Memory, and Me  /docs/mate knowledge memory me .


Projects and Mates in Clay Studio

Join an existing Clay Studio server or install one and choose your first task.

  Start with Clay Studio

Clay Studio gives you a browser workspace for working with AI agents. Use a   project   for work in a folder or repository, or create a   Mate   for a continuing role such as research or review.   Clay   is your built in lead Mate.  Projects and Mates  /docs/clay vs mates  explains how they work together.

   Choose a manual version

Use   Stable   for the released product or   Beta   for changes being prepared for release. The documentation sidebar shows the current channel and, when supplied, its version. On mobile, open the navigation menu to find the switcher. Choosing another channel opens its overview; an unavailable destination is disabled.   Preview   identifies a build without a stable or beta channel designation.

   Join an existing server

If someone has given you a Clay Studio address, open it in your browser and complete the sign in or invitation flow. You do not need to install coding agents on the device you use to view it. Ask the server operator for project access and provider setup if those are unavailable.

The same address can work from your phone when the server is reachable. An address beginning with localhost refers to the device opening it, so use the server's actual hostname when connecting remotely.

   Set up your own server

The server machine holds your project files and runs the coding agents. It can be the computer you are using now.

1. Install a supported   Node.js LTS release    Clay Studio requires version 20 or newer  using the  official Node.js download instructions  https://nodejs.org/en/download .
2. Open a terminal on that machine and run  node   version  to check the installation.
3. Install and sign in to a coding agent CLI under the account that will run Clay Studio.  Provider sign in  /docs/provider auth  includes a complete Claude Code example and links for alternatives.
4. Start Clay Studio:

   bash
npx clay server
   

Follow the startup prompts, then open the printed URL. Complete the administrator setup or sign in shown. HTTPS is enabled by default; follow the printed certificate instructions. The default port is   2633  . To choose another port, use  npx clay server  p 8080 .

A second invocation can connect to an already running server. Use the  CLI reference  /docs/cli flags  when you need unattended startup or an independent installation.

   Try a first task

Follow  Your first project  /docs/first project  to open a folder and create a session. Send a small request such as “Explain how to run this project's checks. Do not change files yet.” You should see the response in the conversation, with tool activity and any permission requests alongside it.

If you want a continuing collaborator instead, follow  Create and shape a Mate  /docs/mate creation identity .

To visit the Clay Studio website, select the wordmark at the top left of the app. It opens  clay.studio  https://clay.studio  in a new tab, leaving your workspace open.

   Understand where information goes

Your request travels through the Clay Studio server and the selected coding agent application to its provider; it does not require a Clay Studio hosted relay. Connected services, email, websites, and agent network commands can also receive data when used for your task.

Private conversations limit who can see them in Clay Studio. They do not prevent the agent from using a connected service you authorize. For remote access and server maintenance, see  Server administration  /docs/server settings .


Getting started

Install your first AI provider, sign in, and check that a session can use it.

  Provider sign in

Clay Studio sign in gives you access to the workspace. A coding agent login lets that agent contact its provider. Install and authenticate the CLI on the   server machine  , under the OS account that runs it. Signing into a provider website on your phone does not configure the server.

   Set up a first provider: Claude Code

This example uses Claude Code on macOS, Linux, or WSL. Check the  official setup guide  https://code.claude.com/docs/en/setup  for supported systems and Windows installation options.

1. Open a terminal on the server machine.
2. Run the official installer:

   bash
curl  fsSL https://claude.ai/install.sh | bash
   

3. Open a new terminal and run  claude   version . A version number confirms the command is available. If it is not found, follow the setup guide's PATH instructions.
4. Run  claude auth login  and complete the provider's sign in flow. Use an account or billing arrangement supported by  Claude Code authentication  https://code.claude.com/docs/en/authentication .
5. Start or return to Clay Studio. In a project, choose   New session → Claude Code → Create  .
6. Choose an offered model and send a short request, such as “Reply with a greeting without changing files.”

A completed response confirms that this session can use the provider. Installing the CLI alone does not establish account access or available usage.

   Other providers

Use the provider's CLI installation guide, rather than installing only its desktop app or editor extension. Alternatives include  Codex  https://learn.chatgpt.com/docs/codex/cli ,  OpenCode  https://opencode.ai/docs/ ,  Kimi Code  https://www.kimi.com/code/docs/en/kimi code cli/guides/getting started.html ,  GitHub Copilot CLI  https://docs.github.com/en/copilot/how tos/copilot cli/set up copilot cli/install copilot cli ,  Qwen Code  https://qwenlm.github.io/qwen code docs/en/users/quickstart/ ,  Junie CLI  https://junie.jetbrains.com/docs/junie cli.html , and  Kiro CLI  https://kiro.dev/docs/cli/ .

The following commands are the sign in entry points configured by this Clay Studio version. Some open an interactive application where you finish login. Provider releases can change their setup flow; use their current instructions if your installed command differs.

| Coding agent | Sign in entry point |
|     |     |
| Claude Code |  claude auth login  |
| Codex |  codex login   device auth  |
| Muse Code |  muse  |
| OpenCode |  opencode auth login  |
| Kimi Code |  kimi login  |
| Grok Build |  grok login   device auth  |
| GitHub Copilot CLI |  copilot login  |
| Qwen Code |  qwen  |
| Junie CLI |  junie  |
| Kiro CLI |  kiro cli login  |
| Antigravity CLI |  agy  |

For example, newer Kimi Code instructions start with  kimi  and then  /login  inside it. Check the installed CLI's help before assuming its commands match an older integration. Account plans, model access, and organization policies remain provider specific.

   If the provider is unavailable

    Missing from the picker:   check that its executable is installed where the server's OS account can find it. A command available in your personal shell may not be available to a separately launched server.
    Listed, but sign in fails:   repeat the provider login under the same OS account. In an OS isolated installation, another user's credentials do not apply.
    Model list loads, but a request fails:   read the error for model access, billing, or usage limits. Reinstalling is unlikely to fix an account limit.

Keep credentials in the provider's login flow or settings, not in a conversation.  MCP connections  /docs/mcp servers  have their own credentials; importing one does not sign the coding agent in.


Provider sign-in

Create a project, choose a working directory, and run a first session.

  Your first project

A project connects Clay Studio to a directory on the server machine. Sessions work against that directory; project records preserve context between conversations. Start with an  authenticated provider  /docs/provider auth  and a repository you can safely inspect.

   Open or create

1. Select   +   in the rail    Add Mate or project   , then choose   Start a project  .
2. Choose   Open an existing folder  ,   Create a new project  , or   Clone a repository  .
3. For an existing folder, browse the server to the project root and choose   Open  . Use   Enter path  , enter the server path, and select   Go   if you already know its location.
4. For a new project, enter   Project name   and select   Create project  .
5. For a clone, enter   GitHub repository URL  , choose the destination offered by the dialog, and select   Clone repository  .

Wait for creation or cloning to finish. The folder chooser describes the machine running Clay Studio. It cannot open an unrelated folder on the device displaying the browser. Private repository cloning also needs Git credentials in the server environment.

Confirm the project name and path when it opens. You can alternatively register a directory with  npx clay server   add .  while the daemon runs.

 ! Start a project dialog offering an existing folder, a new project, or cloning a repository.  /images/manual/start project.webp   /images/manual/start project.webp 

 Choose the route that matches where your project files are. This is the dialog after Start a project. 

   Start the first task

1. Choose   New session   under the intended session folder, including   Unfiled  .
2. Choose an installed provider in the inline creation row.
3. Select   Create  .
4. Check the model and permission controls.
5. Send: “Inspect this repository. Explain its entry point and the command used to run its tests.”

A response should appear in the transcript. Read permission cards before approving tool actions. If files cannot be found, check the working directory.

Next, request one bounded change: “Correct the typo in the welcome heading. Show the diff and run the relevant existing check. Do not commit.”

 ! New session creation row with the provider menu open and the Create button visible.  /images/manual/new session.webp   /images/manual/new session.webp 

 Choose an installed provider, then Create. Grey entries show providers unavailable in this demo installation; your list may differ. 

   Review and return

Open  Files  /docs/files  to inspect the result and the  Git view  /docs/file history git  to review changed paths. Read the check result alongside the changed files.

Use   Rename   in the session menu to give the task a recognizable name. Keep lasting project guidance in repository instruction files such as  AGENTS.md ;  Projects and working directories  /docs/projects working directories  explains supported files. Another session does not automatically contain this conversation.

Before parallel edits, learn about  working directories  /docs/projects working directories  and  worktrees  /docs/worktree sharing : several sessions can otherwise change the same files.


Your first project

Use the sidebar, search, favorites, folders, and keyboard focus.

  Navigate Clay Studio

The   rail   holds project and Mate icons. A project's   sidebar   lists its conversations and saved Views. The main area shows the selected conversation; the composer sends to that conversation. The   tool palette   opens panels such as Files or Terminal beside your work.

 ! Demo project workspace with the project and Mate rail, tool palette, session sidebar, conversation and composer.  /images/manual/workspace.webp   /images/manual/workspace.webp 

 The rail is at the far left; the tool palette and session list sit beside it. The selected conversation fills the main area, with its composer below. This and the following examples use disposable data in Clay Studio 5.3.0. Select an image to view it at full size. 

   Choose where to work

Select a project in the rail, expand a session folder or   Unfiled  , then select a conversation. A saved   View   opens several panes together. To add a project or Mate, select the rail's   +   button, labeled   Add Mate or project  .

Click a Mate icon to open its floating conversation; click again to enter its full workspace.  Projects and Mates  /docs/clay vs mates  explains when to use each.

On smaller screens, open the navigation menu to choose a destination, then return to the conversation.

   Organize project conversations

Use a session's context menu for   Rename  ,   Move to folder  , and   Add to Favorites  . Right click its row to open the menu. A favorite stays in its original folder and working directory.

Choose   New folder   in the folder toolbar, enter a name, and confirm. To rename or delete a custom folder, right click its header, long press on touch, or focus it and press   Shift+F10  . When deleting, read the choice of what happens to its sessions.

Folders organize conversations; they do not move repository files. For example, a “Release” folder can hold planning and verification sessions that still use the same project directory.

   Sort and find work

  View options   controls sorting within folders:   Last activity  ,   Date created  ,   Title  , or   Manual order  . Optional date headings subdivide those folders. These display options are separate from a saved   View  , which is a pane arrangement.

Press   Command+K   on macOS or   Ctrl+K   elsewhere to open the command palette. Type a destination or command, choose a result with arrow keys, and press Enter. Escape closes it. Use  session search  /docs/session history search  for conversation content.

If a conversation seems missing, clear search, expand folders, and check the selected project and account before creating another one.

   Arrange the workspace

Use  Split Views  /docs/split views  to keep several conversations visible. Tools open over the workspace;   Dock   reserves room beside the conversations.  Workbench layout  /docs/workbench layout  explains Dock, Float, Expand, and Close.

Appearance settings live in   Settings → Personal → Appearance  . Choose your theme, conversation layout, and typography. The layout previews show the difference between separate centered bubbles and full width conversations with avatars. Terminal has its own font settings and retains a dark content area.


Navigate Clay Studio

Create, move, resize, rename, favorite, and separate panes.

  Split Views

A saved View arranges sessions and tools in one workspace. It changes what you see, not which agent owns a task or which files a session can edit.

   Add a session beside another

1. Open the session to use as the insertion target.
2. Open its split direction control.
3. Choose   Right  ,   Left  ,   Top  , or   Bottom  .
4. Clay Studio immediately reserves an empty pane in that direction.
5. Search for a recent session or choose a provider to create one.
6. Select the session and wait for placement.

The picker is centered in the reserved space. Escape dismisses it and restores the previous arrangement. It does not create a placeholder session.

The picker excludes ineligible sessions such as existing members and linked Workers. A session in another multi session View can show   Move from  ; selecting it moves that presentation rather than making a second independent conversation.

If creation succeeds but placement fails or the context changes, the real session can remain in   Unfiled  . Inspect the list before retrying creation.

 ! Split view menu offering right, left, top and bottom directions.  /images/manual/split direction.webp   /images/manual/split direction.webp 

 First choose a direction from the session's split control. 

 ! A reserved empty pane on the right with a centered session picker.  /images/manual/split picker.webp   /images/manual/split picker.webp 

 Then choose a session in the reserved pane. This demo has no other eligible recent session, so the picker offers new session providers. Escape cancels the reservation. 

   Find and name the View

The combined arrangement appears as a View in the session sidebar. Select it to return to its panes. Open the View row's menu for   Rename  ,   Add to Favorites  ,   Move to folder  , or   Separate  . Separate returns the sessions to individual presentation; their conversations remain distinct throughout.

   Rearrange a View

Drag a pane header to an offered drop region and release only when the target is correct. Resize using dividers. Existing multi pane layouts also offer   Arrange   presets and   Choose sessions  .

Views support up to eight visible sessions, including linked Workers. Tool panes use the same workspace arrangement without becoming agent sessions.

When combining sessions, organization follows the drop target's actual folder, including Unfiled. If both already share a folder, that folder remains the natural destination.

   Work with tools

Open Terminal, Browser, Files, or another workbench, then choose   Dock   to place it beside sessions. New tools start as overlays, even if a previous arrangement was docked. Docked panes remain in the background while another tool overlays them.

Use Expand to focus a pane and restore the arrangement afterward. Closing a presentation is different from deleting its underlying session or stopping its execution.

Saved Views remember the pane arrangement, but do not save every tool's unsaved content. If a reopened Sketch viewer is empty, reopen the diagram from its conversation or saved source before using Save or Download.

See  Workbench layout  /docs/workbench layout ,  Navigation  /docs/navigation , and  Working directories  /docs/projects working directories . Saved project Views are not available for private Mate conversations.


Split Views

Arrange tool panes as overlays or dock them beside your conversations.

  Workbenches and panes

A workbench opens a tool beside your conversation. An   overlay   floats over the conversation without reducing its layout area; a   docked   pane reserves space alongside it. Use an overlay for a quick lookup and docking when you want to keep a reference visible while working.

   Open and arrange a tool

1. Select the project or Mate workspace.
2. Open a tool from its tool palette.
3. Choose   Dock   to keep it beside the conversation.
4. Drag the pane header to an offered drop region, or resize using a divider.
5. Choose   Float   to return it to an overlay where offered.

Newly opened tools start as overlays. Existing docked panes can remain behind a new overlay. Opening a tool does not create another agent conversation.

The tools you see depend on the workspace and access. Ordinary projects have tools for files, commands, project records, and scheduled work.   Knowledge   and   Debates   are Mate workspace tools;   Me   is in Clay's workspace.   Linear   depends on its connection, and   Sketch   displays a wireframe supplied through a conversation.

 ! File diff overlay covering the right side of the conversation.  /images/manual/file overlay.webp   /images/manual/file overlay.webp 

 Overlay: the file pane sits over the conversation. The transcript continues beneath it. 

 ! The same file diff docked beside a narrower conversation.  /images/manual/file docked.webp   /images/manual/file docked.webp 

 Docked: the file pane reserves its own space, and the conversation reflows beside it. These are two observed layouts of the same demo file. 

   Expand or close

  Expand   gives a pane more workspace; restore it to return to the arrangement. Expanding Knowledge is separate from entering its document editor.

  Close   hides or removes the pane presentation. To stop an agent, use its Stop control. Ending Browser, closing a terminal tab, and deleting a session are separate actions with their own effects.

Terminal content keeps its dark palette while surrounding headers follow the workspace theme.

   Keep a file beside the task

Open a file and choose   Pin this file   to keep that path visible while selecting other files.   Follow file selection   returns the pane to following your selection. For example, pin a specification while reviewing implementation files in another pane. Pinning does not prevent edits to the file.

   Return to a saved arrangement

Project  Views  /docs/split views  retain supported pane arrangements. They do not save all unsaved tool content or keep external processes running. A reopened Sketch viewer, for example, needs its diagram loaded before you can save or download it.

If a pane is empty, check its selected file, tab, or connection. For tool specific steps, continue to  Files  /docs/files ,  Terminal  /docs/terminal ,  Browser  /docs/browser , or  Sketch  /docs/sketch .


Workbenches and panes

Understand project roots, working folders, and project-level tools.

  Projects and working directories

A Clay Studio project registers a directory on the server. File tools, shell commands, and agent edits affect that actual directory. A project title is a label, not a filesystem boundary.

   Select the correct root

Open   Start a project → Open an existing folder   to register a directory. For a Git repository, choose its root unless a subdirectory is intentional. Use   Clone a repository   to obtain a remote repository first, or   Create a new project   for an empty directory.

Before requesting edits:

1. Select the project.
2. Check its path in project information/settings.
3. Open Files and confirm recognizable content.
4. In Terminal, use  pwd  to confirm the shell's working directory.
5. Name the intended directory and file scope in the request.

For example: “Work in the current project directory and change only the documentation folder.” This is useful when several repositories have similar names.

   Instructions and environment

Keep project guidance in a repository instruction file such as  AGENTS.md  or  CLAUDE.md . Clay Studio also recognizes  .cursorrules ,  .github/copilot instructions.md ,  COPILOT.md , and  QWEN.md ; providers differ in which files they read directly.

For example, an  AGENTS.md  might say: “Run the existing unit tests before handing back a change. Keep generated files unchanged. Explain any check you could not run.” Add the real test command used by your project so another session can follow it.

Open the project header menu and choose   Project Settings → Environment   for process configuration. Keep secrets out of messages and committed files. A process already running may need restarting to read a changed environment; saving settings does not retroactively change its environment.

   Parallel tasks

Several sessions in one directory can edit the same files. A  split View  /docs/split views  changes presentation, not isolation. For independent branches or conflicting changes, use  Git worktrees  /docs/worktree sharing .

Check each worktree's path before running commands. Sharing project records does not make two worktree directories identical.

   Registration and access problems

The CLI supports:

   bash
npx clay server   list
npx clay server   add .
npx clay server   remove /path/to/project
   

Removal unregisters the project; it is distinct from deleting its repository directory. Read the specific UI confirmation for any removal action.

If opening fails, check that the directory still exists, the daemon's OS account can access it, and your Clay Studio account has permission. Reopening a browser tab cannot restore files deleted outside Clay Studio.

See  Project sharing  /docs/project sharing  for workspace access and  Troubleshooting  /docs/troubleshooting  for discovery and connection failures.


Projects and working directories

Create, resume, rename, stop, and continue sessions.

  Create, resume, and rename sessions

A session keeps a project's conversation available across visits. Return to it to continue a task with its history, or start another session for different work.

   Create

1. Select the project.
2. Choose   New session   under the intended folder.
3. Choose an installed provider.
4. Select   Create  .
5. Check model and permission mode before sending a request.

Cancel the inline creation row to abandon it before completion. If the connection drops during creation, inspect the session list before pressing Create again. A real session can exist even when your browser misses its acknowledgement.

Folders organize sessions; they do not create a new repository or branch. Sessions using the same directory can edit the same files.

   Resume

Select an existing session from its folder or a  search result  /docs/session history search . Wait for replay to finish before continuing. Scroll upward to load earlier messages when necessary.

A resumed conversation may restart its provider process or need authentication. Readable history does not establish readiness to execute. After an interruption, request a concrete next step: “Inspect current Git status and determine whether the previous validation finished before continuing.”

The latest visible response, pending queue, and actual files together provide the useful recovery context. Do not infer success from the absence of a spinner.

   Rename and organize

Open the session menu and choose   Rename  , or use the title's rename affordance. Enter saves; Escape cancels; leaving the field saves a changed nonempty title. A connection or permission change can cancel the edit.

Choose a descriptive task title, such as “Fix export validation,” rather than a provider name. Move the session into a folder for related work. A saved  View  /docs/split views  displays several sessions without merging their transcripts.

   Finish deliberately

Use   Stop   for execution. The pane's Close action changes presentation and is not a substitute for stopping. Check pending messages before resuming.

To remove a session, right click its sidebar row and choose   Delete  , then read the confirmation. Preserve lasting project outcomes in  Project Logs  /docs/project logs  and reference material in repository documents before deleting history. For an alternative investigation path, see  Fork and rewind  /docs/session fork rewind . For access, see  Session privacy  /docs/session privacy sharing .


Session lifecycle

Find sessions, search a conversation, and inspect history.

  Find conversation history

Use history to recover decisions and search to locate a specific exchange. Session titles, transcript text, and repository file contents are different search targets.

   Search within a session

1. Open the session you want.
2. Press   Command+F   on macOS or   Ctrl+F   elsewhere to open session search.
3. Type a distinctive phrase in   Search in this session…  .
4. Use   Next   or Enter to move forward and   Previous   or Shift+Enter to move backward.
5. Press Escape or Close to leave search.

Clay Studio highlights matches and moves to the selected occurrence. Use a phrase such as a function name, error fragment, or decision rather than a common word. Reading the surrounding exchange matters: a proposed command and its later failed result can both match.

Scroll toward the beginning to load older conversation history. History loads in portions; the first visible screen is not necessarily the entire conversation. Wait for loading to finish when navigating an older result.

   Find another session

Use the session list's search to narrow the current project's work. The workspace command palette, opened with   Command/Ctrl+K  , provides navigation across its available destinations. Open the actual result and check its project and title before continuing.

Search covers conversations you can access. Clearing a search and expanding folders can reveal work hidden only by navigation filters.

 ! Command palette listing two recent conversations with their project names.  /images/manual/conversation palette.webp   /images/manual/conversation palette.webp 

 The command palette offers recent conversations before you type. Check the project beneath each title; use the search field to narrow the available destinations. These are disposable demo sessions. 

   Resume from evidence

Before continuing an old task, read its latest response, pending messages, and any tool result relevant to the next action. Files may have changed outside that conversation.

A useful request is: “Find the last agreed approach in this conversation, inspect the current implementation, and tell me what remains before editing.” This avoids relying on an earlier plan as though it were current reality.

Use  Project Logs  /docs/project logs  for durable project outcomes and repository documents for maintained project references. In a Mate workspace, use  Knowledge  /docs/knowledge documents  for reference material. Searchable transcript history is useful evidence, but it is not a substitute for those records.

If history loads but sending fails, check provider readiness and your connection. If the session is absent, verify the selected account, project access, folders, and visibility. See  Session lifecycle  /docs/session lifecycle  and  Troubleshooting  /docs/troubleshooting .


History and search

Fork a session or rewind project work with a clear recovery path.

  Fork and rewind

Forking creates another conversation path. Rewinding returns an existing session to a selected point using the capabilities available for its runtime. Neither operation should be treated as a general backup system.

   Fork an investigation

Use   Fork   on the relevant message when you want to explore another approach while keeping the original conversation.

1. Find the turn containing the context you want.
2. Choose its   Fork   action.
3. Wait for the new session to appear.
4. Check the copied history boundary and current provider.
5. State the alternative task explicitly.

Example: “Explore an implementation without changing the public API. Inspect the current files before proposing edits.”

A fork is another conversation, not automatically a separate Git branch or worktree. Both sessions can still edit the same directory. Use  worktrees  /docs/worktree sharing  when the alternatives need isolated files.

History boundaries depend on the runtime. Review what the new transcript actually contains, particularly around incomplete turns or provider native task activity.

   Rewind a session

Stop active processing first. Where rewind is offered:

1. Select   Rewind   on a turn, or enter rewind mode and select a message.
2. Wait for the preview.
3. Inspect the listed paths and diffs.
4. Choose the offered conversation/file mode.
5. Confirm only after checking the selected session and checkpoint.
6. Inspect both the resulting transcript and working tree.

The preview distinguishes conversation only behavior from file restoration. Conversation only rewind leaves files unchanged. File restoration applies to the available recorded checkpoint and listed changes; it does not promise to undo every shell command, untracked file, external service action, or edit by another process.

A preview can report   No file changes to restore   or   No diff available  . Those messages are limits of the recorded evidence, not proof that the entire directory equals an earlier state.

   Recover cautiously

If rewind is unavailable, the provider or turn may lack a usable checkpoint. Preserve current changes and use Git or an explicit corrective edit instead.

If an operation errors or disconnects, inspect its observed result before retrying. Never assume rewinding a message recalls a sent email or reverts a remote deployment. See  File history and Git  /docs/file history git ,  Stop and recovery  /docs/stop recovery , and  Provider capabilities  /docs/provider capabilities .


Fork and rewind

Set visibility and understand project and worktree access.

  Session privacy and sharing

Project access lets someone enter a project; session visibility determines which conversations they can read there. A public project can contain private sessions. Public access is within the authenticated Clay Studio workspace, not an anonymous internet page.

   Share a project conversation

In an account mode installation, the owner of an ordinary project session can change its visibility:

1. Select the project and find the session in the sidebar.
2. Right click its row to open the session menu.
3. Choose   Make Shared   to share it with project members, or   Make Private   to restrict it again.
4. Check the updated session state. Shared sessions have a   Shared session   indicator.
5. Ask the intended recipient to open it using their own account.

These controls do not apply to Mate conversations. If the menu is absent, check that you own the session and are using an ordinary project in account mode.

The recipient also needs  project access  /docs/project sharing . A copied session link does not grant that access. Project ownership transfer does not transfer ownership of private conversations.

   Choose defaults for new sessions

Open the project's header menu, then   Project Settings → Access → New session visibility  . The owner can choose   Private   or   Shared with project members  . The setting governs new ordinary sessions; it does not change existing conversations. Worktrees inherit the default from their parent project.

   Bring private work into a shared task

Create a shared project session and summarize only the context you intend to share. Clay and other Mate conversations remain private to their owner, as does  Me  /docs/mate knowledge memory me .

Personal connected tools can become unavailable when a session is shared or includes another person's input, even if its visibility later becomes private. See  MCP connections  /docs/mcp servers .

   If someone cannot open the conversation

Check their signed in account, project access, and the session's visibility in that order. Administrator status alone does not allow reading another person's private conversation. Revoking access can disconnect an existing viewer; reconnecting checks the current permissions.


Session privacy and sharing

Change model, effort, permissions, and continue with another agent.

  Session settings and handoffs

Session controls configure the selected conversation's provider behavior. Project defaults influence creation; changing a default is different from changing an existing session.

   Change a session setting

1. Open the intended session and verify its title.
2. Open the model/session controls.
3. Select an offered model.
4. Set effort if supported.
5. Select the intended permission mode.
6. Wait for each change to finish and check any status or error before sending.

Clay Studio requests a live model catalog.   Retry   in an empty or failed picker reloads that catalog. A failed selection can leave the previous model active. Permission changes also have a confirmed effective state; an unavailable Auto mode can use a fallback.

Do not assume a running provider turn adopts every setting midway through execution. Check the current status and apply configuration deliberately before the next task.

   Continue elsewhere

Wait until the session is idle and has conversation history, then choose   Continue in another agent   beside the composer. If the control is hidden in a split or Mate presentation, open the ordinary session workspace.

In   Continue in a new agent  , select   Agent  ,   Model  , and supported   Reasoning effort  , then choose   Continue  . The result is an independent session with a focused copy of the conversation context.

Prepare a handoff covering:

  The requested outcome and constraints.
  The working directory, branch, or worktree.
  Files changed and checks that actually ran.
  Remaining questions and known failures.
  The next concrete action.

Example: “Continue the export fix in the current worktree. Validation now rejects empty names. The unit check passed; browser verification remains. Inspect the diff and exercise export in the running app. Do not commit.”

Wait for the destination to become available, then verify its provider and context. Shared project instructions support continuity, but hidden reasoning, native task state, and provider specific tools do not transfer universally.

   Keep defaults distinct

The creation UI can offer a project default provider. Saving that default affects later creation choices; it does not migrate all current conversations. Personal settings and server settings have their own scopes and are not session settings.

If the destination cannot start, check authentication and model availability. If it starts with incomplete context, supply the missing facts rather than asking it to infer the previous provider's private state.

See  Models  /docs/models and providers ,  Permissions  /docs/permissions ,  Session lifecycle  /docs/session lifecycle , and  Usage and context  /docs/usage and context .


Session settings and handoffs

Send, stop, edit, and refine a message in the main composer.

  Write and send messages

The composer sends to the currently selected conversation. Before submitting, verify the project, session title, and any recipient mention. A useful request describes an outcome, a scope, and how completion should be checked.

   Send a request

1. Select the intended session.
2. Type your request.
3. Add any required files or context.
4. Review attachment and mention chips.
5. Use   Send  , or press Enter on a desktop keyboard.
6. Watch the transcript, queue, and execution status.

On touch devices, Enter inserts a newline; use the Send button.   Shift+Enter   adds a newline on desktop.   Ctrl+J   also inserts a newline in the composer.

For example: “Fix the empty state message in the search panel. Change only the existing component and styles. Run the relevant check and show the diff. Do not commit.”

Give corrections as concrete instructions. If work is already running, another message can enter the  queue  /docs/drafts and queue ; submission does not necessarily interrupt the current tool action.

   Read the controls

While processing, the composer can display Send when you have content and Stop when it is empty. Use   Stop   deliberately when you need execution interrupted. Review suggested text before sending it.

A question or approval card may need an answer before work can continue. Respond to that card rather than typing unrelated text and assuming it answers the pending request.

   Revise before delivery

An unsent draft is different from a queued message. Edit your draft directly. For a queued message, use its own edit controls and save the change. Once delivery starts, cancellation or editing may no longer have the same effect.

Attachments, pasted blocks, mentions, and schedule delay are part of the outgoing request. Remove outdated context when changing tasks; deleting visible prose alone may leave a chip attached.

Use  Attachments and context  /docs/attachments context ,  Mentions, voice, and slash commands  /docs/mentions voice slash , and  Delayed messages  /docs/delayed messages  for those controls. For an interrupted or uncertain delivery, see  Stop and recovery  /docs/stop recovery .


Composer basics

Preserve drafts and manage queued messages without losing intent.

  Drafts and the message queue

A draft is unsent composer content. A queued message is accepted work waiting for delivery. An active message has already begun delivery or processing. Treat these as separate states when deciding whether to edit or retry.

   Keep a draft

When switching between project sessions in the current page, each composer can retain its text and attachments. Return to the same conversation to continue the draft. This is not a promise of recovery after reload or synchronization to another device; copy important unsent text before leaving the page.

For a Mate conversation, finish an upload or voice recording before switching between its floating panel and full workspace.

   Inspect pending work

Sending while an agent is busy can add a pending message rather than starting another simultaneous turn. Review the queue near the composer.

1. Find the relevant pending item.
2. Check its text, images, timing, and author.
3. Use   Edit   to change a message you own.
4. Select   Save  , or   Cancel   to discard the edit.
5. Check the updated queue after saving.

The queued image editor supports previewing, replacing, removing, and adding images. Wait for image reads to finish before saving.

   Reorder or remove

Use a pending item's drag handle to reorder it. The handle also supports arrow key reordering. Ordering changes which pending request is offered first; it cannot rewrite a turn already executing.

Use   Cancel queued message   to remove unwanted work. Controls depend on ownership and current item state. If delivery already started, check the transcript to see whether the request ran.

If the queue changed while you were editing, reopen its latest state and apply your change there.

   Resume after Stop

A paused queue shows   Resume queue  . Read all pending items before choosing it, particularly after an interruption or reload. Stop is deliberate; queued work should not be assumed to resume automatically.

A future scheduled item can offer   Send now  . This releases it early; it does not guarantee an immediate completed response.

If a send is uncertain, inspect both queue and transcript before sending duplicate text. See  Delayed messages  /docs/delayed messages ,  Worker queues  /docs/worker messages queues , and  Stop and recovery  /docs/stop recovery .


Drafts and the message queue

Attach files, images, pasted content, and contextual sources.

  Attachments and context

Use attachments when the agent needs an exact artifact. Use a repository path when it should inspect a file already present in the working directory. A screenshot, pasted excerpt, and live source file provide different evidence.

   Attach a file or image

1. Select the intended conversation.
2. Open the composer attachment action. Floating conversations with Clay or another Mate group   File   and   Image   under   +  .
3. Choose the artifact.
4. Wait for reading or upload to finish.
5. Inspect the resulting chip or thumbnail.
6. Add the question and send.

You can also paste supported images or content into the composer. Preview images when precision matters and remove the wrong attachment before submission.

For example: “Compare this screenshot with the current search panel and fix the spacing.” Name the relevant project files so the agent can compare the artifact with implementation.

   Pasted text

Long pasted content can appear as a separate pasted content chip. Open it to inspect the actual text; the dialog distinguishes   Pasted content   from   Edit pasted content  . Use its edit/save controls when changing the block.

Do not assume that deleting the surrounding message removes a separate paste chip. Check all outgoing context before sending. For a short log excerpt, include the command and error around the excerpt so it is interpretable.

   Context chips and access

Check the chips to see which attachments, context, and recipients will accompany the message. A path in another private project still requires access to that project.

Repository content can change after it was pasted. If the task requires current truth, ask the agent to inspect the file in the working directory. If the task requires an immutable input, say that the attachment is the version to evaluate.

If an upload fails or a provider cannot read the format, use a supported format or divide the material into relevant parts. Ask the agent to identify any portion it could not read.

   Fix a mistaken attachment

Before delivery, remove it from the composer or edit the pending queue item. After delivery, send a correction and identify which input should be disregarded. Removing a visible chip later does not recall information already sent to a provider.

See  Composer basics  /docs/composer basics ,  Drafts and queue  /docs/drafts and queue , and  Usage and context  /docs/usage and context .


Attachments and context

Address Mates and users, dictate, and use available shortcuts.

  Mentions, voice, and slash commands

Use a mention to ask someone else for a second opinion, voice input to dictate a draft, or a slash command to choose an action offered by the current session.

   Mention a Mate or teammate

1. Type   @   in the composer.
2. Choose an available Mate or teammate.
3. Check the recipient chip and the “Ask @…” placeholder.
4. Write and send the message.

The mention menu explains that the coding agent stays out of this exchange until your next message. A side conversation is therefore different from immediately asking the main coding agent to act. Its visible exchange can become context on the next agent message.

For example, mention a review Mate and ask, “What could confuse someone using this form?” The Mate receives recent conversation context. After its reply, remove the recipient chip and tell the coding agent which suggestions to apply. The side exchange belongs to this conversation; use the Mate's own workspace for a separate conversation.

Use the chip's remove action to return to the main conversation. Backspace in an otherwise empty composer also removes a mention chip. Check the recipient whenever switching between a side conversation and ordinary work.

   Dictate a request

Open   Voice input   to choose   Live   or   After recording  .

  Live places text as you speak.
  After recording transcribes after you stop.

Choose an available transcription model and language. Browser transcription can be unavailable in the current browser. External transcription providers need a connected API key; the connection form explains that audio is sent to that provider and billed to your account.

Allow microphone access when the browser asks. Speak, stop, then review the text before sending. Transcription can mishear paths, identifiers, and negation. Correct those in the draft.

If recording cannot start, check HTTPS, browser microphone permissions, input device, and the selected transcription model. Finish or discard recording before transferring a conversation between presentations.

   Use slash commands

Type   /   to see the commands supplied for the current session. Use Up/Down to choose an entry and Tab or Enter to select it. Escape closes the menu. The offered commands can change with provider, skills, and runtime state.

Read the selected command and any required argument before sending. A command offered by one runtime is not a guarantee of support in another. Skills can also contribute specialized behavior; installing a skill and invoking it are distinct actions.

For files and paste chips, see  Attachments  /docs/attachments context . For provider differences, see  Capabilities  /docs/provider capabilities . For microphone or transcription failures, see  Troubleshooting  /docs/troubleshooting .


Mentions, voice, and slash commands

Read tool results, plans, task progress, and approval requests.

  Responses, plans, and task progress

A response combines the agent's explanation with its work: tool activity, plans, questions, and progress. Start with the summary, then open the details relevant to your task.

   Review a response

1. Read the outcome stated by the agent.
2. Expand relevant tool activity for the action or command.
3. Check actual output, failures, and exit results.
4. Inspect changed files or the external destination where appropriate.
5. Compare the result with your requested acceptance criteria.

For example, “I will run the tests” is a plan. A completed command with a successful exit is test evidence. A passing narrow check may still leave browser behavior unverified.

Tool cards can be collapsed to keep the transcript readable. Expand a command card to see its output or understand a failure.

 ! Expanded Bash activity showing npm test and the sample application's test output.  /images/manual/tool output.webp   /images/manual/tool output.webp 

 Opening the command card reveals what ran and its output. Here the sample tests check creating a note and rejecting an empty title. 

   Plans and todos

Providers can expose plans or todo updates in the conversation. These help explain sequencing and progress. Availability and rendering depend on the runtime.

Read an unchecked item as remaining work. A checked item reflects the agent's reported task state; inspect the supporting result for important actions. Ask for a revised plan if the scope changes substantially.

Use  Scheduled Tasks  /docs/scheduled tasks  to run project work at a particular time, or  Issues  /docs/issues  to track work beyond this conversation.

   Questions and reviews

A structured question asks you for missing information. Answer in the card, including a free text clarification where needed. A permission/review card asks about a specific action and target. Read it before approving.

If work appears idle, look for an unanswered question, pending permission, rate limit notice, or paused queue. Sending another ordinary message may only add pending work.

   Preserve useful results

Keep project reference material in repository documents, durable task outcomes in  Project Logs  /docs/project logs , and reminders in  Notes  /docs/notes . A Mate can keep its reference documents in  Knowledge  /docs/knowledge documents .

For incomplete or uncertain execution, ask the agent to state what actually happened and what remains. See  Stop and recovery  /docs/stop recovery  and  Usage and context  /docs/usage and context .


Responses, plans, and task progress

Schedule a one-off message from a conversation composer.

  Delayed composer messages

Use the composer's schedule control for a one off message to the current conversation after a delay. This is different from recurring Mate messages and project Scheduled Tasks.

   Schedule a message

1. Select the exact conversation.
2. Write the follow up and add any supported attachments.
3. Choose   Schedule message   beside the composer.
4. Enter a delay from   1 to 1440 minutes  .
5. Press Enter to confirm the delay.
6. Check the displayed delay label.
7. Send the message.

For example, enter 30 to queue “Check whether the local build completed and report its result” for thirty minutes later.

Selecting a delay prepares timing for the outgoing message; it does not submit the draft by itself. Clicking an active delay control clears it. Escape cancels the inline delay entry.

The delay is relative to submission, not a recurring wall clock schedule. Use  Mate schedules  /docs/mate schedules  or  Scheduled Tasks  /docs/scheduled tasks  for recurrence.

   Inspect pending delivery

The queued item shows its scheduled state. Review its target, text, and timing. A future pending item can offer   Send now   to release it early.

Use   Edit   and   Save   to change supported pending content, or   Cancel queued message   to remove it. Ownership and current state determine which controls are available. Once delivery begins, editing or cancelling may no longer prevent execution.

A busy session waits until it can process the due message. A due time is not a guarantee of a completed provider response at that time.

   Keep the server available

Scheduling runs on the Clay Studio server. Closing your browser does not itself cancel a saved message, but the server must be running and the target must remain valid and accessible.

After a restart, check the pending queue and conversation before resending. The provider may already have received a message even if its response did not reach your browser.

   Common problems

If delivery is paused, read the queue and use its resume control when ready. If the target session was deleted or access changed, choose an accessible conversation and review the task before scheduling it again.

See  Drafts and queue  /docs/drafts and queue ,  Automation overlap  /docs/automation overlap , and  Stop and recovery  /docs/stop recovery .


Delayed composer messages

Choose a model and account for provider capability differences.

  Choose models and providers

A provider runtime is the coding agent application Clay Studio launches, such as Claude Code or Codex. The model is the AI you select inside that application. Installing a provider does not make every model available, and choosing a model does not change provider accounts.

   Choose a model

1. Select   New session   in the intended folder.
2. Choose an installed provider and select   Create  .
3. Open the session's model control.
4. Wait for the model catalog.
5. Select an offered model and wait for confirmation.
6. Choose reasoning effort if that model exposes it.

The provider picker reflects discovery in the server environment. If a runtime is installed but cannot authenticate, follow  Provider authentication  /docs/provider auth .

The model picker distinguishes   Loading models…  ,   Couldn’t load models  , and   No models available  . Use   Retry   to request the catalog again. If selection fails, read the error and check which model remains selected before submitting a large task.

   Reasoning effort

Reasoning effort controls how much effort a supported model spends working through a request. Models may offer low, medium, high, or additional levels. Use the actual options for the selected model rather than copying another provider's setting. Higher effort can affect latency and usage; it does not guarantee correctness.

A runtime without an effort control can still perform work. Clay Studio does not invent an equivalent option.  Scheduled Tasks  /docs/scheduled tasks  require explicit model choices for both members of their execution pair.

   Continue with another provider

Changing a model and handing off to another provider are different operations. A handoff needs the goal, current changes, verification, unresolved questions, and next action. Hidden reasoning and every provider native feature do not automatically transfer.

Example: “Review the current three file diff for error handling. The relevant check passed. Do not edit or commit.”

   Resolve failures

An empty catalog can indicate startup or authentication problems. A catalog that loads followed by a failed request can indicate model entitlement, exhausted usage, or a runtime error. Read the actual failure before retrying. Repeated selection cannot fix expired authentication.

Permission mode is independent of model and effort. Check  Permissions  /docs/permissions ,  Usage and context  /docs/usage and context , and  Provider capabilities  /docs/provider capabilities  before a long task.


Models and providers

Choose Ask, Auto, or YOLO and understand when approval is still needed.

  Permissions and approvals

Session permissions determine how the coding agent runtime handles tools. Clay Studio account and project permissions determine which workspace resources you can access. A permissive agent mode does not grant another person's private resources.

   Session modes

| Label | Behavior |
|     |     |
|   Ask   | Ask before actions needing permission; previously allowed actions may run without asking again |
|   Auto   | Let the runtime assess eligible actions automatically; some actions can still need your decision |
|   YOLO   | Run tools, file changes, and commands without routine permission prompts; Clay Studio access restrictions still apply |

Start with   Ask   while learning a project. Choose a more permissive mode when the task's scope and checks are clear. Auto can be unavailable for a provider; read the displayed fallback or “using” status to see the mode in effect.

If the server was started with    dangerously skip permissions , the picker can be disabled with   YOLO permissions forced by the server setting  . Ask the server operator to change that policy if you need routine prompts.

You may also see   Plan  ,   Auto accept edits  , or   Don't ask   as workflow statuses. These describe the active workflow rather than additional choices in the Ask/Auto/YOLO picker.

1. Select the intended session.
2. Choose a permission mode in its session/composer controls.
3. Wait for the change to finish.
4. Check errors and effective mode information.
5. Send the bounded task.

A disconnected or timed out change is not confirmation. Check the previous confirmed mode before continuing.

   Review a requested action

Read the action, target, and scope in a permission card, then choose its approval or denial control. If a broader remembered allowance is offered, decide whether it fits the ongoing task.

Structured questions collect information such as a target or preference. Answering one does not approve unrelated tool effects. Use an action's review card to approve it.

Some Clay Studio actions still ask you to review a particular change regardless of session permission mode. Use the review card for that action.

 ! Permission card with npm test details and Sure, Allow for session, and No actions.  /images/manual/permission review.webp   /images/manual/permission review.webp 

 Read the command in Details before choosing. Allow for session is a broader choice than approving this one request. 

   Stop and recover

Use   Stop   to interrupt execution. It cannot undo a command or external request that already happened. Inspect the transcript, files, and destination before resuming.

If a card becomes stale after a context or account change, return to the correct context and request the action again deliberately. Do not approve an old target after replacing a Worker or switching conversations.

For unattended work, define scope and verification before choosing a more permissive mode. See  Stop and recovery  /docs/stop recovery ,  Project sharing  /docs/project sharing , and  Drivers and Workers  /docs/drivers workers .


Permissions and approvals

Stop active work, inspect partial results, and resume deliberately.

  Stop and recovery

Use   Stop   when the active task must pause. Stop interrupts intended execution; it does not undo files, shell processes, messages, or external requests that have already taken effect.

   Stop deliberately

1. Confirm the session or Worker you intend to stop.
2. Choose its Stop/interrupt control.
3. Wait for the status update.
4. Read the final activity and any pending queue.
5. Inspect the affected files or external destination.

Closing Browser, Files, or a split pane changes presentation and is not the same as stopping an agent. Provider native background tasks can have their own Stop control; check its exact target.

   Resume an interrupted task

Before resuming, establish what happened:

  Did the last command finish, fail, or remain running?
  Were files saved?
  Is an external action's outcome known?
  Are pending messages still appropriate?
  Has the provider or target changed?

Then send a bounded continuation, such as: “Inspect the working tree and the last command result. Continue only the unfinished checks. Do not repeat publication.”

A paused queue displays   Resume queue  . Read its items before resuming. Reloading should not be treated as an instruction to replay stopped work.

   Recover after disconnection or restart

Reconnect to the same server, account, project, and session. Wait for history and queue state to reload. An unseen acknowledgement can leave a completed action that your browser did not display.

For scheduled work, inspect the occurrence/run record. Queued jobs and interrupted jobs have different recovery paths. Check an uncertain external action before retrying; it may have completed even though the local connection failed.

   Resolve uncertainty

For a file edit, inspect the file and diff. For Git publication, check the actual remote commit or PR. For email, inspect the send result and destination mailbox where available. For a browser action, inspect the page, not just the accepted input.

If you cannot prove whether an action happened, keep the outcome explicit and avoid an automatic duplicate. Supply the concrete uncertainty when asking the agent to continue.

See  Drafts and queue  /docs/drafts and queue ,  Worker lifecycle  /docs/worker lifecycle ,  Automation overlap  /docs/automation overlap , and  Troubleshooting  /docs/troubleshooting .


Stop and recover work

Read usage, context limits, and provider reporting carefully.

  Usage and context

  Usage   tells you about provider consumption and account limits.   Context   is the material a model can use for its current response. For example, a long transcript may need summarizing even when your account still has plenty of usage available.

   Read the usage overview

Open the usage overview in the top bar to see entries for all supported vendors. Read each entry's status and measurement time: it may contain an account reading, a report from one of your sessions, or an unavailable/not integrated explanation.

Clay Studio has account reading integrations for Claude Code, Codex, Muse Code, Kimi Code, Grok Build, and Kiro CLI. A reading still depends on the installed version, sign in, and whether Clay Studio can associate it with your account. Some readers are limited to single user installations. Other vendors can be listed without an integrated account reading.

External dashboard links are separate: Claude Code and Codex provide links to their own usage pages. An absent dashboard link does not mean the overview has no usage information for that vendor.

1. Select the vendor you want to inspect.
2. Read the status, time, and measurement units.
3. Check reset information when supplied.
4. Use an available provider dashboard for further account detail.

A session token count covers that session's reported activity, not necessarily the whole account. Tokens are pieces of text used to measure model input and output; they are not a currency. Unavailable values are unknown, not zero, and reported figures may not match an invoice.

   Keep useful context available

Messages, tool output, pasted text, and attachments all take up context. A model has a limit on how much it can use at once. Longer conversations may be summarized to make room, so an exact earlier quote may no longer be in its immediate context even though it remains in  history  /docs/session history search .

Refer to current repository paths when the agent should read live files. For a long investigation, ask for a handoff containing the goal, decisions, changes, checks, and next step. For example: “Use the current files as truth. The earlier summary explains the decision; inspect the implementation before changing it.”

   When a limit interrupts work

Read the provider notice and check the pending queue before sending again. You can wait for the reported reset or  continue with another provider  /docs/session settings  that has access. Include unfinished work and unverified results in the handoff.

Stop does not refund usage already incurred. Parallel Workers and background tasks can consume resources in addition to the main conversation.


Usage and context

Understand the Driver/Worker relationship and bounded delegation.

  Drivers and Split Workers

A Driver owns the user request and reviews the final result. A Split Worker receives bounded execution work while the Driver maintains the main context. This arrangement is useful when implementation can be delegated without losing the task's constraints.

   Start delegated work

Ask the project conversation to delegate a specific task. Include the intended outcome, allowed files, acceptance criteria, and checks. The ordinary desktop session also offers   Add Split Worker   beside the composer to open its pair controls.

Example: “Use a Split Worker to fix the validation bug. Limit changes to the parser and its existing tests. Require the relevant checks and a report of remaining uncertainty. Do not commit.”

When Clay Studio presents a proposal:

1. Read the task summary and proposed steps.
2. Review   Why this runtime  , if supplied.
3. Choose the Worker provider, model, and reasoning level from available choices.
4. Select   Run with Split Worker  .
5. Watch for creation and execution status.

Choose   Continue here   to keep work in the current conversation instead. A proposal is not a running Worker until the actual creation/execution succeeds.

 ! Split Worker proposal showing the plan, runtime rationale, model choices and two decision buttons.  /images/manual/worker proposal.webp   /images/manual/worker proposal.webp 

 Review the scope and runtime, then choose Run with Split Worker or Continue here. The screenshot shows an awaiting choice proposal, not completed work. 

   Work with the pair

The Driver and Worker have separate conversations. Open the Worker tab or pane to inspect what it is doing. Use the Driver for task level steering and final decisions. Send a Worker follow up only when you intend to address that exact Worker.

Multiple Workers can belong to one Driver. Keep file scopes distinct or use worktrees where needed. A visual split does not provide filesystem isolation.

Worker messages and tool results are evidence of its activity. The Driver still needs to review the diff, checks, and acceptance criteria. A Worker saying “complete” is not independent Driver verification.

   Finish or change direction

Read the Worker report for changed files, checks that actually ran, failures, running processes, and next action. Ask the Driver to verify the result and integrate only the intended changes.

If the Worker needs replacement, review the replacement proposal and its runtime choices.   Replace Split Worker   and   Keep current Worker   are different decisions. Replacement should carry current task context, not assume the new Worker has invisible knowledge.

Use  Worker lifecycle  /docs/worker lifecycle  for stopping and replacement,  Worker queues  /docs/worker messages queues  for delivery, and  Background tasks  /docs/background task conversations  to distinguish provider native tasks.


Drivers and Split Workers

Send live messages, queue work, interrupt, and resume.

  Worker messages and queues

Messages to a Worker should identify the exact delegated task. The Driver conversation and Worker conversation are separate delivery targets, even when they appear side by side.

   Send steering

1. Open the linked Worker conversation.
2. Confirm its assigned task, especially if a previous Worker was replaced.
3. Read its latest status.
4. Send a concise correction or follow up.
5. Check whether the message is pending or delivered.

Example: “Keep the existing API. Add validation only at the parser boundary, and report the relevant check result.” Include a concrete correction rather than “do it differently.”

Sending to a busy Worker can queue work. It is not necessarily an interrupt of the tool currently running. If the current action must stop, use the appropriate Stop/interrupt action, then inspect before continuing.

   Manage pending messages

Use the queue controls exposed for the exact conversation. Edit or cancel pending messages you own, save edits, and check the resulting order. Once delivery starts, a message may no longer be editable or cancellable.

Do not repeat a message merely because no reply has appeared. First check the queue, transcript, permission cards, and provider state. A Worker can be waiting for input or a long command.

A stopped queue needs explicit resumption. Read pending items before   Resume queue   so an old instruction does not restart after the task changes.

   Understand message status

Queued means the message is waiting. Delivered or acknowledged means it reached the receiving system; the Worker may still be processing it. Open the conversation to read its response and task result.

Automatic message previews provide a brief view of recent assistant output. Hover or focus can recall the latest preview; open the full conversation for context and tool evidence.

   When replacing a Worker

Review or cancel instructions aimed at the previous Worker. Do not assume old pending messages should be replayed against the replacement. Describe current files, observed checks, and the next task in the handoff.

The Driver should still review results after follow up work. Ask for changed files, actual verification outcomes, unresolved issues, and running processes.

See  Drafts and queue  /docs/drafts and queue ,  Worker lifecycle  /docs/worker lifecycle , and  Drivers and Workers  /docs/drivers workers .


Worker messages and queues

Review proposals, replace or close Workers, and preserve ownership.

  Worker lifecycle

A Worker belongs to a Driver and an assigned task. Use its conversation to inspect progress, stop work, or review the result. When several Workers are visible, identify them by their task rather than their position on screen.

   Create and inspect

A reviewed Driver proposal offers   Run with Split Worker   and runtime choices. After accepting, wait for the Worker to appear and check that its assigned scope matches the proposal.

Open its conversation from the linked Worker control. Read both assistant messages and relevant tool output. A Worker can be active while the Driver is waiting, and a quiet transcript can be waiting on a tool, permission, or provider limit.

For multiple Workers, distinguish them by task and provider rather than pane position alone. Rearranging panes does not change their actual ownership.

   Interrupt and resume

Use the relevant Stop/interrupt control for the active task. Then inspect the latest transcript and files. Stop prevents intended continuation but cannot roll back commands or network requests that already took effect.

Before resuming:

1. Identify the stopped Worker and its Driver.
2. Read pending messages.
3. Determine whether its last tool action completed.
4. Supply any changed scope.
5. Send the Driver a new message asking it to resume that Worker's interrupted task, with the updated scope.

Avoid resending the original task blindly; that can duplicate completed effects.

   Replace

A replacement proposal offers   Replace Split Worker   or   Keep current Worker  . Read the proposed runtime and handoff before choosing. Replacement starts another Worker. Review any pending instructions for the old Worker and include current progress in the handoff.

Ask the new Worker to inspect the current working tree and prior observed results. Files can outlive the process that changed them.

   Remove

Worker removal is explicit. In the linked Worker controls,   Remove Worker session   first arms the action, then   Confirm Worker removal   confirms that target. An active Worker can require an additional confirmation.

A timeout can report an unknown removal outcome. Check whether the session remains before retrying. Removing a Worker and merely closing a tool or pane are different actions.

For ordinary ongoing steering, use  Worker messages and queues  /docs/worker messages queues . For reviewing delegated results, see  Drivers and Workers  /docs/drivers workers . For unfinished commands and uncertain effects, see  Stop and recovery  /docs/stop recovery .


Worker lifecycle

Choose between the chat interface, provider TUI, and Terminal.

  Provider capabilities and interfaces

Clay Studio brings different coding agents into one workspace. The provider you choose determines available models, effort controls, native tasks, and some tool behavior. Use the session's offered controls as the guide to what your installed version supports.

   Choose an interface

| Interface | When to use it |
|     |     |
|   GUI session   | Work through Clay Studio's conversation, composer, permission cards, and tool views |
|   TUI session   | Use a supported coding agent's own interactive terminal interface inside the workspace |
|   Terminal   | Run shell commands yourself, including installation and provider login |

For example, choose a GUI session to discuss a change and review tool activity beside your files. A TUI is useful if you prefer the agent's native terminal controls. The current integration offers Claude Code GUI and TUI sessions; the other listed providers offer GUI sessions. A provider having a terminal application does not automatically make its TUI available inside Clay Studio.

   Check the features you need

Create a session, open its model picker, and check the available effort and permission controls. Model access depends on your provider account.   Auto   permission mode may fall back to another mode; the session displays the effective setting.

 Background tasks  /docs/background task conversations  vary by provider. Supported Claude tasks can show conversations or output; another provider may display a task count without a readable transcript. A native task is different from a  Split Worker  /docs/drivers workers , which has its own linked work session.

The  usage overview  /docs/usage and context  lists all vendors, but integrated account readings, session reports, and external dashboard links have different availability. Read the entry's status rather than treating missing data as zero usage.

   Continue across providers

Project files, instruction files, Logs, and a written handoff help another provider continue the work. Provider specific background tasks and internal reasoning do not transfer as a complete running environment.

Use  Session settings and handoffs  /docs/session settings  to create the continuation. Tell the new agent what changed, which checks finished, and what remains. If the previous task involved an external action, check its result before asking another provider to repeat it.

Connected tools also depend on the conversation's access and the provider integration. Ordinary coding may work while a particular Clay Studio tool is unavailable.  MCP connections  /docs/mcp servers  explains connection scope;  Projects and Mates  /docs/clay vs mates  explains Clay's additional workspace controls.


Provider capabilities and interfaces

Inspect project files, preview supported formats, and review agent changes.

  Files

Files displays content from the active project or worktree. Open   File browser   in the tool palette to inspect files, review agent edits, and preview supported formats. Confirm the project and path before interpreting a result.

   Open and inspect

1. Select the intended project or worktree.
2. Open   File browser  .
3. Navigate the directory tree and select a file.
4. Choose   Preview  ,   Source  , or   History   in its pane.
5. Expand or dock the pane when you need more room.

Preview renders supported Markdown, HTML, SVG, and diagram content. Source shows underlying text with line numbers where applicable. Large text files can fall back to plain text for performance. Binary files do not become editable source.

A linked path in a response can open the corresponding file. Check its full path, especially when several worktrees contain the same filename.

 ! README file in Preview mode showing rendered headings and text.  /images/manual/files preview.webp   /images/manual/files preview.webp 

 Preview renders the sample README for reading. 

 ! The same README in Source mode with Markdown syntax and line numbers.  /images/manual/files source.webp   /images/manual/files source.webp 

 Source displays the same file as text with line numbers. These tabs change the view; the repository pane is not a general purpose editor. 

   Make an edit

The repository file pane is a viewer; Source is not a general code editor. To change a repository file, ask the project agent for a bounded edit or use your normal editor on the server's working directory.

For example: “Change only the welcome heading in this file, then show me the diff. Do not commit.” Keep the pane open to inspect the result. Markdown presentation can follow edits and display their progress.

For documents in a Mate's Knowledge workbench, use its separate   Edit fullscreen → Save   workflow. The Knowledge editor does not imply every repository file has the same control.

After any edit, read the current file and Git diff. Another session or external process can change the same path.

   Follow or pin

Use   Pin this file   in the header to retain a reference while navigating elsewhere.   Follow file selection   returns to tracking selection. Pinning does not lock the file against edits.

For example, pin a requirements document while opening implementation files in another following pane.

   Copy, export, and present

  More file actions   offers applicable operations such as   Copy source  ,   Copy formatted  ,   Download  ,   Export PDF  ,   Present slides  , heading level choices, and   Refresh  .

Source copying preserves text; formatted copying uses its rendered representation. Present slides divides Markdown at the selected H1/H2/H3 heading level. These controls depend on file type.

Self contained HTML previews are isolated. Do not assume relative local assets or application network requests work as they do in a running website; use  Browser  /docs/browser  for that.

   History and failures

History combines available recorded edits and Git information. Older previews may be unavailable even when the recorded source remains readable. If content is stale, Refresh and confirm the worktree. For denied paths, check access and scope.

See  File history and Git  /docs/file history git  and  Mate Knowledge documents  /docs/knowledge documents .


Files

Inspect diffs, history, review changes, and link repository work.

  File history and Git

Clay Studio's file History and Git views answer related questions. File History helps trace recorded changes to a path. Git describes repository state, commits, and working tree differences. Use them together to review changes before committing.

   Read file history

1. Open a file in Files.
2. Select   History  .
3. Choose a recorded entry.
4. Read its source, timestamp, and description.
5. Inspect the revision or diff available for that entry.

Git entries show commit information. Conversation entries can identify the editing session or tool. Use   Compare revisions   to select two recorded versions when comparison is available.

A historical snapshot can be unavailable. Clay Studio may offer Source to inspect recorded content without being able to reproduce the original rendered preview.   No file history   means no available entries for that path, not that it was never changed.

   Review the working tree

Open the repository/Git placard below the project tool strip and check the repository/worktree before interpreting status. Select changed paths to inspect the diff.

Useful review sequence:

1. Confirm branch and working directory.
2. Read every intended changed path.
3. Check for unrelated changes.
4. Review actual validation results.
5. Commit or publish only when you intend that operation.

Two sessions sharing a directory see the same working tree changes. A diff can include edits by several people or agents; it is not automatically attributable to the current transcript.

 ! Side by side README diff showing Welcom replaced by Welcome.  /images/manual/git diff.webp   /images/manual/git diff.webp 

 The split diff shows the removed text on the left and the replacement on the right. This sample change remains uncommitted. 

   Distinguish local and remote outcomes

Saving changes a file on disk. Committing records it in local Git history; pushing sends commits to the remote repository. Merging a pull request is a further step. Ask for the step you intend and check its result.

For example, ask: “Show the current diff and run the existing check. Do not stage or commit.” Later, explicitly request the intended commit or publication if wanted.

 GitHub links  /docs/github  connect relevant work without posting a comment or merging anything merely by linking.

   Recover

Before using rewind or a Git restore operation, preserve work you need and inspect the exact target.  Rewind  /docs/session fork rewind  is limited to supported recorded checkpoints; Git has its own tracked/untracked boundaries.

If history appears wrong, verify the path and worktree. Renames and similarly named files can otherwise make you compare unrelated content. See  Worktrees  /docs/worktree sharing  and  Stop and recovery  /docs/stop recovery .


File history and Git

Run commands on the Clay Studio server and arrange terminal panes beside your work.

  Terminal

Terminal opens a shell on the machine running Clay Studio. Use it for project commands, development servers, provider login, and direct inspection. Its current directory and OS identity determine what commands can affect.

   Open a shell

1. Select the intended project.
2. Open   Terminal   from the tool palette.
3. Check the project name in the pane header.
4. Confirm the current directory with  pwd .
5. Run a harmless inspection command such as  git status   short .

The header names the owning project and Terminal. Terminal tab names appear separately. Opening a terminal does not create a new agent conversation or a separate Git worktree.

Commands run on the server, not on your browser device. A phone's Terminal pane can therefore control the server shell.

 ! Sample project terminal showing pwd and ls commands with their actual output.  /images/manual/terminal check.webp   /images/manual/terminal check.webp 

 The header identifies the owning project. Here pwd confirms the disposable project directory, and ls lists its sample files. The returned prompt is ready for the next command. 

   Run and stop commands

Type a command and press Enter. Read the output for a result or error. A returned prompt means the foreground command ended; it does not by itself mean success. In a POSIX shell, run  echo $?  immediately afterward to inspect its exit status: zero normally indicates success. A long running development server remains a running process; closing the pane presentation is not proof that it stopped.

Use the shell's interrupt mechanism, normally   Ctrl+C  , for a foreground command when appropriate. Then verify whether it exited. Separate background processes can require their own process specific shutdown.

On touch devices, the terminal toolbar supplies   Tab  ,   Ctrl  ,   Esc  , arrow keys,   Alt  , and common shell characters. Ctrl and Alt act as modifier toggles for the next intended key interaction. Be careful when switching focus between the shell and composer.

   Layout and appearance

Terminal initially opens as an overlay. Choose Dock to reserve workspace beside sessions; Expand uses more space. Its content retains a dark palette across themes and layout changes.

Open   Settings → Personal → Appearance   for terminal typography. Font size accepts whole numbers from 9 to 32 px and applies to existing and new terminals. Saving a font preference changes presentation, not shell behavior or runtime configuration.

   Common problems

If a command is unavailable, check installation and the shell's environment. A provider CLI available in one interactive shell may be absent from the daemon's environment.

If a browser cannot open the development URL, confirm the server process is still running, its listening host/port, and whether localhost refers to the Clay Studio server or your viewing device.

Avoid entering secrets in an agent transcript; use the appropriate login or settings flow. Terminal commands can still have real filesystem and network effects.

See  Provider authentication  /docs/provider auth ,  Browser  /docs/browser , and  Server settings  /docs/server settings .


Terminal

Use tabs, cookies, incognito, viewport controls, and pause/resume.

  Browser

Clay Studio's Browser shows a live page inside the workspace so you and the agent can inspect and operate the same tab. It is separate from your ordinary browser window and from the optional Chrome extension bridge.

   Open and navigate

1. Select the intended conversation.
2. Open   Browser   from the tool palette.
3. Enter a URL in the address toolbar.
4. Wait for the page frame and live status.
5. Use the tab strip to select the tab you intend to operate.

Back, Forward, Reload, and the address field control the selected tab. Use the new tab action for another independent tab. Verify the address before typing into a page, particularly after the agent or another person navigates.

A development URL using localhost refers to the Clay Studio host in this Browser. The application must be running and listening on the specified port.

   Share control

By default, both you and the agent can act in the tab. The lock control offers   Pause Clay control   to make it exclusively yours. The agent may inspect while paused but must wait for   Resume shared control   before manipulating it again.

This is useful for signing in or completing a sensitive form yourself. Resume only when you want the agent to continue. Asking the agent to finish its browsing activity does not revoke its shared permission.

   Test the actual viewport

The Browser uses a fixed virtual monitor. Resizing its surrounding pane scales that display; it does not change the page's layout viewport.

Use   Browser viewport   in the footer to choose an actual test resolution. For a responsive check, change that control, then inspect the resulting layout. A narrow docked pane alone is not evidence of mobile behavior.

 ! Browser pane showing its tab strip, address bar, Pause Clay control and viewport footer.  /images/manual/browser controls.webp   /images/manual/browser controls.webp 

 The footer separates Pause Clay control from the viewport size. The page is scaled within the pane; the displayed 1280 × 800 is its actual viewport. 

   Personal and incognito data

Mate personal tabs can retain cookies and site storage for your account across Mates and browser restarts.   Incognito   keeps temporary isolated data. Project tabs are incognito.

Review and remove saved personal site data through Browser settings. Browser cookies do not recover provider OAuth credentials or sign the coding runtime in.

  End browser   ends the runtime; a retained last frame is not a live page. Closing or hiding the pane is different. Start a new browser when needed.

After an uncertain form submission, check the page before submitting again. See  Workbench layout  /docs/workbench layout ,  Provider authentication  /docs/provider auth , and  Troubleshooting  /docs/troubleshooting .


Browser

Create and revise a wireframe, save it to a project, or download its source.

  Sketch

Sketch turns a conversational UI idea into a wireframe you can inspect and revise. Use it for page structure, controls, and layout before implementation. It is not a running website.

   Request a wireframe

Ask in a conversation, for example:

“Show a wireframe for this project's issue detail page, with the discussion below the status and a compact sidebar.”

The agent can use current project context and display a supported clay sketch diagram in chat. For an entire screen, describe the main regions and their relative importance. Specify desktop or mobile if it matters.

Read the diagram as a layout proposal. A button drawn in it does not implement that behavior in the application.

   Revise in the viewer

1. Ask for a change, such as “Move filters above the list and show the empty state.”
2. Open or follow the   Sketch viewer  .
3. Inspect the revised diagram.
4. Continue the conversation with concrete changes.

The viewer supports zoom and normal workbench controls such as widening, expanding, docking, and closing. Editing happens through conversation; selecting a drawn control is not equivalent to changing its source.

Revision requests should identify the existing screen so the agent updates the intended sketch. Use several separate sketches when comparing substantially different flows.

   Save or download

Choose   Save to project  , enter a   Project file path   ending in  .puml , and select   Save  . Wait for the   Saved to   result and inspect the path if you will share or commit it.

  Download   downloads the sketch source. It is useful for keeping the source independently of the temporary viewer.

The viewer itself does not automatically save a file. A reopened viewer can be empty, with Save and Download disabled until a diagram is loaded. Ask the agent to reopen the sketch from the conversation or saved file.

 ! Saved notes layout.puml file rendered as a sketch with zoom out, 100 percent, zoom in and Fit controls.  /images/manual/sketch file.webp   /images/manual/sketch file.webp 

 A saved .puml file can be inspected in Files with zoom and Fit controls. This is the saved file preview; the temporary Sketch viewer has its own Save to project and Download actions. 

   Rendering problems

Sketch supports a constrained Salt based wireframe format, including common controls and nested layouts. Other UML diagram types and advanced preprocessor features are not general Sketch features.

If rendering fails, give the visible error to the agent and ask it to simplify the source. Do not assume an empty viewer means a project file was saved.

For implemented UI verification, use  Browser  /docs/browser . For reading saved source, use  Files  /docs/files . See  Workbench layout  /docs/workbench layout  for pane behavior.


Sketch

Read durable continuity records, revisions, and comments.

  Project Logs

Project Logs are the durable account of what was requested, what happened, what was verified, and what remains. They let a new Driver continue useful work without rereading the whole conversation.

   Read the ledger

1. Select the project.
2. Open   Logs   from the tool palette.
3. Use   Search logs   or   Filter by category  .
4. Open an entry.
5. Read its summary, detailed record, authorship, history, and discussion.

In worktrees, the change scope filter distinguishes   Current worktree  ,   Project  , and   All changes  . A record absent from one scope can still exist in another. Check the filter before asking for a duplicate.

Categories are the project's own vocabulary. Priority—Normal, Important, or Urgent—is separate from category.

 ! Demo Project Log entry with summary, revision attribution, task details and an empty discussion.  /images/manual/project log.webp   /images/manual/project log.webp 

 A Log keeps the request, result and verification together. This is revision 1 of a demo task; the discussion below is where a person can add a correction. 

   Ask for a useful record

The Project Driver writes and revises Log entries. People can read and comment rather than silently rewriting the ledger.

For example: “Record this task's outcome in the existing Log: what changed, the checks that passed, the browser behavior still unverified, and the next action.”

One coherent task should normally have one evolving entry. As work progresses, the Driver revises it; revision history preserves earlier states. A commit history alone often lacks the user's constraints or unfinished work.

   Correct an entry

Add a comment explaining the correction and evidence. The Driver can incorporate it, ask a clarifying question, or decline with a reason.

The discussion shows states such as   Awaiting Project Driver review  ,   Incorporated  , or   Declined  . Posting a comment does not itself change the Log. Read the resulting entry after review.

A learning entry can preserve a concept clarified during the task—for example, why a Git worktree gives parallel changes separate files. Investigation findings belong with the task's outcome.

   Choose the right surface

Use  Issues  /docs/issues  for concrete actionable work with a lifecycle. Use  Notes  /docs/notes  for reminders and attention items. Keep project reference material in repository files. In a Mate workspace, use  Knowledge  /docs/knowledge documents  for maintained documents.

A Log can link an Issue without duplicating its entire report. A completed task should not become a permanently open reminder merely because it was important.

If posting fails, reconnect and inspect whether the comment or revision already exists before retrying. Keep uncertainty in the record explicit rather than presenting a pending review as a completed correction.


Project Logs

Track concrete work through an issue lifecycle and verification.

  Project Issues

Issues track concrete actionable project work through discovery, implementation, verification, and resolution. They are Clay Studio project records; linking one to GitHub is a separate operation.

   Create a useful Issue

1. Open   Issues   from the project tool palette.
2. Use the new issue action.
3. Enter   Title  ,   Summary  ,   Type  ,   Priority  , and   Details  Markdown   .
4. Describe the observed problem, impact, reproduction, and acceptance criteria.
5. Select   Save issue  .

Types include bug, feature, and plan. Search existing Issues before creating another report of the same work.

Example: “Export fails when the name is empty,” with the input, observed error, expected validation behavior, and a check that reproduces it.

If a check fails during an unfinished task, first establish whether it is a new mistake in that work or a separate bug worth tracking. Put ongoing task progress in the existing Issue rather than opening a duplicate.

   Work and discussion

Open an Issue to inspect its status, details, revision history, linked work sessions, and   Discussion  . Add a comment to supply evidence or ask a question.

Use   Start work   where offered to create the associated Driver work session. Check the actual session link rather than starting an unrelated duplicate conversation. Record progress and verification in the Issue as the task develops.

   Resolve or close

The edit form offers Open, In progress, Resolved, and Closed. Code resolution includes   Resolution summary   and   Resolving commit SHA  . Clay Studio verifies commit evidence; a prose claim that a fix is committed is insufficient.

Use the supported close reason for declined, duplicate, or non code decisions. Closing a proposal is different from proving a code fix. If the fix has not been committed or checked yet, leave the Issue in progress and record what remains.

If verification is incomplete, retain that state and next action rather than marking the Issue resolved prematurely.

   GitHub and Notes

  Connect to GitHub   searches for matching work. Read any proposed match before selecting an ambiguous result or approving creation. If creation has an unknown result, inspect GitHub before retrying.

A short linked  Note  /docs/notes  can keep an open Issue visible on the attention board. The Issue holds evidence and progress; close the reminder when its action is done.

See  GitHub  /docs/github ,  Project Logs  /docs/project logs , and  Drivers and Workers  /docs/drivers workers .


Issues

Keep short attention items and choose the right project record.

  Notes

Notes are the project's attention board: reminders, preferences, undeveloped ideas, and explicitly requested checklists. Keep each note focused on something still worth seeing.

   Add and edit a note

1. Open   Sticky Notes   from the project tool palette.
2. Use   New note  .
3. Write a short title on the first line.
4. Add only the context needed for future action.
5. Choose an optional color and finish editing.
6. Check the board after saving.

A useful note is “Review the mobile empty state” with the relevant context. A long transcript or command log is difficult to act on and belongs elsewhere.

The editor supports common formatting such as bold, italic, strikethrough, and code. Use color to group notes in a way that helps you scan the board.

   Use a checklist

Switch to the native checklist control when you need items that can be checked independently. Keep each item stable and specific: “Check narrow search layout” is easier to verify than “Polish UI.”

Check items as they are completed. If another person or agent edits the checklist, reopen the latest note before changing its items.

Ask the assistant explicitly when you want a working checklist. It should update that checklist rather than create several competing progress boards.

   Close completed attention items

Close a note when what it asks for is done. Closing removes it from the active board while preserving a recoverable record. Use   Reopen   on a closed note if it needs attention again. This is different from replacing the text with a completion report.

The human Notes browser can offer   Delete permanently   for a closed note with a separate confirmation. Choose that only when you intend permanent deletion. Assistant note closing tools do not silently turn completion into permanent deletion.

For a confirmed open Issue, a short title and Issue link can serve as the reminder. Keep reproduction steps, acceptance criteria, progress, and verification in the Issue, then close the linked note when no action remains.

   Choose a lasting home

Use  Issues  /docs/issues  for actionable bugs or improvements,  Project Logs  /docs/project logs  for durable task results, and repository files for project reference material. In a Mate workspace,  Knowledge  /docs/knowledge documents  holds maintained reference documents.

Do not keep a note open solely because a completed task was lengthy. The active board works best when it asks for current attention.

If a save fails or a checklist changed elsewhere, reconnect and inspect the current note before retrying. Avoid creating a duplicate to work around a stale edit.


Sticky Notes and record choice

Set identity, avatar, color, model, and interview context.

  Create and shape a Mate

A Mate is a collaborator you can return to across tasks. Give it a useful role—such as reviewing proposals—and examples of how you want to work together.

   Create with Clay

1. Select   +   in the project and Mate rail. Its tooltip is   Add Mate or project  .
2. In   What would you like to add?  , choose   Create a Mate  .
3. Describe the role in the conversation with Clay. For example: “Create a reviewer who checks technical proposals for unsupported assumptions and explains tradeoffs clearly.”
4. Answer Clay's questions and review the proposed Mate before approving creation.
5. Open the new Mate and complete any identity interview it offers.

Try a small real task: “Review this proposal and ask me one useful question.” This helps you refine the role using actual responses.

 ! Add dialog with Create a Mate and Start a project choices.  /images/manual/add mate.webp   /images/manual/add mate.webp 

 The rail's + action lets you choose a continuing collaborator or a project. 

   Open Mate settings

Open the Mate's full workspace. If its conversation is floating over a project, use the control to open that Mate's workspace; clicking its rail icon again also opens it.

Select the chevron beside the Mate's name in the workspace header, labeled   Open Mate settings  . The dialog has three sections:

| Section | Use it to |
|     |     |
|   General   | Change the Mate's profile and available appearance options |
|   Model   | Choose an available model and supported reasoning effort |
|   Prompt   | Read or revise its working instructions |

Save the intended changes and wait for confirmation. The rail's context menu has profile and avatar actions, but the header chevron opens this settings dialog. Clay's built in identity is managed by Clay Studio, so it does not offer all the same edits as other Mates.

 ! Mate settings General section with General, Model and Prompt navigation and workspace color choices.  /images/manual/mate settings.webp   /images/manual/mate settings.webp 

 General holds identity and appearance controls. Model and Prompt are separate sections. Shown here with the built in demo Mate Arch; no settings were changed. 

   Refine the relationship

You can edit Prompt directly or ask the Mate to interview you again. For example: “Keep your research focus, but give shorter recommendations with sources. Ask me what should change before revising your instructions.”

Keep reference material, such as your review checklist, in the Mate's  Knowledge  /docs/knowledge documents . Instructions describe how to work; reference documents supply material to work with.

For separate conversations and the small panel/full workspace controls, continue to  Mate settings and conversations  /docs/mate settings conversations .


Create and shape a Mate

Manage Mate sessions, instructions, and conversation history.

  Mate settings and conversations

A Mate keeps its role across conversations. Each conversation has its own history and draft, so use a new one for a separate task and return to an existing one when continuing an exchange.

   Open a conversation

Click a Mate's rail icon to open its floating conversation. Its header offers   New chat   and   Conversation history  . Use history to select an earlier exchange, or New chat to start another.

Click the Mate's rail icon again, or use the panel's open workspace control, for its full workspace. Use   Back   to return to the preceding workspace. This changes where the conversation is displayed; it does not start another chat. Finish an upload or voice recording before transferring the composer.

When opening a Mate from a project, read the context indication above the conversation. It describes the project context available for your next message. A new chat retains the Mate's identity and available stored knowledge, but it is not a copy of every earlier exchange.

   Change settings

1. Open the Mate's full workspace.
2. Select the chevron beside its name in the header:   Open Mate settings  .
3. Choose   General  ,   Model  , or   Prompt  .
4. Make the change and save it.
5. Check the saved selection or instructions before starting the next task.

General controls profile and appearance. Model offers the models and effort levels available through that Mate's provider. Prompt contains its working instructions. If a model list fails to load, retry after checking  provider sign in  /docs/provider auth .

The dialog warns about unsaved changes. Copy an important draft before reloading after a conflict.

   Privacy and connected tools

Mate conversations are private to their owner, including when discussing a shared project. A teammate or administrator cannot open them through ordinary project sharing.

Personal services can supply tools in private conversations, subject to their connection and permission settings. If a tool is missing, check the saved connection and the active provider before retrying. See  MCP connections  /docs/mcp servers  for limits involving shared conversations and messages from other people.

If the Mate's behavior needs adjustment, revise its Prompt or  reshape its role through an interview  /docs/mate creation identity . Use  Knowledge, Memory, and Me  /docs/mate knowledge memory me  to decide where lasting context belongs.


Mate settings and conversations

Distinguish Mate Knowledge from owner observations and saved memory.

  Knowledge, Memory, and Me

Use   Knowledge   for material you maintain with a Mate, and   Me   for information about you that should be useful across projects and Mates.   Memory   refers to Mate specific recorded conversation material; it is separate from both.

| What you want to keep | Where it belongs |
|     |     |
| A research brief or review checklist | The Mate's Knowledge |
| A preference such as “Give short recommendations during code review” | Me, after Clay reviews the observation |
| The outcome and remaining work of a project task | The project's Logs |
| A project's coding rules or test instructions | Its repository instruction files |

   Maintain a Mate's Knowledge

Open the Mate's full workspace, then   Knowledge   in its tool palette. Create documents for reference prose or databases for repeated fields, such as a research register. The Knowledge workbench and its databases are available in Mate workspaces, not ordinary project workspaces.

For example, save a “Proposal review checklist” document and ask the Mate to use it during reviews. Save the document revision explicitly; a recovery draft is not the published version. Follow  Knowledge documents  /docs/knowledge documents  or  Knowledge databases  /docs/knowledge databases  for the complete workflow.

   Understand Mate Memory

Mate Memory can contain summaries of earlier exchanges. Supported mention and debate workflows can record summaries and use relevant material in later work. This does not mean every conversation is saved or that every earlier detail is available on the next turn.

A Memory viewer is not an established workflow in the current Mate workspace. For material you need to inspect and maintain yourself, use Knowledge. For an exact exchange, return to its conversation history.

   Review Me in Clay's workspace

1. Open   Clay's   full workspace.
2. Choose   Me   from its tool palette.
3. Use   Search what Clay knows   or the category filter.
4. Open an entry to read its evidence and revisions.
5. Comment to correct or refine it, or use Delete to remove it.

Me belongs to you across projects and Mates. A project agent or another Mate can report an observation, but Clay reviews it before saving it as knowledge.   Ask Clay to review   requests review of pending observations. New/updated badges help you find saved changes.

   Correct or forget

Give the intended scope: “This preference applies only to code reviews,” or “Forget my old location; it is no longer current.” Check the entry after review.

Deleting through Me removes the active memory once the change is saved; a deletion audit record remains. It does not erase earlier conversations or copies held by an external provider. Sharing a project does not give teammates access to Me.

Use  Project Logs  /docs/project logs  for project outcomes and  Notes  /docs/notes  for reminders that need attention now.


Knowledge, Memory, and Me

Maintain documents in a Mate's Knowledge and inspect saved revisions.

  Knowledge documents

The Knowledge workbench stores reference material in a Mate's workspace: decisions, procedures, specifications, and explanations worth finding again. Use a document for evolving prose, rather than leaving its only useful copy in a long transcript.

   Create and read

1. Open the intended Mate's full workspace and choose   Knowledge   from its tool palette.
2. Use the create action and select   New document  .
3. Give it a meaningful document path/name.
4. Write Markdown content in the editor.
5. Select   Save   and wait for confirmation.
6. Return to reading mode to inspect the rendered result.

Use   Search names and contents   to locate documents. Open tabs retain several references. The details area offers   Outline  ,   Links  , and   History  . Headings make long procedures easier to navigate.

A suitable document is “Release procedure,” with prerequisites, ordered steps, expected results, and recovery instructions. For ordinary project work, keep procedures in repository documents and task outcomes in Project Logs; the Knowledge workbench is Mate only.

 ! Saved Knowledge document with the document explorer, rendered release procedure, outline and history controls.  /images/manual/knowledge reading wide.webp   /images/manual/knowledge reading wide.webp 

 After Save and Exit editor, the document is available for reading. The explorer selects the reference; the outline jumps between its headings. This example belongs to a disposable Mate workspace. 

   Edit and organize

Open a document and choose   Edit fullscreen  . Make changes, Save, then use   Exit editor   to return to reading. Expanding the Knowledge pane itself is only a layout action.

The editor distinguishes   Unsaved changes  ,   Saving draft…  ,   Draft saved on server  , and the saved document. A saved draft is recovery state; use Save to publish the document revision.

Use   Move / rename   for a saved clean document. Update meaningful links after reorganizing material. Relative document links and heading links can appear in Links, with unresolved targets identified.

 ! Knowledge Markdown editor showing source, live preview, Draft saved on server, Save and Exit editor.  /images/manual/knowledge editor.webp   /images/manual/knowledge editor.webp 

 The editor shows Markdown beside its preview. Draft saved on server protects the draft; Save creates the document revision. Exit editor returns to reading. 

   Resolve conflicts

If another change reaches the document, Clay Studio can offer   Keep draft   and   Reload disk version  . Copy important unsaved text before discarding it. Compare the versions and reapply the intended change against the current document.

Your document may be saved even when updating search fails. If the warning says this happened, choose   Retry index sync  . Check the saved document before creating another copy.

   History and recovery

Use   Load version history   to inspect recorded revisions. Select a version to open its read only preview. Choose   Review restore fullscreen  , inspect the exact content, then   Restore this version   if it is the intended replacement. Merely selecting a historical version does not restore it.

Use   Recover deleted documents   to find recoverable content and review its history through the same explicit restore flow. Deleting a document is distinct from erasing its entire recorded history. Recovery can fail if the target changed or a path conflicts; preserve your draft and resolve the current error rather than overwriting another document.

If a document is read only, ask its owner to make the change.

For structured records, see  Knowledge databases  /docs/knowledge databases . For durable task outcomes, see  Project Logs  /docs/project logs ; for reminders, see  Notes  /docs/notes .


Knowledge documents

Organize a Mate's Knowledge into fields, records, saved views, and imports.

  Knowledge databases

A Knowledge database is a table in a Mate's workspace. Its schema defines the fields, records hold the items, and saved views help you find a useful subset. Use it when the same fields recur across many items—for example a research register with title, status, source, and review date.

   Create a database and schema

1. Open the intended Mate's full workspace and choose   Knowledge  . Databases are not available in ordinary project workspaces.
2. Open the create menu and choose   New database  .
3. Enter a database name and create it.
4. Open   Schema  .
5. Use   Add field  , choose names and types, then   Save schema  .

For a research register, keep a title field for the item name, add Status as a select field with “To review” and “Reviewed,” Source as text, and Review date as a date. Save the schema before entering records.

Supported types are   title  ,   text  ,   number  ,   boolean  ,   date  ,   select  ,   multi select  , and   reference  . Select fields have options. References can point to eligible Knowledge documents or records.

Keep a useful title field and choose types when adding a field. Existing field types are locked in the schema editor. Use   Required   to require a value and   Archived   to retire an eligible field or select option while preserving its identity and recorded data. The title field cannot be archived. Renaming a field is different from creating another field with a similar name.

 ! Knowledge database schema editor with a required title field and Status select choices.  /images/manual/database schema.webp   /images/manual/database schema.webp 

 This small schema keeps the required title field and adds Status with To review and Reviewed choices. Save schema makes the new field available when entering records. 

   Add and edit records

Select   New record  , complete the fields, and save. For example, add “Export accessibility audit,” set Status to “To review,” supply a source URL, and choose a review date. The saved row appears in the table. Select an existing row, then   Edit fullscreen   to change it. A record's history belongs to that record; a table view is a presentation of the same stored records.

Use   Archive   for a record you want removed from the active listing.   Archived records   switches the listing, and   Recover fullscreen   lets you review recovery before confirming. The same principle applies to an archived database through recoverable Knowledge.

For a reference field, choose   Text item   or   Database record   and the target database where needed. A document reference uses its stable item ID; the record input uses  databaseId:recordId . If you do not know the identifier, ask: “Find the Knowledge record for the export audit and give me its reference value.” Use that returned value rather than a filename or row number.

A reference can show a missing or unavailable target. Check the selected document or record and your access. Open the record's detail to see its saved revisions.

   Save views

Open   Views  , choose or create a   New view  , and set its name, displayed columns, filter, and sorting. Select   Save view  . Use the   Table view   selector to return to a saved view.

For example, a “Needs review” view can filter the status field and sort by review date. Choose the field, an operator such as  eq   equals ,  contains ,  empty , or a supported comparison, and a value appropriate to the field type. Choose a sort field and Ascending/Descending direction. A filtered out record is not deleted.

The compact editor handles one filter and one sort. If an existing view contains several, those controls are locked while the name and columns remain editable; the existing filter/sort order is preserved. Do not recreate a complex view merely to change its name. Clear or change the selected view before concluding that an import or save lost data.

 ! Research register with Needs review selected and one row whose status is To review.  /images/manual/database table final.webp   /images/manual/database table final.webp 

 The saved Needs review view shows the matching record. The Reviewed record still exists in the database; the filter only changes which rows appear. 

   Import through the assistant

Imports run through the assistant's Knowledge tools rather than a CSV upload control. Ask the assistant to inspect a source, map fields to the existing schema, and import the reviewed rows.

Start with a small batch: “Import these three research items into this Mate's register. Show the field mapping first, then report the saved records.” The tool accepts up to   100 rows and 256 KiB per batch  . Keep the original import input unchanged when retrying; corrections to already imported items should update their saved records.

If a save reports a stale revision, reload current state and reconcile your draft. If records were saved but the Knowledge listing did not update, use   Retry sync   and check for those records before importing again.

See  Knowledge documents  /docs/knowledge documents  and  Stop and recovery  /docs/stop recovery .


Knowledge databases

Set up a structured debate with several Mates and inspect the result.

  Debates

A debate brings several Mate perspectives to a decision. Use it when different responsibilities could reveal tradeoffs—for example, asking a reliability reviewer and a product reviewer whether a first release should support offline editing.

   Prepare the discussion

Open a Mate's full workspace and choose   Debates   from the tool palette. Select   New debate  , enter the question, and choose   Continue in chat   to plan it with Clay. You can also ask Clay or a suitable Mate to set up a debate in conversation.

 ! Debates workbench with an offline editing question drafted and Continue in chat available.  /images/manual/debate draft.webp   /images/manual/debate draft.webp 

 New debate starts with a question. Continue in chat takes it into planning; it does not by itself show an approved panel or a completed debate. This demo draft was cancelled. 

Describe the decision, useful background, and the perspectives you want. The setup can ask about format, moderator, participants, and constraints.

When the   Debate proposal   appears:

1. Read the topic and context.
2. Check the moderator and each panelist.
3. Review their roles and any model choices.
4. Approve the proposal to begin.

Give panelists distinct responsibilities. “Assess operational risks” and “Assess the user experience” usually produce a more useful discussion than asking everyone for a general opinion.

   Watch and contribute

Follow the live discussion in its conversation.   Raise hand   requests a chance to contribute; when the input is offered, write your message and choose   Send  , or   Pass  .   Stop debate   requests an end after the current speaker finishes; the status tells you when stopping is pending.

If a participant cannot start, read the error before relying on the panel's coverage of that perspective.

   Use the result

Read the disagreements and unresolved questions as well as the recommendation. A debate provides analysis; it does not implement its recommendation. If the decision depends on uncertain behavior, ask for source checks or a prototype.

Keep a reusable brief in a Mate's  Knowledge  /docs/knowledge documents . When taking the decision into project work, ask the project's Driver to record the adopted decision in  Logs  /docs/project logs  and create  Issues  /docs/issues  for actionable follow up. Share only the private Mate context you intend to disclose.

   Return to an earlier debate

Open   Debates   in a Mate workspace and select the discussion. Filters include   All  ,   Planning  ,   Live  ,   Ended  , and   Interrupted  . This lets you revisit an earlier conclusion without starting the same debate again.


Debates

Create recurring private messages through a Mate scheduling interview.

  Recurring Mate messages

A Mate schedule delivers a message to an owner private Mate conversation at a reviewed time or recurrence. It is useful for a continuing check in or research prompt. It does not create a project Driver/Worker execution pair.

   Ask for a schedule

In the intended Mate conversation, describe the message and cadence:

“Every Monday at 9:00, ask me which research question I want to investigate this week. Use the server's timezone and show me the proposed schedule.”

The Mate can interview you, prepare the message, and present a structured review. Scheduling can also be included in a new Mate's reviewed creation intent.

1. Check the target Mate and conversation.
2. Read the exact message.
3. Verify the date, time, and displayed server timezone.
4. Check recurrence and any end condition.
5. Approve the actual schedule card.

A conversational statement saying “approved” is not a substitute for the authenticated review. A cancelled proposal creates no approved schedule.

   Recurrence

You can request daily, weekly, monthly, or yearly recurrence and supported intervals within a day. For example: “Every weekday at 9:00 for the next four weeks.” The review card shows the interpreted timing and end condition.

Messages are bounded; a schedule prompt should identify a task rather than embed a long manual. Store larger reference material in the Mate's Knowledge.

Server timezone matters when you travel or connect from another device. Do not assume a browser's clock changes the saved cadence.

   Update or cancel

Ask the Mate to list or read its schedules, then request a change to the specific one. Review the updated message, timing, and target before approval. Cancellation also uses a reviewed lifecycle action.

After cancellation, inspect the saved status. A delivery already in progress may have effects that cancellation cannot recall.

   Delivery limits

If the server misses several scheduled times, those messages can be combined into one delivery. Later messages follow the schedule again. After a crash, check the conversation before requesting another delivery: the provider may already have received the previous message.

Check the conversation to see the result of a delivery. If access changed or the conversation is unavailable, resolve that before requesting a replacement schedule.

See  Delayed messages  /docs/delayed messages ,  Project Scheduled Tasks  /docs/scheduled tasks , and  Automation overlap  /docs/automation overlap .


Recurring Mate messages

Schedule Driver and Split Worker work with recurrence and run history.

  Project Scheduled Tasks

Use Project Scheduled Tasks for work that should run at a chosen time, such as a recurring review of dependency alerts. Each run uses a  Driver and Split Worker  /docs/drivers workers : the Driver manages the task and reviews the Worker's result.

For a reminder or recurring question in a private chat, use  Mate messages  /docs/mate schedules  instead.

   Create through an interview

1. Select the ordinary project.
2. Open   Scheduled   from the tool palette.
3. Choose   New  .
4. Answer the task interview, including outcome, instructions, timing, and execution pair.
5. Review the prepared task in Scheduled.
6. Select   Create task   yourself.

New interviews use the shared   Default AI  ;   Change default   changes that interview choice. The interview prepares a proposal. It does not replace the final human Create task action.

For direct entry, open the menu beside New and choose   Manual creation  .

   Fill the form

Enter   Name   and   Instructions  . Good instructions define the allowed work, checks, and report: “Review new dependency alerts, report actionable changes, and make no commits.”

Set   Date   and   Time  . Times use the   server local timezone   shown in the summary.

    Repeat   enables a cadence in days, weeks, months, or years. Weekly recurrence selects weekdays.
    Ends   limits recurrence to a date or occurrence count.
    Interval   repeats within each active day in minutes or hours, optionally ending after a count or time.
    Advanced custom schedule   accepts a five field cron expression.

Repeat chooses active days; Interval chooses multiple starts within each active day. For example, a weekly repeat on Monday and Wednesday with a two hour interval creates several starts on those days. Read the generated summary to confirm the start time and any interval end before saving.

 ! Schedule draft with Monday and Wednesday selected, a two hour interval and a generated summary.  /images/manual/schedule recurrence.webp   /images/manual/schedule recurrence.webp 

 Repeat selects Monday and Wednesday; Interval adds starts every two hours on those days. The summary states the schedule and server timezone. This example was cancelled without creating a task. 

   Configure execution

Choose vendor, model, and supported effort independently for Driver and Split Worker. Both must have an available model and support the tools needed for scheduled work. If the task reports Unavailable, read its reason and choose a supported configuration.

  Skip a scheduled start while this task already has an active run   is enabled by default. Turning it off combines overlapping starts into one queued run; it does not launch unlimited parallel copies.

   Operate and inspect

Expand a task to use   Edit  ,   Pause/Resume  ,   Run now  ,   Open run  , or   Delete  .

| Status | What to do |
|     |     |
|   Needs setup   | Edit the task and configure its Driver/Worker execution pair |
|   Unavailable   | Read the reason; check provider installation, model choices, and support for scheduled work |
|   Needs input   | Use Open blocked run and answer the pending question or review |
|   Waiting for Worker   | Open the run to follow the Worker's progress |
|   Driver reviewing   | Wait for the Driver's review and final result |

Use   Open blocked run   to answer required input in the actual execution context. A completed Worker is not the same as a completed Driver review.

Pause affects future starts; inspect the active run separately. Delete removes the schedule record, so read its confirmation. Run now still obeys eligibility and overlap controls.

See  Automation overlap  /docs/automation overlap ,  Drivers and Workers  /docs/drivers workers , and  Loop and Ralph  /docs/loops and ralph .


Project Scheduled Tasks

Use the built-in Loop interview and Ralph workflow where available.

  Loop and Ralph

Use a loop when a task needs repeated attempts and has a clear finish line. For example, an agent might reproduce an export bug, repair it, run a check, and continue if the check still fails. Decide what counts as finished and how long it may continue before starting.

| Workflow | How you prepare it |
|     |     |
|   Guided Loop   | Answer an interview in the current project session and review its objective, checks, and limits |
|   Ralph   | Prepare prompt and judge files that describe repeated coding work and how to evaluate it |
|   Scheduled Task   | Choose when a project Driver/Worker pair should run; use this for timed or recurring work |

   Start a guided Loop

1. Open an ordinary project GUI session and wait for current work to finish.
2. Choose   Start Loop interview   beside the composer.
3. Answer the Driver's questions about the outcome and completion checks.
4. Review   Loop brief ready for review  , including continuation and time limits.
5. Choose   Edit  ,   Cancel  , or   Start  .

Edit lets you change   Objective   and   Completion checks  ; enter separate checks on separate lines and Save. For an export bug, name the failing input and the existing test command. This gives the agent a way to decide when the repair is complete.

  Start enables Skip Permissions for this run. Your previous setting is restored when it ends.   Review the allowed work and limits before starting; this run will not keep asking for routine tool approvals.

   Prepare Ralph

Ask the assistant to set up a Ralph loop for a bounded coding task. It prepares  .claude/PROMPT.md  for the work and  .claude/JUDGE.md  for evaluating the result. Read both before unattended execution.

Describe allowed files, excluded work, acceptance criteria, checks, limits, and what to do when input is missing. The judge should examine the resulting files and check output. Repeating an attempt alone does not establish that it succeeded.

   Schedule or migrate work

For current timed execution, use  Project Scheduled Tasks  /docs/scheduled tasks . Its form requires a Driver and Split Worker.

Older scheduled Ralph tasks can retain their own prompt/judge files, models, recurrence, and history. If migrating one, inspect those settings and pause the old schedule before starting an equivalent new one, so both do not run unintentionally.

   Inspect an interrupted run

Read the current files, completed checks, and any running commands before continuing. Pausing a schedule affects future starts; stopping the active session affects current execution.  Stop and recovery  /docs/stop recovery  gives the recovery sequence.


Loop and Ralph

Understand skipped starts, combined runs, and safe resumption.

  Pause, skip, and overlap

Use Pause to prevent future scheduled starts and Stop to interrupt work already running. Overlap settings decide what happens when another scheduled time arrives before the previous run finishes.

   Choose overlap behavior

For a project Scheduled Task, open   Scheduled  , expand the task, and select   Edit  . Inspect:

  Skip a scheduled start while this task already has an active run  

When enabled, a scheduled start during an active run is skipped. When disabled, overlapping starts are combined into one queued follow up, rather than a separate run for every missed time.

For example, a task scheduled every ten minutes can take twenty five minutes to finish. Skip avoids another start during that run. Coalescing preserves one follow up opportunity rather than starting several concurrent copies.

   Pause versus Stop

  Pause   disables future scheduled starts. It does not by itself prove an active Driver, Worker, command, or external request stopped.

To halt current execution:

1. Open the actual run.
2. Confirm the Driver/Worker target.
3. Use the relevant Stop control.
4. Inspect its last observed result and pending work.
5. Resume only when the remaining action is understood.

  Run now   is a start request, not an override of every readiness, busy, or Stop rule.

   Inspect outcomes

Read task status and open its run. Needs input, Waiting for Worker, Driver reviewing, completed, skipped, and failed describe different situations.

Open the run to see whether it is waiting, executing, or under Driver review. If the connection was lost, check the last result before retrying.

   Restart and missed times

The server must be running for automation. After a restart, check restored pending work separately from a task that was already executing.

Missed Mate messages can be combined into one delivery, followed by the next future occurrence. Delayed composer messages are one shot jobs. Legacy Loop/Ralph follows its own task configuration and history. Do not apply one system's recovery assumptions to another.

Before retrying a task that sends mail, publishes work, or changes an external service, check that destination. The action may have completed before the connection failed.

See  Scheduled Tasks  /docs/scheduled tasks ,  Mate schedules  /docs/mate schedules ,  Delayed messages  /docs/delayed messages , and  Stop and recovery  /docs/stop recovery .


Pause, skip, and overlap

Connect remote, local, and browser-extension MCP servers.

  MCP servers

MCP connections give an agent tools from another service or local program. For example, a connected issue service can let the agent read current requirements instead of relying on pasted text. First connect the service, then enable it where you want to use it; individual actions can still ask for permission.

   Add a remote server

1. Open   MCP / Skills  , then   MCP Servers  .
2. Choose   Add → Remote MCP URL  .
3. Enter the service's actual   Server URL  .
4. Select   Continue  .
5. Complete sign in if required.
6. Inspect its tool catalog and enable it for the intended scope.

Public HTTPS endpoints are supported by this remote flow. If needed, the connection detail offers   Use an access token → Save and connect  . Enter tokens in that settings form, not in a transcript.

Connection status distinguishes   Ready  ,   Saved · connects when used  ,   Connecting…  ,   Sign in required  , and   Unavailable  . A saved idle connection is not necessarily broken.

   Inspect tools and permissions

Open a connection's   Tools   tab. Expand a tool to read what it does and the inputs it accepts. The   Permissions   tab offers applicable AI review behavior: session default, AI review, or Ask every time.

Enabling a connection does not approve every tool call. Session permission policy and action specific authorization still apply.

If the agent cannot see a tool, check that the connection is enabled for the intended conversation and that its provider supports the connection.

   Local and computer connections

  Import vendor config   inspects supported runtime configuration and can produce a disabled local copy after review. See  Imports and skills  /docs/mcp import skills .

  On your computer   uses the Clay Studio browser extension. Follow the displayed extension/native bridge instructions, including the generated install command for that extension ID. This is different from a process running on the Clay Studio server.

Computer connections are configured per project. Personal imported and remote connections are for supported owner private conversations. They are unavailable in shared sessions, and a private session can also lose access after another person's input. Making the session private again does not erase that history. A Worker cannot use personal tools to bypass its Driver's restrictions.

For a personal task, use your own private conversation with the appropriate connection. Keep material you retrieve there private unless you intend to share it.

The Chrome extension bridge is not available in private Mate conversations. Use the  shared Browser  /docs/browser  there.

   Maintain a connection

Use   Manage connection   to rename or remove a managed connection. Removal disables it and removes saved connection credentials; it does not revoke an external service account by itself.

If sign in fails, inspect the connection status and provider flow before repeatedly adding duplicates. See  Browser  /docs/browser ,  Permissions  /docs/permissions , and  Provider capabilities  /docs/provider capabilities .


MCP connections and browser extension

Import vendor connections and use the Skills workbench safely.

  MCP imports and skills

An   MCP connection   gives the agent tools from a service or local program. A   skill   supplies instructions for a repeatable workflow. For example, a connection might let an agent retrieve live issue data, while a skill explains how to structure a review. You can use both in the same task.

If you are adding a service for the first time, start with  MCP connections  /docs/mcp servers . Use import when you already have a connection configured for another coding agent.

   Import an existing connection

1. Open   MCP / Skills → MCP Servers  .
2. Choose   Add → Import vendor config  .
3. Select an available vendor source.
4. Check the discovered connection's source, command or URL, and scope.
5. Select the connection and approve its import review.

Discovery only reads configuration. Import saves a   disabled copy  ; it does not run the command or sign you in. Open the imported connection, enter any required credentials in its settings, then enable and test it. Existing vendor login credentials are not automatically transferred.

If several entries look similar, use their source and destination to choose the right one.

   Find and use a skill

Open the   Skills   area of MCP / Skills and select a skill to read its description and instructions. For an installable skill, choose   Add to this project   or   Add to all projects   according to where you want it available. The detail view shows its installed scope after installation succeeds. Built in skills are already available and have no install step.

Ask for the skill by name in a conversation: “Use the review skill to assess this proposal.” Some providers also offer it in the slash command menu. Installation makes the workflow available; it does not run it immediately.

Read the instructions before using a skill for consequential work. Your request and the relevant permission controls still govern sending messages, publishing changes, and other actions.

   Installing Clay Studio specific skills manually

Skills reserved for Clay Studio use the  clay    prefix. Built ins ship with the application. Optional Clay Studio specific skills belong in the owner's or project's  .clay/skills/  directory, separate from generic vendor skill folders.

If a skill is missing, check its installed scope and current provider. If a connection remains idle, its status may say it connects when used;  connection states  /docs/mcp servers  explains how to distinguish that from a failure.


MCP imports and Skills

Link issues and pull requests to sessions and review repository changes.

  GitHub

Clay Studio links sessions and project Issues to exact GitHub issues and pull requests. A link helps identify related work; it does not post a comment, create a commit, merge a PR, or grant repository access.

   Link session work

In the intended session, provide the exact GitHub URL or an unambiguous repository and issue/PR number:

“Investigate this pull request and its linked issue.”

An eligible agent can read the work and save relevant session links. Ask it to check existing linked conversations before duplicating an active investigation. Linking metadata itself does not modify GitHub.

Open a linked work badge to inspect its current title/status and related entries. Verify the repository when names or numbers overlap.

   Choose a primary

The linked work popover groups issues and pull requests and offers   Make primary  . Select the item you want emphasized and check for   Primary saved  .

Refreshing or adding a link does not replace an existing primary automatically. If asking the assistant to change primary, make that request explicit and review the exact proposed change. Unlinking a saved primary can require choosing a replacement first.

   Connect a Clay Studio Issue

Open the Clay Studio Issue and choose   Connect to GitHub  . Clay Studio searches existing open and closed work and compares potential matches.

A clear match can be linked; ambiguous matches require your choice. If no suitable issue exists, review the proposed title, description, and repository before authorizing creation. This action publishes content to GitHub, unlike a local session link.

If creation has an uncertain result, inspect GitHub and link the actual created URL before trying again. Automatic retry can create a duplicate.

   Authentication and verification

GitHub operations use tools on the server. Where Clay Studio uses the GitHub CLI   gh  , that CLI must be authenticated under the appropriate server OS account. Follow  GitHub CLI authentication  https://cli.github.com/manual/gh auth login ; signing into the website in your viewing browser does not configure it.

Read failures carefully: wrong repository, missing permission, expired authentication, and unavailable tools are different problems.

For code work, inspect the actual diff, commit SHA, remote branch, and PR result. Open the repository or PR to confirm publication. Explicitly request comments, publication, or merge when those actions are intended.

See  Issues  /docs/issues ,  File history and Git  /docs/file history git , and  Linear  /docs/linear .


GitHub

Understand saved connection limits, existing issue links, and the separate MCP route.

  Linear

Clay Studio can link a conversation to a Linear issue so its requirements, status, and related work stay together. This depends on a working native Linear connection. Linear's official MCP service is a separate way for an assistant to read or update issues.

   Current connection limitation

  Saving a new named Linear connection does not currently assign it to Clay Studio's native session tools.   There is no assignment control in the current UI. A saved key or   Not assigned   state therefore does not mean native issue search and linking are ready to use.

An existing legacy connection may still support those features. If native access is unavailable, use authorized Linear MCP tools for the work itself, or supply the issue details in the conversation. MCP access alone does not create Clay Studio's linked badges or related conversation records.

   Manage a saved named connection

1. Open   Settings → Personal → Integrations  .
2. Under   Available integrations  , choose   Linear  .
3. Enter a   Connection name   and your own   Personal API key  .
4. Choose   Save connection  .
5. Check the entry under   Your connections  .

This saves credentials, subject to the limitation above.   Manage   lets you rename the connection or replace its key; leaving the key blank keeps the saved value. Disconnect removes the connection while retaining existing issue links. Enter keys only in settings, never in chat.

   Read and link when native access works

Give the assistant an issue URL or identifier: “Read CLAY 123 and check for existing linked work before implementing it.” If several issues match, choose the intended one.

Open the Linear side panel to read requirements, comments, and   Linked conversations  .   Link this conversation   and   Unlink this conversation   manage the current session's association. Linking does not post a comment or change Linear, but issue titles and status are visible to people who can view the Clay Studio conversation.

Use   Make primary   in linked work to emphasize one issue. Adding another link does not replace a saved primary. If a GitHub PR implements the issue, link both so the relationship is easy to follow.

   Use official Linear MCP

Linear publishes its remote MCP service at  https://mcp.linear.app/mcp . It supports reading and writing Linear objects after authorization. Follow  Linear's official MCP setup instructions  https://linear.app/docs/mcp  for your client, or use Clay Studio's  remote MCP connection flow  /docs/mcp servers  with that URL and complete sign in.

Ask the assistant to check which tools are actually available before requesting an update. For example: “Read this issue and draft a clarification comment for me to review.” Send or publish only when you intend that action. A draft remains useful even when the connected tools cannot post it.

For native access failures, distinguish the connection limitation above from an issue in another workspace or one your account cannot read. Repeatedly saving another named key does not resolve assignment.


Linear

Connect personal mailboxes and distinguish them from server SMTP.

  Personal email and server SMTP

Personal mailboxes let an eligible assistant read, search, and send your mail. Server SMTP handles Clay Studio's server delivery, including invitations and login codes. These are separate connections and scopes.

   Connect a personal mailbox

1. Open   Settings → Personal → Integrations  .
2. Under   Available integrations  , choose Gmail, Outlook Mail, Yahoo Mail, or   Custom email  .
3. Enter the mailbox details and required app password.
4. Supply custom server information when needed.
5. Test the connection through the offered control.
6. Save and confirm the account appears.

Use the provider's app password instructions:  Google  https://support.google.com/accounts/answer/185833?hl=en ,  Microsoft personal accounts  https://support.microsoft.com/en us/accounts billing/manage/how to get and use app passwords , or  Yahoo  https://ca.help.yahoo.com/kb/account/generate manage rd party passwords sln15241.html . Availability depends on the account and its security policy;  Microsoft work or school accounts  https://support.microsoft.com/en us/accounts billing/work school/create app passwords for your work or school account  may have app passwords disabled by the administrator. An app password does not guarantee that a provider permits IMAP/SMTP access. If the connection test refuses authentication, check the provider's current mail access requirements.

Saved accounts offer   Manage → Disconnect  . Disconnecting removes Clay Studio's connection while keeping mail at the provider.

   Ask for mailbox work

State the account and scope: “Search my work mailbox for messages from this sender since Monday and summarize them. Do not reply.”

Tools can read folders, search, inspect message details, reply, and mark messages where available. Specify the folder if it is not INBOX. Reading/searching and sending are different actions.

For a send request, review the sender account, To, CC/BCC, subject, and body. Say explicitly when you want it sent. If several accounts are enabled, name the sender rather than relying on a default.

If sending times out, check the send result before trying again so you do not send a duplicate.

   Configure server delivery

Administrators use   Server Settings → Email delivery   for SMTP host, port, credentials, sender details, and applicable registration/email code settings.

Port   587   with direct TLS off uses STARTTLS; port   465   with TLS on uses direct SSL. Use the actual mail service's requirements. Save and test delivery rather than assuming that credentials alone establish reachability.

Server SMTP does not provide a personal inbox reader. Assistant email tools can distinguish server and personal send modes; specify the intended identity.

   Fix failures

Check host/port, app password requirements, network access, selected mailbox, and the actual error. Removing SMTP can affect invitation/login delivery, so read its confirmation.

Keep credentials in settings, never in repository files or chat. See  Account security  /docs/account devices security ,  Users  /docs/team users roles , and  Permissions  /docs/permissions .


Personal email and SMTP

Manage users, roles, permissions, and ownership.

  Users and roles

Account roles govern server administration and feature permissions. Project ownership and session privacy govern content access separately. An administrator is not automatically the reader of every private project or conversation.

   Add an account

An administrator opens   Server Settings → Users → Accounts   and chooses   Add user  .

1. Enter the username and optional display name/email fields.
2. Review the account details.
3. Create the account.
4. Give the temporary sign in information to the intended person through an appropriate channel.
5. Have them complete first login credential changes.

The account form can generate a temporary six digit PIN. Password policy installations can require password enrollment before ordinary account use. Read the actual sign in flow for the server's current policy.

   Invitations

Use   Users → Invitations   to create, copy, email, or revoke invitation links. Email invitations require configured  server SMTP  /docs/email .

An invitation is account onboarding, not automatic ownership of every project. After joining, the person still needs project access and permission for the relevant features.

Revoke an unused invitation when it should no longer admit someone. Do not treat revocation of an invitation as signing out an account that already joined.

   Permissions

Open a non administrator user's   Permissions   control, review the feature toggles, and Save. Permissions can govern actions such as project/session management or tool access.

Check the actual account after a change. A hidden control or refused request may reflect role, feature permission, project access, or session ownership; these are different causes.

   Ownership and recovery

Only the project owner can transfer ownership or change sharing. Before removing an account, resolve the ordinary projects it owns, including registrations whose directories are unavailable. If removal is blocked and you cannot access the ownership controls, ask the server operator to investigate the affected registrations rather than deleting their directories.

Administrator overview/access metadata for a foreign private project does not grant its files or transcripts. Private Mate projects are excluded from that ordinary overview.

If someone cannot recover their sign in through the offered flow, contact the server operator. Ordinary administrator access does not provide a way to impersonate another person and read private content.

   OS level isolation

Application access checks are not isolation from a machine/root operator. Agent commands and terminal shells exercise the underlying OS account's authority. Distinct OS users and filesystem permissions are needed for stronger process separation; Clay Studio's OS user mode requires Linux, root, and multi user setup.

See  Project sharing  /docs/project sharing ,  Account security  /docs/account devices security , and  Server settings  /docs/server settings .


Users and roles

Set public, private, allowed-user, and inherited access.

  Project sharing

Project access determines who can enter an ordinary project. Session visibility determines which conversations inside it they can read. Neither setting publishes the workspace anonymously to the internet.

   Set project visibility

Open the chevron beside the project name in the workspace header and choose   Manage Access  . This opens   Project Access   in account mode.

1. Confirm the exact project and owner.
2. Open   Manage Access   from that project's header menu.
3. Choose   Private   or   Public  .
4. For a private project, select   Allowed Users  .
5. Reopen/check the saved state and have the recipient verify access.

Public ordinary projects are available to authenticated workspace users under the server's rules. Private projects require ownership or an explicit grant. Only the valid owner can change sharing; administrator role alone does not supply content ownership.

If no other users are available, create or invite accounts first. A link cannot substitute for an account grant.

   Set new session defaults

Open the project header menu, then   Project Settings → Access → New session visibility  . The owner can choose   Private   or   Shared with project members  .

This applies to new ordinary project conversations and Issue   Start work   sessions. Existing sessions, hidden work, and delegated workflows keep their current visibility. Administrators can view the default but cannot change it for another owner.

Worktrees inherit this default from their parent; change it in the parent project.

   Share a particular conversation

Inspect that session's own privacy/sharing controls. A public project does not override a private conversation. Project ownership transfer also does not transfer private session ownership.

For collaborative work, create an appropriately shared conversation and summarize the necessary context there. Keep owner private Mate or Me information out of it unless deliberately shared.

   Revoke or diagnose

Remove an exact grant when it should no longer apply. Access revocation can close existing connections, and reconnect checks current authorization.

If access persists for a worktree, inspect parent inheritance. An inherited Entire project grant cannot be removed only from a child worktree. See  Worktree sharing  /docs/worktree sharing .

If the UI says   Ownership needs recovery  , ask the server operator to investigate the account and directory ownership. Content stays disabled until that is resolved; changing a sharing checkbox cannot repair it.

For account roles and underlying OS authority, see  Users and roles  /docs/team users roles . For conversation privacy, see  Session privacy  /docs/session privacy sharing .


Project sharing

Create a worktree, understand inherited access, and remove it when finished.

  Worktrees and sharing

A Git worktree is a separate working directory for the same repository. Use it for parallel changes that need independent branches and files. A split View only arranges conversations; it does not provide this isolation.

   Create and use a worktree

1. Open the chevron beside the parent project's name in the workspace header.
2. Choose   Add Worktree  .
3. Enter   Branch name  , such as  feat/export validation .
4. Choose   Base branch  , select   Create  , and wait for the result.
5. Open the new worktree under its parent.
6. Verify the directory and branch before starting a session.

Use one worktree for a feature and another for a conflicting fix. Commit and integration remain separate Git actions; creating a worktree does not merge its eventual changes.

Externally located worktrees can be marked separately. Read the location/status rather than assuming every child directory is managed identically by Clay Studio.

   Share exactly what is needed

Open the worktree's header menu and choose   Manage Access   to open   Worktree Access  .

A private parent can provide   Entire project   access that is inherited automatically. Those checked inherited users cannot be removed from just the child.   People with exact access   identifies grants for this worktree only.

For example, grant a reviewer exact access to a feature worktree without giving them the entire private parent project. Conversely, a person already granted the whole project inherits its worktrees.

If the parent is public, every authenticated user can access the worktree. Exact grants are retained in case the parent later becomes private.

   Session defaults and records

New session visibility is inherited from the parent project's setting. Change it at the parent; a worktree does not independently override that default.

Project records can have scope filters. In Logs,   Current worktree  ,   Project  , and   All changes   distinguish relevant change records from broader project history. Sharing records does not merge filesystem contents.

   Remove carefully

Open the worktree's menu and choose   Remove Worktree  . In the managed worktree deletion flow, the confirmation warns that the branch and working directory will be removed from disk. Preserve uncommitted changes and stop work that uses the directory before confirming. This is more destructive than merely unregistering an ordinary project.

Externally managed worktrees can have restricted removal controls. Do not use a manual directory delete as a substitute without understanding Git's worktree state.

If a path becomes unavailable, confirm its actual location and OS access. An old browser arrangement cannot restore a deleted working directory.

See  Projects and directories  /docs/projects working directories ,  Project sharing  /docs/project sharing , and  File history and Git  /docs/file history git .


Worktrees and sharing

Manage credentials, devices, passkeys, and sign-in policy.

  Account, devices, and security

Manage your own credentials and browser sessions in   Personal settings → Account  . Administrators configure server wide authentication policy separately.

   Review signed in devices

1. Open Personal settings and choose   Account  .
2. Find   Signed in devices  .
3. Select   Manage sessions  .
4. Identify   This session   before signing anything out.
5. Review browser/device information, last observed activity, IP, and expiry.
6. Choose   Sign out   for the intended entry and confirm.

You can also sign out other sessions through the offered control. Signing out the current session returns you to sign in. Merely expanding the device list stays inside settings.

Older migrated sessions can show   Unknown device   or   Previous activity unknown  . These are missing historical metadata, not evidence of a particular device or login time.

Sessions expire, so an older browser tab may ask you to sign in again.

   Passwords and PINs

Account settings shows whether you use a PIN or password. Choose its Change control and complete the verification shown.

An administrator can switch account sign in from PINs to passwords. This change cannot be reversed through the policy control. At your next sign in, use your existing PIN to enroll a password, then use the password for normal access.

A legacy single user Server PIN is separate from multi user account authentication. Do not try to repair an account login by changing an unrelated Server PIN.

   Passkeys

Where configured, choose   Manage passkeys  . Password enrolled accounts can register, name, rename, and remove passkeys. Management requires fresh password verification and your browser or device's verification.

Use the sign in address configured for passkeys. If you open Clay Studio through a different hostname or tunnel, a passkey may not work there; use password fallback and ask the administrator to check the  passkey settings  /docs/server settings .

Password fallback remains available. Recovery can clear passkeys and invalidate affected sessions. TOTP authenticator enrollment is not part of this supported flow.

   Resolve sign in problems

Use the server's actual sign in URL, check HTTPS and account policy, and distinguish an expired browser session from provider authentication. Your coding agent login does not sign you into Clay Studio.

See  Users and roles  /docs/team users roles ,  Server settings  /docs/server settings , and  Provider authentication  /docs/provider auth .


Account, devices, and security

Configure HTTPS, proxy, SMTP, storage, upgrades, restart, and backup.

  Server settings and operations

Server Settings apply to the Clay Studio installation and can affect everyone connected. Personal settings apply to your account; project settings apply to a selected project. Clay does not operate Server or User Settings for you.

   Inspect the server

Open   Server Settings → Overview   for host, process, uptime, memory, and current project connection information. Configuration changes require administrator access in account mode.

Use the displayed server URL and port when diagnosing another device. Localhost on the viewing device is not the remote Clay Studio host.

   HTTPS and proxies

Production defaults to HTTPS on port 2633. Startup options choose port and listening address. The following settings address different problems:

| Setting | Use it when |
|     |     |
| Allowed external origins | A proxy changes the Host header and the workspace connection is rejected |
| HTTPS & trusted proxies | Account sign in relies on HTTPS information supplied by your reverse proxy |
| Passkey sign in address | You are enabling passkeys for a fixed sign in hostname |

In   Network → Reverse proxy & tunnels  , add   Allowed external origins   when a proxy rewrites the upstream Host. Enter one exact HTTP/HTTPS origin per line, with port where needed, and no path or wildcard. Example:  https://clay.example.com .

Saving applies to new WebSocket connections. Reconnect to verify. Direct connections and proxies preserving Host normally need no extra origin.

Account transport uses separate   HTTPS & trusted proxies   controls under Access & security. Configure the permanent proxy HTTPS address and exact trusted proxy IPs only when appropriate. Trusted proxies must overwrite forwarded protocol/client address and prevent direct public backend access. Forwarded headers are not trusted automatically.

Passkeys have a separate exact   Passkey sign in address  . Network allowlisting does not expand passkey trust.

   Email delivery

For invitations and login email, open   Server Settings → Email delivery   and configure SMTP. Follow  Personal email and SMTP  /docs/email  for host, port, TLS, and test delivery steps. This connection does not give an assistant access to a personal inbox.

   Storage and retention

Open   Storage   and select   Refresh usage   for a new measurement. Read timestamps and partial/unavailable indicators. Cached results can be up to five minutes old; unavailable does not mean zero bytes.

Usage can attribute registered projects to owners or mapped Linux identities. Shared, nested, conflicting, and skipped paths affect totals. Image retention controls govern supported stored images, not a complete repository backup.

   Update, restart, and stop

In   Operations  , inspect Software updates and choose   Update now   when intended.   Restart   interrupts active work and reconnects browsers.   Danger zone   shutdown stops the server for everyone; starting again requires host access.

Before maintenance, inspect active sessions, queues, and scheduled runs. Afterward, verify the server version, provider readiness, and unfinished work rather than assuming interrupted actions replay safely.

   Back up and recover

There is no general backup/restore button implied by Storage. For an operator backup, stop Clay Studio for a consistent copy and preserve its configured data directory, registered project directories, provider required state, and relevant configuration using your host backup system.

The default data location is  ~/.clay ;  CLAY HOME  can change it. Development uses separate state. Store backups securely because they can contain private history and credentials. Test restoration in an isolated environment before replacing live data, and never run two active writers against the same data store.

See  CLI flags  /docs/cli flags ,  Account security  /docs/account devices security , and  Troubleshooting  /docs/troubleshooting .


Server administration

Resolve common symptoms with evidence-backed checks.

  Troubleshooting

Start with the symptom below. If an action may already have completed, check its result before repeating it—especially a send, publication, or external update.

   Clay Studio will not open

  On the server machine:   check the terminal or service that started Clay Studio. Use its printed URL and port. If the server is stopped, start it through the normal  CLI flow  /docs/cli flags . Follow any certificate instructions shown at startup.

  Only on another device:   first confirm the printed address works on the server. Use its reachable hostname from the other device; localhost on a phone refers to the phone. If the hostname cannot be reached, ask the operator to check the network, listening address, and firewall before changing account settings.

  Through a proxy or tunnel:   compare direct access with the proxy address. If the page loads but the connection fails, the operator should check   Server Settings → Network → Reverse proxy & tunnels  . A proxy that rewrites Host can require an allowed external origin. Account HTTPS proxy trust is a separate setting. If the UI is unreachable, use a working direct connection to inspect settings or ask the host operator for help.

See  Server administration  /docs/server settings  for the distinction between network origins, trusted proxies, and the passkey address.

   Sign in or project access fails

Check the signed in account and the server's PIN/password policy. A provider login is separate from Clay Studio account sign in.

For a project link, check project access, then session visibility. An administrator does not automatically have access to private conversations. For passkeys, use the configured sign in address; a different tunnel hostname may require password fallback. See  Account security  /docs/account devices security  and  Project sharing  /docs/project sharing .

   Provider missing or request rejected

If the provider is missing from the picker, check that its CLI is installed under the server's OS account. If it is listed but requests fail, check sign in and model access.

Use   Retry   in a failed model picker. If authentication works but the provider reports a rate limit, read its reset information instead of repeatedly sending the request.  Provider sign in  /docs/provider auth  includes setup steps.

   Nothing seems to happen

Look for an unanswered question, permission card, paused queue, future scheduled message, active tool, or rate limit notice. A queued message is waiting to run.

For a Scheduled Task, expand it and read the status.   Open blocked run   takes you to input it needs. For a background task, open its viewer and use   Refresh   after resolving a connection problem.

   Files or records look stale

Check the project, worktree, and full path, then use Refresh in Files. In a Mate's Knowledge, a document can be saved while its search update fails; use   Retry index sync   rather than creating a duplicate. Clear database filters before concluding a record is missing.

If an edit conflicts with another saved change, preserve your draft, reload the current version, and reapply the intended change.

   Browser or voice fails

For responsive testing, use   Browser viewport  ; resizing the surrounding pane only scales the display. Check whether shared control is paused and whether Browser is live or showing its last frame.

For voice, check microphone permission, HTTPS, input device, transcription mode, and any required provider credentials. Review the transcription before sending.

   After a crash or uncertain action

Reconnect and inspect the conversation, queue, files, and any external destination before retrying.  Stop and recovery  /docs/stop recovery  gives a recovery sequence.

If reporting a problem, include the Clay Studio version, provider, exact error, steps to reproduce, and what you observed. Leave out credentials and unrelated private content.


Troubleshooting

Navigate, search, compose, and control panes with keyboard shortcuts.

  Keyboard shortcuts

These keys apply to Clay Studio's workspace. Focus matters: keys typed into Terminal or the streamed Browser page go to that surface rather than necessarily to the composer.

   Workspace and transcript

| Keys | Action |
|     |     |
|   Command+K / Ctrl+K   | Open the workspace command palette |
|   Up / Down   in the palette | Move between results |
|   Enter   in the palette | Activate the selected result |
|   Escape   in the palette | Close it |
|   Command+F / Ctrl+F   in a session | Open find within the session |
|   Enter   in session search | Next match |
|   Shift+Enter   in session search | Previous match |
|   Escape   in session search | Close search |

Command is the usual macOS modifier; Ctrl is the alternative supported by these handlers. The docs site's search is separate from Clay Studio workspace navigation.

   Composer

| Keys | Action |
|     |     |
|   Enter   on desktop | Send the current message when no selection menu consumes Enter |
|   Shift+Enter   | Insert a newline |
|   Ctrl+J   | Insert a newline |
|   Up / Down   in slash menu | Choose a command |
|   Tab / Enter   in slash menu | Select the highlighted command |
|   Escape   in slash menu | Dismiss that menu |
|   Backspace   in empty mentioned composer | Remove the recipient mention chip |

On touch devices, Enter inserts a newline and the Send button submits. IME composition does not submit merely because its confirmation uses Enter. An empty Enter press while processing does not send a stale suggestion.

   Editing and organization

Session Rename uses Enter to save and Escape to cancel. Moving focus away also saves a changed nonempty title.

Session context menus support Up/Down, Tab/Shift+Tab, Home, End, and Escape. The Worker runtime picker supports arrow navigation and Home/End. Native selects and buttons retain their ordinary activation behavior.

Queued message drag handles support arrow key reordering. Check the resulting order, especially if the queue updates while you are editing.

In a reserved split session picker, Escape cancels the reservation and returns to the prior geometry. Menus can consume Escape before the containing conversation closes.

   Tool focus

Terminal supplies touch controls for modifiers and arrows. Ctrl+C there normally interrupts a foreground shell command; it is not a global Clay Studio Stop shortcut.

Use visible Stop controls for agent interruption. In shared Browser, verify the selected tab and control mode before typing.

See  Composer  /docs/composer basics ,  Session search  /docs/session history search , and  Terminal  /docs/terminal .


Keyboard shortcuts

Use documented Clay Studio server commands and CLI options.

  CLI reference

Run the CLI on the machine that hosts Clay Studio. It starts or controls the daemon; it is not a command sent through an agent conversation. Node.js 20 or newer is required.

   Common commands

   bash
npx clay server
npx clay server  p 8080
npx clay server   add .
npx clay server   list
npx clay server   remove /path/to/project
npx clay server   restart
npx clay server   shutdown
   

Add, remove, and list address the running daemon. Add resolves the supplied directory; remove unregisters the matching project. They are not repository clone or filesystem delete commands. Restart and shutdown affect everyone on that daemon.

   Supported options

| Option | Purpose |
|     |     |
|   h ,    help  | Print usage and exit |
|   p ,    port <port   | Listening port; production default 2633 |
|    host <address  ,    bind <address   | Bind address; default 0.0.0.0 |
|    no https  | Disable default HTTPS |
|    local cert  | Use local mkcert certificate and suppress migration notice |
|    builtin cert  | Use built in certificate even if mkcert is installed |
|    no update ,    skip update  | Skip startup update check |
|    debug  | Enable the web debug panel |
|   y ,    yes  | Accept default interactive choices |
|    pin <pin   | Set a six digit PIN, typically with   yes |
|    headless  | Start the daemon and exit; implies   yes |
|    multi user  | Start in account mode |
|    os users  | Linux OS user isolation; requires root and multi user mode |
|    dangerously skip permissions  | Bypass routine agent permission prompts |
|    add <path   | Register a directory with the running daemon |
|    remove <path   | Remove a registration from the running daemon |
|    list  | List registered projects |
|    restart  | Restart the running daemon |
|    shutdown  | Stop the running daemon |

Permission bypass does not remove Clay Studio account/project access restrictions or replace required product reviews. Account mode sign in policy is separate from the legacy Server PIN.

   Unattended startup

   bash
npx clay server   headless   multi user  p 2633
   

Complete the actual administrator setup flow and use the printed address. Headless does not mean anonymous access or that providers have been authenticated.

Use  CLAY HOME  to select a data location when intentionally managing an independent installation. Preserve configuration and avoid concurrent writers to the same data store.

   Development only options

   dev  uses development state, default port   2635  , debug mode, and skips update checks.   w  /    watch  enables the CLI's watch mode. These are Clay Studio application development controls.

If the installed version differs, run its    help  and check the observed behavior. See  Server settings  /docs/server settings  for network and operations details.


CLI reference

Look up Clay Studio concepts and follow links to the relevant guides.

  Glossary

Follow a term's link for examples and instructions.

   Workspace and collaborators

| Term | Meaning |
|     |     |
|    Clay Studio  /docs/getting started    | The application and server that provide your workspace |
|    Clay  /docs/clay vs mates    | Your built in lead Mate, who helps coordinate work and operates supported workspace controls |
|    Mate  /docs/mate creation identity    | A private AI collaborator with a continuing role, instructions, and conversations |
|    Project  /docs/projects working directories    | A folder on the server, with conversations and records for the work there |
|    Session  /docs/session lifecycle    | A conversation you can return to across visits |
|    Provider runtime  /docs/models and providers    | The coding agent application Clay Studio uses, such as Claude Code or Codex |
|    Model  /docs/models and providers    | The AI model selected through that coding agent |
|    Driver  /docs/drivers workers    | The project agent responsible for the task and reviewing its result |
|    Split Worker  /docs/drivers workers    | A linked agent session assigned part of the Driver's work |
|    Background task  /docs/background task conversations    | A task started within a provider's execution, with provider dependent inspection controls |

   Layout and files

| Term | Meaning |
|     |     |
|    View  /docs/split views    | A saved project arrangement of conversations and tool panes |
|    Folder  /docs/navigation    | Organization for session list entries; it does not move repository files |
|    Worktree  /docs/worktree sharing    | A separate Git working directory for parallel changes |
|    Overlay / Dock  /docs/workbench layout    | A tool floating over the conversation / space reserved beside it |
|    Follow / Pin  /docs/files    | A file pane following your selection / keeping one file visible |
|    GUI / TUI  /docs/provider capabilities    | A graphical conversation / a coding agent's terminal interface |
|    CLI  /docs/cli flags    | A program you operate through typed terminal commands |

   Lasting context

   Knowledge  /docs/knowledge documents    holds documents and databases in Mate workspaces. A database   schema   defines its fields; a saved table   view   chooses columns, filters, and ordering without copying its records.

   Project Logs  /docs/project logs    preserve task outcomes and decisions.    Issues  /docs/issues    track actionable work.    Notes  /docs/notes    keep reminders visible while they need attention.

   Me  /docs/mate knowledge memory me    holds private knowledge about you across projects and Mates. Clay reviews reported observations before saving them.   Mate Memory   refers to that Mate's recorded conversation material and is separate from Me.

   Messages and automation

A    draft  /docs/drafts and queue    is unsent text. A   queued   message is waiting for delivery. Delivery or acknowledgement means it reached the receiving system; completion means the requested work finished.

A    delayed message  /docs/delayed messages    sends once after a delay. A    Mate schedule  /docs/mate schedules    sends a private recurring prompt. A    Scheduled Task  /docs/scheduled tasks    runs a project Driver/Worker pair.    Loop/Ralph  /docs/loops and ralph    supports repeated attempts toward a defined outcome.

   Skip  /docs/automation overlap    omits an overlapping start;   coalescing   combines overlapping starts into one queued follow up.   Pause   changes future scheduling.    Stop  /docs/stop recovery    interrupts execution without undoing actions already completed.

   Access

A    public project  /docs/project sharing    is available under authenticated workspace rules, not anonymously published.   Exact access   grants access to one worktree;   inherited access   comes from its parent project. A session has its own  visibility  /docs/session privacy sharing  in addition to project access.

   Permission mode  /docs/permissions    controls how the agent handles tool actions. It does not grant access to another person's private content.


Glossary

Keep the original sessions guide URL available while the catalog grows.

  Sessions

Sessions keep a project's conversations available across visits. Each has its own task history, provider choices, draft, and visibility. A session can remain available after a turn finishes or its pane closes.

   Begin or return

Choose a project, select   New session  , choose an installed provider, and select   Create  . Send a bounded request and inspect the response and relevant tool results.

To return, select the session from its folder or find it through search. Wait for history to load, then review the latest outcome before asking it to continue. Files may have changed since its previous turn.

Start with  Create, resume, and rename  /docs/session lifecycle  for the full procedure.

   Common session tasks

   History and search  /docs/session history search : find earlier messages and decisions.
   Fork and rewind  /docs/session fork rewind : explore another path or inspect a supported checkpoint.
   Settings and handoffs  /docs/session settings : change supported settings and continue elsewhere.
   Privacy and sharing  /docs/session privacy sharing : check who can see the conversation.
   Composer basics  /docs/composer basics : send requests and interpret Send/Stop behavior.
   Drafts and queue  /docs/drafts and queue : edit and reorder pending work.
   Split Views  /docs/split views : arrange several conversations without merging them.

   Keep execution distinct

Closing a pane changes presentation. Stop interrupts execution. Deleting a session is a separate removal operation. Before retrying after disconnection, inspect both transcript and pending queue so a missed acknowledgement does not cause duplicate work.

Several sessions in one directory can change the same files. Use  worktrees  /docs/worktree sharing  for independent branches and  Drivers and Workers  /docs/drivers workers  for delegated tasks.

For model availability and runtime specific limits, read  Provider capabilities  /docs/provider capabilities .


Sessions (legacy guide)

Keep the original Mates guide URL available while the catalog grows.

  Mates

Mates are persistent AI collaborators with defined roles, instructions, Knowledge, and private conversations. Use one when you want a continuing working relationship across tasks.

   Start a relationship

Select   +   in the rail    Add Mate or project   , choose   Create a Mate  , and describe its purpose to Clay. Review the proposal and complete the new Mate's interview. Give examples of the help you want, communication style, and boundaries.

Try a small real request before relying on it for a long workflow. “Review this proposal for unsupported assumptions and ask me one useful question” is an easy way to assess a reviewer Mate.

The  creation and identity guide  /docs/mate creation identity  covers the full setup, including name, avatar, color, and reshaping its behavior.

   Maintain the collaborator

Open the Mate's full workspace and select the header chevron labeled   Open Mate settings  . General, Model, and Prompt settings affect different parts of its behavior. Save changes and verify the actual result.

Use  Mate settings and conversations  /docs/mate settings conversations  to continue the correct exchange or work in the native conversation. Different conversations share the Mate identity but do not automatically contain every detail of each other.

Use  Knowledge, Memory, and Me  /docs/mate knowledge memory me  to choose the appropriate home for reference material, recorded memories, and owner preferences.

   Do more

 Mate schedules  /docs/mate schedules  deliver reviewed recurring prompts to a private conversation.  Debates  /docs/debates  bring multiple Mate roles to a decision.

A Mate remains owner private. Ordinary project sharing or administrator status does not expose its conversation. Connected services still require their own authorization, and ordinary Mates do not receive every Clay's workspace controls.

For project execution, use a project Driver and  Drivers and Workers  /docs/drivers workers . See  Projects and Mates  /docs/clay vs mates  for the boundary between owner level workspace controls and persistent collaborators.


Mates (legacy guide)

Keep the original Split Workers guide URL available while the catalog grows.

  Split Workers

Split Workers let a project Driver delegate bounded execution while retaining the main task context. They are linked work sessions with visible activity, not simply extra browser panes.

   Delegate a useful task

Ask the Driver to use a Split Worker and specify the allowed area, outcome, acceptance criteria, and checks. For example:

“Use a Split Worker to repair the parser's empty input handling. Limit edits to the parser and existing tests, run the relevant checks, and report any uncertainty. Do not commit.”

Read the proposal, choose an available runtime/model/effort, and select   Run with Split Worker  .   Continue here   keeps the work in the current conversation.

Follow  Drivers and Workers  /docs/drivers workers  for the complete creation and review workflow.

   Operate existing work

Use  Worker lifecycle  /docs/worker lifecycle  for interruption, deliberate resumption, replacement, and confirmed removal. Use  Worker messages and queues  /docs/worker messages queues  for steering and pending delivery.

Multiple Workers can belong to a Driver. Keep their task and file boundaries clear. They can share a working directory, so a visual split does not prevent conflicting edits.  Worktrees  /docs/worktree sharing  provide separate filesystem workspaces where needed.

   Review the result

Open the exact Worker's conversation and inspect its report and tool evidence. Confirm changed files, actual checks, unresolved failures, and running processes.

The Driver is responsible for independent review against the user's criteria. A Worker reported pass is evidence to assess; it is not a claim that Driver verification happened.

Provider native  background tasks  /docs/background task conversations  have a different lifecycle and can expose more limited conversation/output inspection. Do not assume a native task is a separately controllable Split Worker.


Background task conversations

#Inspect a task

#Understand the task list's lifetime

#Stop or continue