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 sent while an agent is busy are queued in order. You can edit or remove a queued message before it starts. Supported agents also let you steer an active turn with a queued message. 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. 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, and Side chat once the workspace has something to show there. Opening a Canvas file or media item switches the sidebar to it. 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. 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.
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 to quote 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 to send under the quote, so each quote carries its own reply. Select the selections chip in the composer to review or remove quotes before sending.
On the web, select, drag and drop, or paste up to five images of 20 MB each into a new task or existing chat. JPG, PNG, WebP, GIF, HEIC, and HEIF are supported; Replicas converts HEIC and HEIF photos to JPEG before sending.
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. 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. 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, 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 underwebrtcFailures, 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%.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 menu beside the workspace name. Hover a chat there to rename or delete it, or restore one 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, 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 and automation workspaces stay out of Home.
- 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.Keyboard shortcuts
While the prompt input is focused, pressShift+Tab to toggle Plan mode. Use Cmd+Shift+Option+H, Cmd+Shift+Option+M, or Cmd+Shift+Option+E to cycle the harness, model, or effort. On Windows and Linux, use Ctrl+Shift+Alt+H, Ctrl+Shift+Alt+M, or Ctrl+Shift+Alt+E instead.
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 + / to open the full keyboard shortcut reference.
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
A workspace can use one repository or a repository set. Repository sets save combinations of repositories for tasks that span services. Every workspace uses one environment. The environment provides its repositories, variables, files, skills, MCP servers, system prompt, and setup hooks. Values from the organization-wide Global environment 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 one hour 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.
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 with no activity for 30 days are deleted. 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.
Troubleshooting
Workspace under heavy load
The workspace is using enough CPU or memory to delay its engine. Check Resources to see which, then wait for the active build or analysis to finish, or open a terminal and stop a stuck process. The banner clears when resource use falls.Engine temporarily unavailable
Reload after a few seconds. The workspace state on disk is unaffected by a transient engine health-check failure. If the workspace remains unavailable, select Try again when offered or contact founders@replicas.dev.Setup or wake failed
Wakes retry transient failures on their own, and a wake interrupted by a Replicas server restart resumes within a few minutes, so this appears only once those retries fail. Select Try again to repeat the wake. A workspace whose setup failed or was interrupted can’t be recovered; create a new one. Repository authentication and setup-command failures remain visible in the workspace so you can correct the underlying configuration.Billing
Usage accrues while a workspace is awake. Sleeping and archived workspaces use no minutes.- Manual work: Developer covers one individual for a fixed monthly price. On Team, new seats start as Flex and pay per minute, while Full seats pay a fixed monthly price.
- API and automations: usage is billed separately to the organization and does not consume a seat’s manual allowance.