How workspaces run
Each workspace runs the Replicas Engine, which manages agent sessions, queued messages, git operations, previews, and workspace tools. The engine keeps the agent session and branch available while the workspace is awake. Messages you send from the app, Slack, Linear, the CLI, the API, or another workspace while an agent is busy steer the active turn when the agent supports it. Otherwise they are queued in order. To queue them instead, turn off Steer with follow-up messages in Personal → Preferences. You can edit or remove a queued message before it starts, or steer the active turn with it. Clearing the queue removes waiting messages without adding them to chat history or interrupting the active turn. Messages from any source also wait in order while a workspace prepares or wakes, then run when it is ready.Background tasks
Claude background tasks appear in the transcript with their status, latest activity, output path, and resource usage. Expand a task row to see its originating shell command, progress or final result, subagent type, and prompt when available. They can continue after the turn that created them, and you can send another message while they run. The chat shows Claude as working only during its own turns; a finished task can wake it for a new one. Stop ends the active Claude session and its background tasks; your next message resumes the conversation. Workspace lifecycle actions such as Archive when done wait for background work and Claude’s completion response. If a finished task does not wake Claude, Replicas tries one recovery prompt. Claude Code stops a background shell command after its time limit: 30 minutes by default, up to 2 hours when Claude sets a longer timeout. Claude is notified when that happens. Background subagents have no limit. For dev servers and other long-running processes, usereplicas service. Failed or stopped tasks remain visible in the transcript.
Workspace tools
Open and close the sidebar with the panel button in the top-right corner of the workspace. It has Changes, Files, Desktop, and Terminal tabs, plus Mobile, Canvas, Subagents (Ships in a Mothership), and Side chat once the workspace has something to show there. Opening a Canvas file or media item switches the sidebar to it. Subagents keeps every subagent a chat has started, marked running, done, or failed. Selecting a subagent, in Subagents or from its chip in chat, opens its transcript in the sidebar beside the main chat; subagents that run as their own chat, such as those spawned through the Replicas subagent MCP, can also be messaged from there. Side chats opened with/btw get their own Side chat tab.
Changes and files
Use the sidebar to review changed files, browse the repository, and open files mentioned by the agent, including read-only skill files. In Changes, you can mark files as viewed and attach line comments to send with your next message. Once the workspace has a pull request or merge request, Changes shows its review instead, and selecting one in the workspace header opens it there. Diff lines automatically wrap to the available width, including in narrow panes or when the right sidebar is expanded. Markdown files opened from the repository browser default to Formatted; select Raw to edit them. Other compatible files open directly in edit mode. Files opened from Changes open as a read-only diff; select Edit to modify the file in place. On workspaces created before in-place editing shipped, Changes opens a read-only diff with highlighted additions and deletions instead. Select Save or pressCmd/Ctrl + S to write the draft. Agent changes are folded into an open draft automatically; all-changes and completed turn diffs remain read-only review surfaces.
A file opened from Changes shows its changed hunks with surrounding context. Select a collapsed region to expand it in place, or Show full file to render the whole file; Show changes returns to the hunk view. The copy button next to close copies the file’s full contents.
Hover a code symbol to inspect its type and documentation. Cmd/Ctrl-click opens its definition, including definitions in another file; add Shift to list references. Replicas uses the repository’s language server when available and falls back to workspace symbol search.
When the workspace has changes or is on a non-default branch and has no pull request yet, the workspace header shows Create PR with the total additions and deletions; select it to ask the agent to open one. Once a pull request exists, the same spot shows its status. On mobile, a bar above the composer shows the repository, branch, and totals with Review and Create PR.
To comment on a range, drag across line numbers or select the first line and Shift-click the last, then use + to attach the selected range and code to your next message. In split view, keep the selection on one side of the diff. Without a range selected, + attaches a single-line comment.
Files attached to chat and files the agent places in ~/.replicas/canvas/ appear in Canvas. Images, video, audio, PDFs, Markdown, Mermaid, HTML, and common text formats have inline viewers.
Click an image attached to a user message to inspect it at full size.
On the web, select text anywhere in the conversation and click Add to chat, or press Cmd/Ctrl + L, to annotate it in your next message, or Ask in side chat to ask about it in a side chat. After Add to chat, type an optional comment for that annotation. Until you send, each annotation has a number beside its text in the conversation: hover it or its text to highlight the text, or click either to edit or remove the annotation. Select the annotations chip in the composer to see them all: click one to edit it, or its trash icon to remove it. The agent refers to them as Annotation 1, Annotation 2, and so on; click one of those, or one in the annotations chip above your sent message, to jump back to the text.
On the web and mobile, select, drag and drop, or paste up to 20 images of 20 MB each into a new task or existing chat. JPG, PNG, WebP, GIF, HEIC, and HEIF are supported. Large images are shrunk to the size the agent can read (2576 px on the long edge) before sending, so nothing the agent would see is lost.
Desktop tab
Every workspace includes a Linux desktop with Chrome. Open Desktop in the sidebar to watch the screen, then select Interact to control it inline with mouse, keyboard, scrolling, and audio, or Fullscreen to control it in an expanded view. The desktop shares text with your clipboard:Cmd/Ctrl + V pastes what you copied on your computer, and Cmd/Ctrl + C or X on the desktop copies back to your computer. On a Mac, Cmd works as the desktop’s Ctrl for all shortcuts.
While you interact with the desktop, select Annotate in the viewer header to comment on the screen. The picture freezes and your clicks place markers instead of reaching the desktop: click an element or drag over an area, and add an optional comment to each numbered marker. Select Annotate again or Cancel to go back to controlling the desktop. Add to chat attaches the screenshot with its markers and adds each marker as an annotation to your next message. A marker on a page in the desktop’s Chrome also names the element, its page URL and selector, and the React components that render it, so the agent can find the code.
While the sidebar is open, the desktop connects in the background at a low frame rate, so Desktop shows the live screen as soon as you open it. In Chromium-based browsers, it skips this on slow connections or when data saver is on. When you switch to another browser tab, the desktop drops to that low frame rate and disconnects after a minute, so coming back within a minute shows the live screen right away.
Desktop remains available for the selected workspace during sleep and wake, including provisioning, and stays selected if you were viewing it. The panel shows Workspace is sleeping while asleep and Workspace is waking up… during provisioning. The live view reconnects automatically once the desktop is ready.
The desktop and its processes continue running when you close the viewer. They also survive sleep on the default pause mode. Only authenticated Replicas users can open its viewer URL.
The desktop follows your dashboard theme, so switching between light and dark also switches its wallpaper, top bar, dock, and windows. Chrome switches with the desktop while its tabs remain open; other applications may need to be relaunched.
The stream settings menu in the viewer header chooses the transport (WebRTC by default, with automatic WebSocket fallback), a Balanced or Text quality profile, adaptive or pinned quality, and how the 1920×1080 picture is shown: fitted to the panel, at native size (one source pixel per CSS pixel), or at device pixels. Show diagnostics overlay displays the live transport and route, negotiated codec profile, source, decoded, CSS and device dimensions, displayed and decoded frame rates, bitrate, latency, loss, server load, and the latest server and viewer events, such as a WebSocket fallback and its reason or a quality change and the signals behind it. Open stream telemetry opens the same snapshot as JSON with the last five minutes of one-second samples and events. Settings are stored in your browser and also apply when you open the viewer in a new tab. Existing transport preferences are preserved; you can select WebSocket manually.
WebRTC prefers a direct connection to your workspace. When your network blocks one, it relays through a TURN server over UDP, TCP, or TLS on port 443 before falling back to WebSocket.
Stream telemetry also keeps the latest 50 automatic WebRTC fallback snapshots under webrtcFailures, including the failure reason, connection states, and received and decoded video counters. These snapshots remain available after viewers disconnect, until the stream server restarts.
Use the CLI computer commands when an agent needs to capture screenshots, interact with the browser, or record the screen.
Terminal and Docker
Open Terminal in the sidebar to run an interactive shell. Each workspace has one terminal session. Typed characters appear as you type and are confirmed when the shell echoes them; full-screen programs and hidden prompts, like passwords, wait for the workspace. Docker is installed but starts on demand. To make it available during every workspace setup, add this command to a start hook:replicas.yaml
Resource usage
Open Workspace info → Resources to see the workspace’s current CPU, memory, and disk usage. Values refresh every few seconds while the panel is open and turn amber at 80% and red at 90%.Engine updates
A workspace installs new engine releases each time it sleeps. To update sooner, open Workspace info → Engine and select Update. The engine restarts for a few seconds. Chats and files are kept, and messages sent meanwhile wait until it’s back. If the new engine doesn’t start, the workspace goes back to its previous one. Finish or stop the current turn first. Workspaces too old to update in place say so here; start a new workspace to get the latest engine.Chats and collaboration
- Create multiple chats to separate workstreams. Each chat keeps its own agent, model, effort, and history.
- New chats start with your resolved personal or organization defaults, then retain their selected agent and model across follow-ups and workspace wakeups until you change them.
- Switch chats from the tabs beside the workspace name. A new chat is named from its first message. Double-click a tab to rename it, or hover it and click ✕ to delete it. Restore a deleted chat from + → Deleted chats. Deleting an active chat stops its turn.
- Long chats open at the newest messages. On the web, scrolling up starts fetching older history ahead of your position, with more loaded as you approach the end of the cached messages.
- Live tool calls appear in an expanded, scrollable Working for … section. It follows new activity until you scroll up. When the assistant replies, it collapses into Worked for …; select it to inspect the activity.
- Completed turns show their total elapsed time below the response.
- On the web, LaTeX math in chat renders as equations, written with
$…$,\(…\),$$…$$, or\[…\]. A display equation appears once it is complete while the reply streams. - On the web, an unconfirmed send times out after 60 seconds, keeping your draft and unlocking the composer. Check the conversation before retrying; the message may already have arrived.
- Share workspaces with teammates to add them to the teammate’s Shared view. Organization members already have access; opening the link automatically switches to the organization that owns it.
- Recent activity on Home lists workspaces strictly by last interaction: messages sent and agent turns completed. Opening or waking a workspace does not reorder it. Each row shows the creator, contributors, and the state of any linked pull request. Rows group under Today, Yesterday, Last week, and Older, and pinned workspaces list above in their own section. Each date group initially shows five workspaces, with Show more revealing the rest. The activity list scrolls independently while the composer and selectors remain fixed. Select a heading to collapse or expand that group.
- Home visibility is independent of sidebar Owner selections: with Workspace Visibility disabled, it lists only workspaces you own; when enabled, it also lists shared and team workspaces. Ownerless API workspaces and automation workspaces, including personal ones, stay out of Home unless Workspace Visibility is enabled and they are shared with you.
- Use split view on desktop to compare multiple workspaces side by side.
- The workspace header shows linked pull requests and their checks. Eligible reviewers can approve, and standalone mergeable pull requests can be merged from the checks popover even while the workspace is sleeping. Merging uses the GitHub integration directly and does not wake the workspace.
- Use
Cmd/Ctrl+Kto search pages, environments, automations, and workspaces. See Keyboard shortcuts for prompt controls and the full in-app reference. - Hover over What’s New in the sidebar for weekly highlights, or select it to read the full weekly changelog. The online count sits beside search.
- Returning users see unseen weekly updates automatically. Closing an update dismisses it for your account in that browser until a new weekly update is published. New users skip the current update after onboarding and can still open it manually.
Switch credentials
Open Workspace info → Coding Agents → Switch beside Codex or Claude, choose a connected personal or organization credential, then select Switch credential. Stop that agent’s running chats and clear its queue first. The change applies to all of that agent’s chats in this workspace, preserves their conversations, and survives sleep and wake. Configured fallbacks still apply if the selected credential fails. Existing Codex workspaces support switching authentication methods, including OAuth to Microsoft Foundry. Switching accounts with the same method, and switching Claude credentials, require a newer workspace engine.Edit a message
On the web, hover a message you sent and click the pencil. Its text and images move to the prompt box; change them and send. The agent continues from just before that message, and the message and everything after it are hidden from the chat. Click Cancel to put back what you were typing.- Stop the agent first: editing is only available while the chat is idle.
- Files and git state are not rolled back, so they keep any changes made after that message.
- Claude Code and Codex continue from their own session. Other harnesses start a new session with the conversation before the edited message.
- Attached files are not copied; attach them again before sending.
- Only workspaces whose engine supports it show the pencil.
Keyboard shortcuts
While the prompt input is focused, pressShift+Tab to toggle Plan mode. Press Cmd+Option+/ to open the harness and model picker, or Option+Tab to switch to the next model. On Linux, use Ctrl+Alt+/ and Alt+L. On Windows, use Shift+Alt+/ and Alt+L.
Press Cmd+Option+↑/↓ to switch workspaces in the sidebar, or Cmd+Option+Shift+↓ to jump to the next one that needs you. On Linux, use Alt+↑/↓ and Alt+Shift+↓. On Windows, use Alt+↑/↓ and Ctrl+Alt+Shift+↓.
In the desktop app, press Cmd/Ctrl + F in a chat to find text in the conversation. Enter jumps to older matches, Shift+Enter to newer ones, and Escape closes the search. On the web, Cmd/Ctrl + F uses your browser’s built-in search.
Press Cmd/Ctrl + Shift + S in a workspace you own to share it. This also copies the workspace link. Type a teammate’s name and press Enter to share with the top match.
Press Cmd/Ctrl + / to open the full keyboard shortcut reference.
Voice input
Select the microphone in the Home or workspace composer, or pressCmd/Ctrl + Shift + Space, to record a prompt. While you talk, the composer shows elapsed time and a waveform. Select stop or press the shortcut again, and the text appears a moment later after anything already in the composer, including what you typed while recording, for you to review before sending. Replicas sends the recording to OpenAI to transcribe it.
Your browser asks for microphone access the first time. If you blocked it, allow the microphone for Replicas in your browser’s site settings. For the desktop app, see Desktop app.
Chat commands
Type@ in a workspace’s web chat to fuzzy-search repository filenames and paths. Files changed in the workspace are listed first and marked with a dot. Use the arrow keys and Enter or Tab, or click a result, to insert its path into your prompt. Press Escape to dismiss the list. Inserted files appear as compact pills showing the file name, while the agent receives the full path. Deleting a pill removes the whole path. Search also works while the workspace is provisioning or asleep, using its saved file list or the connected repositories’ default branches until a live index is available. Awake workspaces also reuse the cached list and refresh it in the background.
Type / in the composer to see commands supported by the selected agent. The menu also opens on a / typed after existing text, and closes once you type a space. Picking a command replaces only the / word you are typing, leaving the rest of your draft untouched.
In web and desktop, use the Up and Down arrow keys to navigate commands and skills, then press Enter or Tab to select one. The menu scrolls to keep the highlighted item visible.
/planasks the agent to propose a plan before editing. See Plan mode./fastenables a faster service tier where supported. See Fast mode./compactcompacts the active Claude Code, Codex, or Muse session./goal <objective>sets a goal the agent keeps working toward in a Claude Code or Codex chat.
Repository targeting
Every workspace uses one environment. The environment provides its repositories, variables, files, skills, MCP servers, system prompt, and setup hooks. Values from the environments it builds on are merged into it. Before creating a task from Home, the starting point control sets the branch each repository starts on. A single-repository environment opens its branch list directly; otherwise every repository is listed so you can choose a branch for each. Repositories without an override use their configured default branch.Sleep and wake
Workspaces sleep after 30 minutes without activity. Sending a message wakes a sleeping workspace automatically and resumes its previous branch and agent session. Sending a message also restores an archived workspace. Background integration events and API reads leave archived workspaces paused. Closing a workspace’s linked PR or issue doesn’t archive it while any chat is still running.
Selecting a sleeping workspace from Home starts waking it before navigation, so startup is already in progress when the workspace opens.
Sleeping workspaces with no activity for seven days are archived. Archived workspaces are deleted 3 days after they’re archived, or sooner if they’ve had no activity for 7 days, so a workspace archived after a week asleep is deleted about 30 minutes later. Waking a sleeping workspace, restoring an archived workspace, or sending a message resets its activity window; viewing an archived workspace does not. See Data retention for organization controls.
You can force sleep, archive, restore, or permanently delete a workspace from its sidebar actions menu. These actions are also available in bulk-selection mode.