The desktop application

The desktop application is a window around the same Circle: the same model connection, tools, approvals, sessions and modes as the terminal. Installation says how to get it. This page says what its window shows and how to use it.

First start

The first time, Circle opens the connection form by itself. Later, open it from the connection at the bottom of the sidebar (connect a model until one is set; see When the runtime stops for runtime stopped), from settings or with /login. It asks what the terminal’s setup asks, in two steps:

The provider, editable API URL and key. Online providers request their model list; selecting a provider without a compatible list chooses its released presets before any request. Custom endpoints keep protocol discovery. Nothing is saved yet.
The model. Preset providers show their ids marked preset, under a line with the date of the preset list; they remain unverified and can be edited. Providers that require deployment names ask you to type yours. When the endpoint listed its models, pick one from the list (arrow keys and enter work in its search box); type to search it, and use “…” takes an id it does not list. When it listed none, or could not be asked, type the model id your provider documents; it is not checked. If the endpoint could not be asked, choose whether the API is OpenAI-style or Anthropic-style too. Connect saves the URL that answered (the one you typed when none did), the kind of API, the model and the key, and lists that endpoint’s models in place of the ones listed before.

The key field can stay empty only while the URL stays on the host (and port) of the saved endpoint: then the saved key is kept, so the path or the model can change alone. For another host the key is required, and the saved one is never sent there. Back returns to the first step; the key you typed is kept in the form until it closes.

Settings → models & connection lists what the saved endpoint offered when it was connected or last refreshed, with the models in use, and the default model and thinking depth of a new session. Refresh models asks it again; an endpoint that does not list its models, such as an Anthropic-style path without GET /v1/models, gets a note saying so, and its model ids are typed in the search and used from there.

The window

The layout follows Claude’s:

The sidebar: a new session and all sessions; then recent, the newest sessions from every folder and from no project. A session row, in recent or under its folder, shows the title. Two rows with the same title also show the start of the first reply, or the short id when that reply is shared too. Hovering or focusing it shows the folder, when it has one, how long since the last message, and that time in full, in a card to the right of the row. Five show before the rest. Order follows the last message: opening or renaming a session does not move it. Up and down move between session rows. Tab moves on to the next folder header, which folds that group. A row’s menu is not a tab stop, and right arrow or Shift+F10 reaches it. The menu’s own tip and the session card do not show together. Focusing that button, including while the pointer is still on the row, replaces the card with the tip. Changing page, or pointing at the page, closes the card so it does not stay over the next view. Hovering another row dismisses a focused tip so only one popup is open. Scrolling the list closes a popup. Sending a message keeps the row that was at the top of the list there when there is room to scroll; otherwise the list stays at its end. When the list is already at the top, the newest session stays in view. Then your folders, in name order, and their sessions, with action menus for each; and at the bottom the connection, then search, settings and hide sidebar as icons at the right end, each named by its tip. Hide sidebar folds the whole sidebar away, as the sidebar button at the left of the top bar and ⌘B do; that button brings it back. New session opens the home composer. It does not create a session. Work with no project lives in a task folder of its own: recent and search hold it as well, and after your folders it lists under no project, one group per task. See Tasks with no project. Tasks a conversation starts fold under its row, in recent and under its folder, as 2 tasks: a click lists them, each with a dot for its state, and a click on one opens its conversation. The list is open while one of its tasks is the open session. A task’s reviewer is not a row of its own; a request waiting in it marks the task. Task conversations are not recent rows, and a task’s isolated copy of the project is not a folder group. Circle makes, starts and retries tasks; the sidebar only shows them.
The top bar: the session’s title, whose menu has rename, details, find, the session tree, fork, clone, compact, export and share; the folder and its git branch; and on the right the overview button, a divider, and the modes of the work drawer: files, changes, browser, subagents and terminal, each an icon whose name shows when the pointer rests on it. The theme is in settings, and help in the application’s help menu. The subagents button carries the number of subagents at work, and the terminal button the number of background commands that run. A click on a mode opens it beside the overview, a second click, or esc in the drawer, closes it. A mode has no title bar of its own: what it offers, such as full view and, for the browser and the terminal, open in a window, is on its own toolbar. full view gives the mode the width of the whole workspace, while the conversation keeps its own part below it, and the sidebar still lets you pick another session. Click it again, or press esc anywhere in the window, and the split returns with the record as you left it, scrolled where you had scrolled and typed what you had typed. Only the changes, the terminal, the browser, a file that is open and a subagent that is open offer it.
The conversation: your messages on the right, Circle’s answers as plain text. The tool calls of each model step fold into one line, such as ran 2 commands, edited calc.py +1 −1; a later step in the same turn gets its own line, not one summary for the whole turn. A click opens them, each with its output and, for a file change, its diff. A screenshot Circle took stays with the call that took it: the folded line says 2 pictures, and opening the calls brings them out, each a small picture; a click opens one, to copy or to keep. Thinking folds to one line too; when thinking is shown, a thinking-only step stays between its tool lines. The time, the usage and a copy button show under a message when the pointer is on it. The plan no longer sits above the input box, nor the context ring and the lines for the work that runs around it: they are in the overview. Above the box stay the bar that counts the requests waiting for you, and, when there are any, the messages you queued and inputs to recover.

The app starts in a folder of its own, workspace inside its data folder, which it trusts, or in the default workspace you chose in settings. Open your own project with file → open folder, and trust it before Circle reads it or runs anything in it.

The overview

The overview is a column of cards, 380 pixels wide, pinned to the right of the conversation. It only shows; what a row leads to is a click away. A card with nothing in it is not drawn, except environment and context, which are always there.

environment: this machine, the folder, and its branch.
context: how full the model’s window is after the last answer, as a percentage and a meter, orange from 70% and red from 90%. Opening the card shows the same fill in tokens, used of the model’s window, such as 14.1k / 128.0k; the session’s cost, estimated from the model’s published prices; the share read from the cache; and the instruction files the folder gave Circle, each one a click that opens it in the files mode. Unknown values read N/A.
in progress: the plan step under way, or the next one, while the plan has steps left, the subagents at work with what Circle sent each to do and what each is doing (a click opens it in the subagents mode), and the tasks that are not finished (a click opens the task’s conversation). A row keeps a subagent’s name whole and some of what it was sent to do; what it is doing is cut short when the card has no room for it, and shows whole when the pointer rests on it. A subagent that waits for you says so with an orange dot, needs approval when it asked to run a command or a tool, and the command or tool shows when the pointer rests on its row.
outputs: the files this session changed, each marked M for changed, A for new and D for deleted; a click opens the file’s difference in the changes mode.
needs your review: operations an interrupted run left half done, such as a save or a terminal restart, each with mark as checked once you wrote what you found, and copy diagnostic. It is drawn only when there is one.
changes: the lines added and removed since the last commit, with create pr when the branch has work and no open pull request, or update pr when it has one: either asks Circle to do it, in the conversation, with the built-in create-pr skill, which runs the GitHub CLI (gh) installed on your machine. Below, the repository’s pull requests with their checks (passing, running, failing); a row’s ⋮ menu has open pr, copy link and, for a failing run, copy failed ci logs: the last 32 KB of each failed job’s log, of ten jobs at most, with anything that looks like a GitHub token hidden; while other jobs of the run still run, it copies the jobs that already failed. The window reads pull requests with the gh it ships, signed in as your own gh is: with the sign-in for github.com that gh auth login saved on this computer. Without one the card shows the changes, and neither pull requests nor its button; a GitHub Enterprise login or another account beside it does not count. When GitHub does not answer, as when the computer is offline, the card keeps the pull requests it last read for the branch. The window never merges a pull request.

The overview and the drawer’s mode sit side by side, with the conversation keeping at least 420 pixels. A mode opens at the width it was last left at, and its left edge is dragged, or moved with the arrow keys, to change it; each mode keeps its own width. When the conversation, the overview and the mode do not all fit, the mode wins: the overview steps aside, and comes back by itself when there is room again. An overview you closed yourself stays closed. In a narrow window, 1050 pixels or less, the overview and each mode lie over the conversation, one at a time: a file or a mode opened from the overview takes its place. A file or a subagent opened there also takes the sidebar’s room when it needs it, and gives it back when it closes.

Knowledge, memory and workflows

The Circle section of the sidebar opens knowledge, memory and workflows. Knowledge browses personal folders, sources and statements, with search and verification filters. Select an item for its original sources and recent version history. Narrow windows open details as a page with back to list. Personal edits, moves, deletion and conflict resolution first show the proposed change and require confirmation. Imported text files keep their original bytes; existing memory files and skills are never imported automatically.

Memory separates my memory, team memory and shared with me. Team and shared content are read-only. Loaded labels describe the actual frozen session content; refresh session memory adopts current eligible preferences when the session is idle. Merely viewing shared memory does not load it into the model. /knowledge and structured /memory commands open these pages; file-memory commands keep their existing behavior.

Workflows lists personal workflows and generic skills. Import selects a compatible folder containing pack.json and adds its manifest. Install files… separately checks and installs matching local files on this device. Only intact, enabled installations are available to the model. Hooks are not imported, and arbitrary standalone skill folders are not converted automatically.

Sync settings selects an existing MCP connection and shows the mode, last successful sync, conflicts and connection/login status. Before switching to only on this device, the confirmation shows the actual personal content size, folder shares that become unavailable, pending team shares (or unknown) and independent team copies that remain. Local copies remain. Share to team… creates an independent copy only after confirmation; it is disabled in local-only mode with a tooltip and change sync mode entry. The switch is explicit and never happens temporarily for a share. Local pages work without a selected connection.

Organizing sessions

The ⋯ beside a folder opens the home composer with that folder selected, reveals the folder in Finder or the system file manager, collapses the sidebar groups, or archives all its sessions. The + beside a folder does the same as new session, with that folder already chosen. A session’s ⋯ pins, renames, archives, restores or deletes it. Rename in the sidebar edits the row in place, and F2 does the same for the open session, with the whole title selected: enter or leaving the field saves, escape cancels. Renaming does not move the row. Deleting still asks for confirmation and preserves the workspace folder.

New session, in the sidebar, on a folder, on the sessions page, or from the file menu, always opens the home composer: the question, the message box, and a project menu. The menu lists every folder Circle knows, including the default circle workspace, marks the selected one, and can open a folder or choose no project. Two folders that answer to one name say which folder each sits in beside it, and a folder already on the list keeps its single row and its own place in it when it is opened again. The same words, open folder, are in this menu and on the folder dialog. With nothing else chosen, the menu keeps the project of the conversation you were just in when that project is trusted. An untrusted project is not the default; the menu uses the first trusted project instead. The + beside a folder selects that folder, including circle. Choosing no project does not file the session under circle or any other project. Nothing is saved until the first message is sent. Opening a folder only selects that project: it does not write a session. Until then, the draft and the project, model and thinking depth chosen with it stay, including after opening another session and coming back with new session. Searching the project menu says when nothing matches, and open folder and no project stay in the menu. Those menus, and the mode, model and thinking depth menus, open downward. If the chosen project is not trusted yet, confirming trust sends the waiting message. The box under the question has the same attach, approval mode, model and thinking depth controls as a session. That message creates one session, using those choices, in the folder the menu shows, and the session then appears in recent and, when it has a folder, under that folder. Opening the app when the current conversation has no messages shows this same home. A session with no messages and no title of its own stays out of the sidebar, the session list, search and resume. A folder stays out of the sidebar too, until the first message creates its session or the home composer is drafting a new one in it: while a draft aims a folder, that folder shows on the bar, its name beside an open-folder icon, shaded as the current one. The project menu still lists every folder. Search finds sessions, files, pages and past messages, including Circle’s replies, and says when nothing matches.

After the first turn the model names the session with a short summary of its first message, the same request as the terminal’s. Until that title arrives the row says new session, and the trimmed message is not used as the title. A short line such as hi is its own title. A refused or failed request leaves the row as new session and says title failed in the conversation. A network failure says could not reach the endpoint, and that request is tried once more. A title that only repeats the question is asked for once more and otherwise leaves the session untitled. A name you give a session is kept. Opening an older session asks again when the stored title is still the short first message, a cut of it, several messages stuck together, or a title that reads as work already done.

Ctrl+N (⌘N on macOS) and new session take the keyboard from a sidebar row and put the cursor in the home composer before the next key, so the next keys are the message; they go after a draft the home composer kept. Search is Ctrl+K (⌘K). Ctrl+R (⌃R on macOS) opens the same search; that is the history-search key, kept on purpose.

Settings open as a dialog over the window you were in, from the settings icon at the bottom of the sidebar, ⌘, (Ctrl+, on Windows and Linux) or the application menu. The groups are listed at the left under five headings and the chosen one shows at the right; the search box narrows the list, and enter opens the first match. Many choices apply as you make them; other controls have their own save step, and protected-file patterns take effect after a restart. A click outside the dialog, esc or × closes it and returns to the view behind it; esc in the search box only empties it, and a dialog opened from a page, such as a server’s configuration, closes alone. In a narrow window the list becomes a row above the group.

General: appearance (theme, text size, language, terminal screen reader), sessions (what a double Esc does, whether thinking is hidden in new sessions), shortcuts, help (the built-in commands, which run in view of the conversation unless one opens another group) and about & updates.
Models: models & connection, with the connection, the models the endpoint offers, the model and thinking depth for this session, and the defaults for new ones.
Capabilities: skills, commands, MCP servers, extensions, tools and hooks. A kind of thing decides where it goes: a skill is text loaded into a conversation, an MCP server is a separate program Circle connects to, and an extension is code that runs inside Circle and adds tools, commands and checks, so GitHub is an extension, found under extensions → interface components, and its details open inside the dialog. The sidebar shows no GitHub connection status; when a task needs GitHub (a pull request, CI checks or logs) and the connection is off or not ready, the model is told to say where to set it up, in one line, and carry on with local git.
Workspace & git: workspace (the default workspace, tasks with no project, workspace trust and the number of parallel tasks) and git, with the switch that credits Circle in the commits and pull requests it makes.
Permissions & safety: approvals, file access (external files and protected files), variables & secrets and, once the runtime has reported it, network.

Each group has its own address, /page/<group> (/page/settings is the first), and a slash command opens the group it names: /themes appearance, /variables and /secrets variables & secrets, /hooks hooks, /models and /effort models, /skill skills, /mcp, /extensions and /approvals their own.

Settings → workspace → workspace trust lists the folders, each with its trust, green when trusted and red when not, review and remove…. Removing one archives its conversations and takes away its trust in one step, so it leaves the sidebar; it deletes no file, and the history stays under all sessions → archived sessions. A folder with no conversation leaves the list with it, and so does a removed one: a folder Circle neither trusts nor works in, and whose conversations are all archived, has nothing left on this page to trust or remove. Its archived history stays under all sessions, and the notice says which happened. When a conversation there cannot be archived yet, for example while it waits on an approval, the remove changes nothing: the folder keeps its trust, the dialog stays open and the error says why. The folder Circle is working in cannot be removed. Review on another folder trusts that folder, not the one in use.

Archiving hides a session from the sidebar. All sessions → archived sessions shows it again; its history stays readable, and restore conversation enables the composer. Until restored, it cannot change the saved branch, labels or conversation mode. A fork or clone can start a separate conversation from it. Archive state is kept in desktop metadata, without deleting the folder or changing the terminal’s checkpoint history.

Conversations in the same folder can run together. Creating or switching a conversation leaves the others running; each keeps its draft, attachments, scrolling, folded messages, queue and approvals. Stop affects the selected conversation only. Background requests stay with the session that asked them.

A running turn, pending request or running background job prevents archiving, including after switching to another conversation. The menu names that reason while archive is unavailable. Archive all checks every session first and changes none when one is busy. A session with a shell open in a terminal tab or a task running can be archived: archiving asks first, closes those terminal tabs and stops those tasks once you confirm, and stops nothing when another session keeps the archive from happening. Removing a folder from workspace trust says so in its own dialog, and does the same. Archive state survives restarting the application. Deleting a running conversation asks you to stop it and its tasks, waits for cleanup, and then removes its history. Deleting the selected conversation selects the most recent available conversation in that folder; when it was the last one, the app returns to that folders home, awaiting a new first message. A folder its home is drafting in stays on the bar and wears the highlight until that message creates the session, which then carries it. Workspace files stay.

Selecting a conversation owned by another Circle terminal opens its committed history read-only. Execution and deletion stay locked until that terminal releases it; export the saved history or fork a complete checkpoint to work independently. Conversations in the same folder still share its real files.

Asking and answering

When Circle wants to change a file or run a command, the request appears in the conversation, right under the call it is for: the command, or the change as a diff with line numbers. Answer it there:

Answer	What it does
allow once	Runs this call.
allow for this session	Runs this call, and in this session does not ask again for the same thing: the same command, or file changes inside the workspace. For the browser it reads *allow on site* for this session** and covers that site.
allow “…” commands	For a command: allows commands starting with the same words, in this session.
reject	Does not run it; the model is told.
reject and explain	Does not run it, and tells the model what to do instead.

A question from the model appears the same way, with its choices and a box for your own answer. While a request waits, the frame around the input box is orange and still, and the bar above the box says how many wait; click it to scroll to the first.

A command that answers with one line — an unknown /name, /undo, /share — says it as a toast for a few seconds, and it also stays as a line of the conversation that asked, in its place in the transcript. A missed toast is not a lost answer. Asked in one conversation and answered while the window shows another, the line goes to the conversation that asked; the one on screen keeps its peace. A line an extension appends joins the conversation the same way, straight from the runtime.

Modes

The button under the input box, on the left, shows how this session asks. Click it to choose, or press shift+tab in the input box to move to the next one.

Mode	What it does
manual	Asks before each file change and command. The default.
accept edits	Changes files inside the workspace without asking. Commands, deletes and changes outside the workspace still ask.
plan	Read-only: Circle researches and writes its plan, and changes nothing else. The plan opens where a file opens. When it is ready a card asks what next: implement it in auto mode or with manual approval, change it, or save it only.
auto	Runs every call without asking, including the ones Circle always asks about. Read Security first.

The mode belongs to the session, as in the terminal; see Modes.

In plan mode Circle writes its plan to a file of the conversation’s own in the data folder, not in your project, and never asks to. When it writes it, the plan opens where a file opens, as a document that follows what Circle writes; closed while Circle works, it stays closed until the card asks about it. That card, at the end of the conversation, asks what next: implement in auto mode or implement with manual approval end plan mode; change the plan asks what should change and sends it to Circle, which revises the plan and asks again; save the plan only keeps plan mode on and changes nothing. open plan on the card shows the plan again; in a narrow window the plan waits for it.

While Circle works

The input box is one line and grows as you type more. Its frame takes the approval mode’s colour: blue to accept edits, violet to plan, orange for auto; in manual mode it keeps its plain border. While the model works, the row of the turn’s latest tools shows how long the turn has run and, once a model request has finished, the tokens the endpoint reported for it, as Claude’s desktop application does; before the first tool a row of its own shows them beside Circle’s turning ring. Time spent waiting for you is not counted. When a model request is tried again the row says why and which try. When the turn ends, its last answer shows the whole turn: the time, the tokens sent and received, and the cost when every request had a price in dollars. Turns finished before Circle started again show only the last request’s tokens.

A finished file change shows its diff when its line is opened. The changes mode lists every file this session changed while the app was open, each against its version before the first change, or everything that differs from the last commit. The files mode lists the open folder when it is trusted.

When the runtime stops

Conversations run in a separate process, the Circle runtime. When it ends without being asked to, as when it crashes or runs out of memory, the turn under way stops and a notice says why and gives the process’s exit code, such as Circle runtime crashed (4294930435 (0xFFFF7003)) · restarting…. The saved connection stays: the sidebar says runtime restarting… rather than connect a model. About 31 seconds later, once the stopped process’s sessions are free (a session lease expires 30 seconds after its holder’s last heartbeat), Circle starts the runtime again by itself and reopens the same session, idle. The turn that was cut off ends with ✖ Interrupted, after its last saved message or tool result, and the next message goes to the same endpoint with that history. Text the model was still streaming is not kept.

Circle restarts the runtime by itself once. If it stops again within ten minutes, it stays stopped: the sidebar says runtime stopped · restart, and a click on it starts it again. While it is stopped the connection dialog says so and offers restart runtime instead of a form that cannot save.

On macOS Circle also ends the runtime itself when it stops carrying out file operations. The runtime does its file reads and writes, DNS lookups and some cryptography on a pool of four threads, and macOS has been seen to stop waking that pool for good (see known issues); every such operation then waits for ever, while the window keeps saying Circle is still working on workspace-service · 39s, the seconds counting up to the two-minute timeout. The runtime keeps one cheap file operation in flight and checks it every ten seconds; when it is unanswered at 30 seconds and still at the next check, Circle ends the process and starts it again as after a crash, and the notice reads Circle runtime stopped handling files · restarting….

Each unexpected exit is written to logs/runtime.log in the data folder (runtime.log.1 keeps the previous megabyte): the exit code and what it means when Circle knows, how long the runtime ran, whether it restarted, and the last 16 KB the runtime wrote to its error output, with values that look like keys or tokens replaced by [redacted]. When V8 ran out of heap, that output says JavaScript heap out of memory and the notice says the runtime ran out of memory. On Windows a crash without a crash handler reports 4294930435 (0xFFFF7003): Chromium’s crash reporter was asked for a dump and none was connected, so the code does not say what failed; the log’s error output may. A stalled thread pool is logged as runtime thread pool stalled, with how long the file operation went unanswered and how many operations of each kind were waiting. A command the runtime does not answer within two minutes is logged with its name and, for a workspace call, its service and method, such as workspace-service git.changes, never its parameters.

When the runtime is slow

A command that has gone unanswered for four seconds says so in the conversation that asked it: a line at its end, or under the composer on the new-session page, reads Circle is still working on custom-command · 9s. The line grows as the wait does and goes when the runtime answers. Commands still run one at a time, in the order they were asked, so a command asked meanwhile waits behind the held one.

A command the runtime never answers fails after two minutes. That failure stays in the conversation as a card, not as a toast that passes: Circle did not answer in 120s · prompt, the runtime’s own words folded under error details, and copy error details and dismiss. A timeout is not proof that nothing happened, and the command may still run, so the card offers no retry and says to check before sending it again. A slash command that failed outright has retry, which sends it again by name.

A title is a side request, not a reason to wait: it gets ten seconds, is not sent again when its own clock stopped it, and closing a session waits for it for at most three seconds.

The runtime’s standard output is kept in a 64 KB ring and written to logs/runtime.log with the last of its error output when a command times out, so a wait that ends in a failure can be read afterwards. It is not shown in the window.

Files, changes and subagents

The desktop application edits, runs and reviews a trusted project while the agent keeps working; you do not need to stop a turn to open or save a file, or to switch sessions.

Files

The files mode lists every file of the open folder, with a filter box in its toolbar to find one by name. The files, changes and subagents modes share one layout, so the eye keeps its place between them: a toolbar row 44 pixels high where a mode has one, the background of a row starting 8 pixels in from the drawer’s edge and what is in it 16 pixels in. A file Git says differs from the last commit has its name coloured, orange for changed and blue for new, and the letter M or A at the end of its row; a folder with such a file somewhere under it carries a small dot. A file that was deleted is not in the tree: the changes mode lists it. Files are drawn with one grey icon each, whatever their type. A file outside the folder is not in the tree: giving the conversation access to one existing text file there is under settings → file access → manage external file access; see Known issues.

A click on a file widens the drawer to 760 pixels and opens it as the file itself, on the left, with the tree on the right; where the window has no room for that beside the conversation, the sidebar folds, and comes back when the file closes. The heading has full view, and the × that closes the file, so that the drawer is the tree again. In a drawer too narrow for both, the file has the room and the tree comes back when the file closes. A file opens in a code editor with syntax highlighting, as the file itself and not as its difference. Beside its line numbers the editor marks where the file on disk differs from the last commit: an orange bar for a line that changed, a blue bar for a line that is new, and a small red triangle on the line after the place where lines were deleted. The marks move with the text as you edit and are read again when the file is saved or changes on disk; text you have typed and not saved has no mark of its own yet. A save carries the version you started from: when the agent or another program changed the file meanwhile, your text stays and the version on disk is shown to compare. On Windows, when another program holds the file at that moment, the save waits up to two seconds for it to let go. ctrl+s saves. A Markdown file has a reading view that shows the editor’s current text, unsaved changes included.

Changes

The changes mode is one list of files, each with a letter, M for changed, A for new, D for deleted, and its added and removed lines. The control at the top chooses which: this session, the files Circle’s file tools changed while the application ran, each against its version before the first change, together with the uncommitted files the overview’s changes card lists, or all uncommitted, everything that differs from the last commit in the folder’s repository, staged or not and including new files, read from Git whoever made the change. The choice stays while you use other modes; a file sent here from the overview’s outputs shows in the list that has it. A click on a file shows its difference under the list; open file opens it in the files mode, except a deleted one. The list does not author anything: committing, pushing and opening a pull request are create pr in the overview, or the terminal, and the window stages nothing.

Subagents

The subagents mode lists the conversation’s subagents, those at work and those finished, each with its name, what Circle sent it to do, and, for one that runs in the background, how long it has run, which the finished list keeps. A click opens its own conversation beside the list, widening the drawer to 760 pixels; the sidebar folds if the window needs the room, and comes back when the subagent is closed. The heading names it and says what it was sent to do, with stop for a subagent running in the background, full view and ×. A request a subagent asks, such as a command to approve, is a card in the main conversation with the subagent’s name on it, and the list marks the subagent as waiting.

Tasks

Circle splits work into tasks that run in parallel, and makes, starts and retries them itself; the window shows them, under their conversation in the sidebar and in the overview. A task that writes gets its own Git worktree on a branch of its own. Up to eight agents run at once by default, two builds and one task that drives the screen; settings change these limits. The limit belongs to the application, so parallel tasks reads and saves it without opening a folder’s task ledger: it answers even while another Circle holds one. When the saved limit cannot be read, tasks run one at a time and parallel tasks in settings says so; saving a value there repairs it, and the tasks already queued in the folder of the conversation wait until start queued tasks there starts them. A task whose checks cannot decide needs your review, and the card for it sits at the end of the task’s own conversation, with what really ran under it: each acceptance criterion is ticked with what you checked and what you saw, and confirm reviewed criteria works once every one is filled in. send back takes a reason instead: the task runs again as a new attempt, a fresh worktree from the same commit, with your reason added after its instruction and acceptance criteria, and kept for every later attempt. The attempt you sent back keeps its worktree and results, and tasks waiting for this one keep waiting. N files changed on the card opens what the task changed in the changes mode.

Known issues lists what these do not do yet.

The browser

Each conversation has its own sandboxed browser, which you and Circle use together: what one does, the other sees. Open the browser mode from the top bar and enter an HTTP or HTTPS address, or ask Circle to use it. The page fills the mode and it works like Chrome; see Using the browser. The model’s browser tools open pages, read them, click, type, choose options, press keys, take screenshots, answer a page’s dialogs, manage tabs and give pages files, and can record what they did as a script and replay one, which you watch in the browser as it runs. While Circle’s turn is using the browser, the page is ringed in blue, and a click on the page during an action, or take over, a button at the end of the address bar that shows only then, gives you the browser once that action ends; continue on the card in the conversation, or a message to Circle, returns it, and in auto mode it comes back by itself once you stop. See Taking turns. Downloads go to the system’s Downloads folder and are listed under the page, with show in folder; one that Circle’s action started from a site not yet allowed shows waiting for approval until you answer the card in the conversation (keep, allow downloads from site for this session or discard); when a click of Circle’s opens a file chooser, choose… under the page lets you pick the files instead of Circle. A site that asks for a user name and password gets a sign-in over the page, which you or Circle can answer; a page that asks for the camera, your location, notifications and the like asks under the page, with allow and block, and only you answer; a site that asks for a client certificate lists yours in the page’s place, and only you choose one, or send none. In auto mode both are refused without asking, and the model is told. They can reach local devices and private addresses as well as public sites. They are available to the main agent only.

Before Circle acts on a page, an approval card shows the site and the URL, element or text involved. Allow on site for this session covers all browser actions on that site in that conversation, and another site asks again; reading the page and taking a screenshot do not ask. In plan mode those two reads work, and the other browser tools are refused. When Circle starts using the browser the mode opens and rings the page in blue, and in orange while a browser action waits for your approval. The ring stays lit from that first browser tool until the turn ends, you take the browser, or the session stops (Circle is operating, or Waiting for your approval while an approval card is open, on the ring’s tooltip and for assistive technology), unless you are on another page of the application, the browser is in a window of its own, or the window is narrow (1050 pixels or less), where the mode would cover the conversation and its requests; open it from the top bar there. full view at the end of the address bar takes the page across the whole workspace; the page is a real browser view, so it is resized with the mode, which is what a wide device web interface needs. In the page, a pointer moves to what Circle clicks, with a ripple, and a field it types into is outlined, with a label saying what it does and naming the element as the page does. The pointer fades after a few seconds and stays out of snapshots and screenshots.

A page’s alert, confirm, prompt or “leave site?” question appears over its tab, on a picture of the page as it stopped, with the site it came from; a tab waiting on one is marked. While Circle is working it appears in the conversation too. You can answer it in either place, or Circle can; the first answer counts, and Circle is told who gave it. No dialog appears over the whole window.

A site whose certificate is not trusted, such as a device with a self-signed certificate, gets the browser’s privacy warning in its tab, as in Chrome: Your connection is not private, the error code, Advanced and Back to safety. Advanced shows the certificate (who it is issued to and by, its validity and its SHA-256 fingerprint) and Proceed to … (unsafe). You can click it yourself. Circle sees the same page and can click it too, but then asks you first in the conversation, except in auto mode; for a host on this network you can also trust that certificate there for good. The address bar says certificate error while the warning shows and not secure after you proceed. See Built-in tools for how long each choice lasts. A link or script that opens a new window opens a new tab. Other loading failures show cannot reach this site in the browser.

Password values never appear in snapshots; a password field shows only whether it is filled. The model cannot type plain text into one: it writes %NAME% for a secret you saved, and never sees the value; with none saved it asks you for one. You can still type it yourself in the browser. See Secrets by name. Pages can still send whatever you or Circle enter to their server: read the approval card and the address before allowing an action. Contents of frames from another site cannot be read.

The warning page and the pointer follow the application’s theme.

Using the browser

By default the browser shows the toolbar and the page, and nothing else. Who has the browser is the ring around the page. It lights on the turn’s first browser tool and stays lit until the turn ends, you take the browser, or the session stops: a blue ring while Circle is using it (Circle is operating), an orange ring while a browser action waits for your approval (Waiting for your approval), and the blue ring while Circle is still stopping after you take over (Waiting for Circle to stop…). While you have the browser the border is the ordinary one and says you have the browser. The words are the ring’s tooltip and its accessible name, not a line of their own. The mark on a click still flashes for that action only. Everything else is in the ⋮ menu or on the keys below, as in Chrome.

Tabs. The row of tabs shows only when there is more than one tab; with one, the page has the whole mode and new tab in the ⋮ menu, or ⌘T, makes a second. Each tab shows the page’s icon (a spinner while it loads, a globe when the page names none), its title cut short with the whole title as the tooltip, and a close button. A middle-click also closes a tab, and + opens a new one with the keyboard in the address bar. Closing the last tab leaves a new, empty one. A link or script that opens a new window opens a new tab. The icon is read only when the page names one in its <link rel="icon">; Circle does not ask a site for /favicon.ico by itself.
Toolbar. Back, forward, and reload, which turns into stop (×) while a page loads. The address bar shows the address without http:// or https://, the host in the text colour, with a lock for HTTPS, not secure for HTTP or after you passed a certificate warning, and certificate error while the warning shows. A click selects the whole address; Enter opens what you typed (a bare host gets https://), Esc puts the page’s address back and leaves the field. While the page is not at 100%, a magnifier in the address bar shows the zoom and opens the zoom controls.
⋮ menu. new tab, zoom (−, the current level, which resets to 100% when clicked, and +), find…, take page screenshot, developer tools and close tab. take page screenshot puts a picture of the page into the message box as an attachment, named for the site and the time, such as app.example.test 12:04.png; send it with your message or remove it as any attachment. The pictures Circle takes are in the conversation, under its tool line, as small pictures: a click opens one large, with copy image, save to file and ×. While a menu of the window is open, the page shows as a still picture under it, because the live page would cover it; it comes back when the menu closes.
Find in page. The find bar opens over the end of the address bar, so the page keeps its size. It shows the current match and how many there are (2/3); Enter and shift+Enter step through the matches, the arrows do the same, and Esc or × closes it and keeps the found text selected.
Zoom. Each step is one of Chrome’s levels (… 90%, 100%, 110%, 125% …). As in Chrome, the level applies to the site, so other tabs of the same site follow it. Ctrl and the mouse wheel zoom too. Circle is told when you change the zoom and takes a new screenshot before it clicks by coordinates.
Right-click. The page’s menu is Chrome’s: on a link Open link in new tab (behind the current tab) and Copy link address; on an image Open image in new tab, Copy image and Copy image address; on selected text Copy; in a field Undo, Redo, Cut, Copy, Paste and Select all; elsewhere Back, Forward and Reload; and Inspect at the end, which opens the developer tools in their own window. Choosing it again, or the shortcut, closes them. It follows the application’s language. Links and images you open this way are your actions, not Circle’s, and need no approval.
Developer tools. developer tools in the ⋮ menu, Inspect at the end of the page’s menu, and F12, ctrl+shift+I (Windows and Linux) or ⌥⌘I (macOS) open Chromium’s own developer tools, and the same control closes them. They open in their own window, so the page does not get shorter. The shortcuts work while the keyboard is in the address bar or anywhere else in the browser, as well as in the page, and only then. While they are open, Circle’s browser tools wait: Chromium is using the page’s debugger. Circle attaches it again when the tools close, and needs a fresh look at the page.

While Circle acts, keys pressed in the page and its right-click menu are left to Circle’s action; take over first.

These keys work while the page or anything in the browser has the keyboard, and only then (⌘ on macOS, Ctrl on Windows and Linux):

Key	Does
⌘L	the address bar
⌘T, ⌘W	new tab, close tab
⌘R, F5	reload
⌘[ and ⌘], alt+← and alt+→ (Windows, Linux)	back and forward
ctrl+tab, ctrl+shift+tab	next and previous tab
⌘F	find in page
⌘= (or ⌘+), ⌘-, ⌘0	zoom in, zoom out, 100%
⌥⌘I (macOS), ctrl+shift+I (Windows, Linux), F12	open or close the developer tools
Esc	stop a page that is loading

While the browser has the keyboard, ⌘W closes the tab rather than the window, and the zoom keys zoom the page rather than the window.

The terminal

The terminal mode holds this conversation’s terminals in one row of tabs: shells of yours, commands Circle runs in the background, and the device terminals, the SSH and Telnet consoles Circle reaches on your network the way you would with SecureCRT. Each tab has its name, a × that closes it, and a dot when there is something to say: blue while a command or a device connection works, red when it failed, a ring when a command has ended; a shell at rest has none. The row scrolls when there are more tabs than room, and keeps the one in front in view. A tab stands where it came to be, so a shell you open after a device console sits after it, not in front; drag a tab onto another to set the order, and every window, a reload and a visit home keep it. A long name is cut short with the whole of it in the tooltip. Right-clicking a tab offers rename… (for a shell), close, close others, close all and new terminal. A shell you rename shows its name instead of its number, keeps it through a restart, and Circle’s terminal tools and approval cards call it by that name too. Dragging a tab onto another moves it there: past that tab when it comes from the left, before it otherwise. The order is kept for the conversation in every window, a terminal in a window of its own included, and after a reload, until Circle quits. With no conversation open, on home, the terminal mode says that terminals belong to a conversation.

The + at the end of the tabs opens a menu: new local terminal, in the folder of the conversation; connect to a device, the saved profiles from terminal-sessions.json, one click each; and connect new device…, a quick connect by address (SSH or Telnet, the address and port, and for SSH a user name and a password; a Telnet console asks for its own login on its screen) that reaches a device without saving it. A console you connect, by address or from a saved profile, is yours to type in from its first line; Circle’s actions on it wait until you give it back. The password signs in once: it is kept in memory only until that login has used it, also while you answer the device’s key, and it is never saved or shown to the model. A first SSH login to a device asks you to trust its key, on a card above the screen (below); the answer that gets through puts that console in front of you at once, its banner typing itself in a moment later, and an answer that cannot do its work says why and keeps the card where you can answer again. At the end of the row stand what the tab in front can be told to do, only when there is something to press, and terminal menu (⋮), open in a window and full view.

A shell is a real terminal in the folder, named terminal 1, terminal 2 and so on. A service takes a number too, so a shell’s number can skip one. A tab keeps the number it was given while it stays open, so closing another tab does not rename it. A new shell takes the lowest number no open tab is using. Restarting one in place keeps that tab’s number: the exited process leaves the row, and the shell that replaces it is still that tab. When the shell has exited, the tab’s dot is red and the screen says this terminal has exited, with press enter to restart and restart; Enter in the tab restarts it too. Circle can work in it too, as below: its dot and the ring round its screen are orange while Circle asks you about it and blue while Circle works in it. × stops it and takes its tab out of the row. The ⋮ menu has find in terminal, add selection to chat (the selected text becomes a quote in your message), copy complete output, restart terminal, interrupt command and start service, a long-running command that has its own tab with its command, the port it listens on and whether it is ready.
A command Circle runs in the background gets a tab of its own while it runs, named by the command and ringed in blue, with stop at the end of the row; it has no × until it ends, then the tab stays for you to read and close. The terminal button in the top bar carries the number of such commands.
A device console is painted by a real terminal emulator: what the device paints, you see, colours and cursor included, and it fits itself to the mode. You and Circle take turns on it, as with the browser. While Circle works, take over at the end of the row hands the keys to you: what you type goes straight to the device, Circle’s next action on it waits, and the model learns only that you typed, never what. give back returns it. When the model wants you to log in or answer a prompt it cannot, it hands the console over itself and says so; give it back when you are done. × asks once, then disconnects the device, also while you hold it: an action of Circle’s waiting for the console ends, and the model is told that you disconnected it. The ⋮ menu has refresh the screen. When Circle opens a console, the terminal mode opens on it, once for that console, unless you are on another page of the application, the terminal is in a window of its own, or the window is narrow; what Circle then does on the same console leaves the drawer on the mode you chose.

Before Circle types on a device, an approval card names it; allow for this session on it covers connecting, sending, pressing keys and disconnecting there, and another device asks again. A line with a word that can wipe the device asks every time, rule aside. The first SSH login to a device shows a card with the key’s type and SHA-256 fingerprint: connect once, or trust for good for a device on this network (kept in terminal-host-keys.json, in the application’s data folder); a device answering later with a different key is asked about again. A device password is never typed plain: it comes from a saved secret by %NAME%, or from the password you type into a quick connect, and the model never sees its value. See Device terminals.

Circle in your terminal tabs

The model’s terminal_* tools also reach the shells you open as terminal tabs in the desktop terminal drawer. Each shell still in the tab row is listed by terminal_sessions beside the device consoles, as local:<id> and under the name of its tab: terminal 1, terminal 2…, or the name you gave it. A tab keeps its number while it stays open. A new shell takes the lowest number free among the open tabs. Restarting a shell keeps its number. A shell whose process has exited stays listed: the line says the shell is gone, and that sending to it restarts it and then types. Do not ask for a new terminal, and do not use execute. Background commands Circle runs in a terminal of their own, services, and tabs you have closed are never listed, and another conversation’s tabs are not reachable. The model reads a tab’s screen and scrollback, waits on it, types and presses keys in it, and can hand it to you with terminal_handoff. It does not open a tab, and it cannot close one: terminal_disconnect refuses.

Reading a tab asks nothing, in every mode. The first time the model would type in a tab in a conversation, you are asked, in every mode including auto, whatever an allowed_commands pattern, a rule or a hook’s allow says. The card is the card a command gets: the line that would run, and the same answers, so allow for this session is there when that command could have it. A rejection types nothing, and the next try asks again. Once you allowed one, a line the model runs in the tab is judged as execute would judge the same command: text sent with enter or with a line break, and Enter or Ctrl-D pressed at the prompt, go by the mode, the approval rules, which the tab shares with execute (allow for this session on either covers both), and the hooks that match terminal_send or terminal_press. Plan mode and read-only refuse every write to a tab before anything reaches it. Text without Enter and the other keys ask nothing once the tab is in use. Text for a tab carries no control characters or tabs; keys go through terminal_press. If the line at the prompt changed between the card and the answer, because you typed in it, nothing is typed and the model is told to read it and send again. The line is judged with the values of the secrets it names, as execute judges a command, and the card shows their names. A line Circle had to read off the screen without knowing where its prompt ends asks every time, in every mode, and offers no rule to keep (see Known issues).

The tab stays yours. Typing in it while Circle is reading, waiting on or typing in it takes it over: Circle’s read or wait on it ends at once and says that you have it, its typing there is refused, and the model learns that you typed, never what. Typing in it while Circle is not using it only tells the model that you typed. Until you hand the tab back Circle’s typing there stays refused. Stopping Circle’s action on a tab ends that action with an error the model reads, without taking the tab. When the shell exits while Circle is waiting on it, that wait fails and says so; the tab stays, listed as exited, until you close it. Closing the tab takes it out of the row and out of the list, and frees its number. Sending to an exited tab restarts it and then types. In the window, a shell Circle asks you about has an orange dot on its tab, an orange ring round its screen and a card in the conversation headed by the tab and why it asks. The first time it would type, the card says it will type that command into the tab, such as terminal 1 · types this command into your terminal, with the line that would run; when that shell has already exited, the card says it will restart the terminal and type the command. A later line is headed as that command would be, such as terminal 1 · runs a shell command. Listing a tab and reading its screen ask nothing, and neither does waiting. While Circle works in a shell — including a wait for a command that prints nothing, such as sleep, which stays until the prompt returns — the dot and the ring are blue, and take over and stop stand at the end of the row: take over is the same as typing in the shell, and stop ends what Circle is doing there without taking it. While you hold a shell, give back stands there instead, and a shell Circle handed to you says why above its screen. give back returns the shell to Circle: the dot and the ring turn blue again, and the conversation says you gave that terminal back. When your typing had cut a wait short, Circle goes on and waits for the command to finish. An execute card, when your latest message asked for your own terminal tab and a tab is open, offers run this in terminal N: the card’s command is typed into that tab and run there, with the values of the secrets the card shows by name, and Circle is told that it went there, not to its own shell. It is typed only when the line that runs is the card’s: the shell is at its prompt, nothing is on its line, neither text Circle typed without Enter nor a line you started, and Circle is not typing in the tab. Otherwise nothing is typed, the card stays and says why. On Windows, where Circle cannot see whether a command holds the tab, the line at the cursor has to end like a prompt.

In a window of its own

The browser and the terminal can leave the drawer. open in a window on the mode’s toolbar makes a window of its own for that mode of that conversation, titled for the mode and the session, such as browser · Fix the reconnect race. The mode’s button in the top bar then carries a blue dot and is not shown as the open drawer, and pressing it brings the window to the front instead of opening the drawer. The browser’s page moves with its window. On macOS and Windows it stays loaded as it was; on Linux it opens again in the window it moves to, with its history, so a form it held and where it was scrolled are lost (see Known issues). The terminal shows the same shells and consoles. put back in the drawer, at the end of the window’s toolbar, closes the window, and so does closing it by hand: the mode is in the drawer again and its button is shown as open. Showing another conversation closes the windows of the one you left, and closing the main window closes them all. A window holds one mode: a second press on the same mode never makes a second window, and a press while its window is still closing opens a new one.

The message box stays in the main window. take page screenshot in the browser’s window and add selection to chat in the terminal’s put their attachment into that conversation’s message box there, and the window says so in a notice. An address an extension opens for the conversation opens in the browser’s window, which comes to the front. Browser shortcuts such as ⌘W, ⌘R and ⌘L (Ctrl on Windows and Linux) act on the page only in the window that shows it, while its toolbar or its page has the keyboard; typed in the main window, they do what they do there. ⌘W closes the active browser tab, including immediately after opening another one. A window shows its notices on its toolbar and follows the theme, the text size and, with the theme on auto, the system’s light or dark. A conversation’s title too long for a window’s title is cut short and ends in an ellipsis.

Under the input box

As in Claude: on the left, + to attach files and the mode; on the right, the model and the thinking depth, each a menu. Nothing else sits under the box. The context, the plan and the work that runs are in the overview, and compacting the conversation and the session’s details are in the title’s menu.

Keys and text fields

Text fields keep the system’s editing keys. On macOS ⌘C, ⌘V, ⌘X, ⌘A, ⌘Z and ⇧⌘Z, ⌘ with an arrow, ⌥← and ⌥→, and ⌘⌫ do in the input box and every other field what they do in any Mac application; on Windows and Linux Ctrl with C, V, X, A and Z do the same.

Circle’s own keys in the input box are the terminal’s, listed in Keyboard and mouse. On macOS they are Control keys, as in the terminal: ⌃C clears the draft, ⌃D on an empty box asks to close the session, ⌃T shows or hides thinking, ⌃O expands tool details, ⌃G opens the larger editor, ⌃R opens search and ⌃Q queues a follow-up. ⌘ is left to the system, apart from the window’s own commands: ⌘K search, ⌘P quick open of a file, ⌘N new session, ⌘O open folder, ⌘, settings, ⌘B the sidebar, ⌘F find in the conversation and ⇧⌘M the model list. On Windows and Linux all of these are Ctrl.

Where the two meet, the field wins. With text selected in the input box, Ctrl+C copies instead of clearing, and so it does over text selected anywhere else, such as an answer in the conversation: the draft survives and the selection goes to the clipboard. Ctrl+Z in a text field is the field’s undo, not suspend. Ctrl+D over a draft deletes the character after the cursor, as in the terminal; only on an empty box does it ask to close. In any other text field, such as a rename box, a settings field, the editor or the terminal, Circle’s keys do nothing but esc. A terminal of the terminal mode, or a device console you hold, sends the keys typed into it to its shell or device: on Windows and Linux Ctrl+K, Ctrl+P and Ctrl+B there are the shell’s control keys and open neither search nor quick open, nor hide the sidebar. On macOS ⌘ is no terminal key, so ⌘K, ⌘P and ⌘B still work from a terminal.

A right-click in a text field offers Cut, Copy, Paste and Select All; on selected text, Copy. Elsewhere in the window there is no menu. The menu follows the application’s language. Settings → shortcuts gives an action another key; a key recorded with ⌘ on macOS stays a ⌘ key.

Outside the window

While the window is in the background, Circle sends a system notification when a request needs you and when a turn ends or fails. On macOS the Dock icon counts the requests that wait. On Windows and Linux the taskbar shows a busy bar while Circle works.

On Windows and Linux, closing the window keeps Circle running in the tray by the clock. The runtime goes on with its sessions. Click the tray icon to bring the window back, with the windows that were open beside it; right-click gives the menu, where Open Circle shows the window and Quit Circle ends the application and stops the runtime. The first close comes with a system hint saying where Circle went. On the first start a missing tray icon falls back to the old behaviour: closing ends the application, so no window is ever hidden with no way back. To keep the old behaviour anyway, start the app with CIRCLE_DESKTOP_TRAY=off. macOS is unchanged: the window closes, the application stays in the Dock, and clicking the Dock icon opens a window again.

The default workspace

When the folder of the last run cannot be resumed, the app starts in its default workspace. That is workspace inside its data folder at first; settings → workspace → default workspace → change… picks another folder through the system’s folder dialog, so it can live on another drive. The choice is saved as workspace_folder in the data folder’s settings.json; the app refuses its own data folder, a folder inside it and a folder containing it.

Changing the folder moves no files:

The new folder starts empty and, like any folder you open, needs trust before Circle reads it or runs anything in it.
The old folder keeps its files and its sessions; they stay listed and open while it exists. While the built-in workspace folder still holds files, settings names it, and you delete it by hand to reclaim the space.
Choosing the built-in workspace folder again resets the default.

Session history, the projects/ offload folders and updates stay in the data folder wherever the default workspace lives.

Tasks with no project

A task that belongs to no project gets a folder of its own, so its files and its history sit apart from your projects and one task can be deleted whole. Those folders live under the task folder: tasks inside the data folder at first; settings → workspace → tasks with no project → change… points it somewhere else, on another drive if you like. The choice is saved as task_folder in the data folder’s settings.json; the app refuses its own data folder, a folder inside it and a folder containing it.

Starting a new session while the app sits in its default workspace — nothing of yours opened — makes the task’s folder, trusts it as the app trusts its own scratch folder, and starts the session there. A new session inside a project you opened stays with that project. The sidebar lists these tasks under no project, after your folders, each with its own folder name (2026-10-15-1f2e3d).

The terminal reaches the same place with one flag: circle --task [name] works in <task folder>/<name>, making and trusting it. Without the flag it still works in the folder you started it in. See Arguments and options.

Circle keeps each task’s conversation in projects/ inside the data folder, as it does for any folder: deleting the task’s folder takes its files and leaves that record until you clear it too. See Known issues.

Variables

Settings → variables & secrets lists names and values as Windows lists environment variables, with new…, edit… and delete under each table; double-click a row to edit it. The model writes %NAME% in any tool’s arguments and Circle puts the value in when the tool runs. On Linux and macOS the shell’s own form is $NAME; Circle’s placeholder stays %NAME% on every system. The first table holds plain variables, whose values the model is told; they are variables in settings.json. The second holds secrets, whose values the model never sees and the page never shows again: to change one, enter a new value, or leave the value empty to keep it when you only rename it. In the dialog, secret decides which: it is ticked by itself for a name with a part such as PASSWORD, TOKEN or KEY, and ticking it while you edit a plain variable moves that variable to the secrets in one step. See Secrets by name.

Saved sign-ins

A sign-in the application keeps for you, such as the GitHub connection’s when you choose stay signed in on this computer, is saved as the terminal saves its keys: in a file in the data folder that only your user account can read (desktop.secrets.json), not encrypted and not in the system keychain, on every system. Versions before this one kept them encrypted with the system keychain; the first start moves them into the file once and removes the old folder. If one cannot be read, because the keychain refuses, say, the GitHub connection asks you to sign in again. See Saved sign-ins in the desktop application.

Protected files and network trust

Settings → file access → protected files adds file names that Circle’s file tools refuse or skip and that shell commands are denied for naming (Credential files). Commands that reach a file indirectly are not blocked by these name checks. Each pattern is a file name, not a path: * is any run of characters and ? is one character, so *.key is right and secrets/*.key would never match anything — the page says so when you type one. A pattern already on Circle’s own list is refused as unnecessary, and the list under always protected shows that list. Check a file name answers whether a name would be protected and by which pattern. Circle reads these when it starts, so a change takes effect after a restart.

Settings → network is the transport the connected runtime actually uses: how many authorities a server’s certificate is checked against, how many of them Circle added itself, which file or setting each group came from, whether requests go through a proxy (and which variable named it, without any key in its value), and, when there is one, the bundle given to everything Circle starts. Anything it could not use is named under it.

Keyboard

Settings → shortcuts lists the application’s actions, one row each, with the key that triggers them. change… on a row then a key press records another key: the row says press the new key while it waits, and esc gives up. A key another action already has is refused with that key is already used, so a recording cannot leave you without a way to stop a turn; recording an action’s own default key clears it back, and reset key does the same. Each row’s buttons name the action they belong to, so a screen reader says what would change.

These keys belong to the desktop application and are kept with its window. The terminal reads keybindings.json; a key you record here does not change that file. view shortcuts lists the keys as the application handles them.

Language and text size

Settings → appearance:

language: follow system, English or 简体中文. Following the system, any Chinese system language gives Chinese. Menus and notifications follow. Only the interface is translated: what the model writes, tool output, file names and commands stay as they are. GTK file dialogs (Cancel, Open, Recent, Home) are GTK’s own strings. Generating zh_CN.UTF-8 (locale -a) is not enough: gettext also needs the catalog gtk30.mo at /usr/share/locale/zh_CN/LC_MESSAGES/gtk30.mo or /usr/share/locale-langpack/zh_CN/LC_MESSAGES/gtk30.mo. On Ubuntu that file comes from language-pack-gnome-zh-hans (sudo apt-get install language-pack-gnome-zh-hans). Start Circle with LANG=zh_CN.UTF-8, LC_ALL=zh_CN.UTF-8 or LANGUAGE=zh_CN. When the window starts in Chinese and LANGUAGE is unset, Circle sets LANGUAGE=zh_CN before a dialog is shown. Choosing 简体中文 later, or Chromium’s --lang, does not install that catalog. Circle does not set LC_ALL. A test profile (CIRCLE_WORKBENCH_TEST_PROFILE) stays in English.
text size: small, default, large or larger. Interface and code text change together.

The choice of language and text size is kept by the window, not in settings.json.

The light theme is white, #FFFFFF, with the sidebar and the drawer on the same white and set apart by their borders, and the window’s text is the system’s own font: SF Pro on macOS, Segoe UI Variable on Windows 11 and Segoe UI before it, with PingFang or Microsoft YaHei for Chinese.

Updates

Settings → about & updates → check now asks GitHub for the newest release. When there is a newer one, update downloads this system’s package into the data folder and checks it: its checksum, on macOS its signature, and that it holds that version. Restart to update then quits Circle; a small installer puts the new copy where the old one was and starts it, and settings say which version it was updated to. Quitting is bounded, so the restart cannot stall: a runtime that does not stop within ten seconds is ended, and the macOS and Linux installers wait two minutes at most for the old copy to leave — a copy that still has not quit keeps its files, the download stays staged for another try, and the next start says the application did not quit. The sidebar offers a newer version as well, with how far the download is and the restart. Circle reaches GitHub through the system’s proxy settings.

With check for updates on (as in the terminal, update_check in settings.json), the packaged application also looks once a day when it starts. On macOS the new bundle replaces the old one in place. On Windows, the copy the .msi installed is updated with the new .msi, which asks for administrator permission as installing did; the installer waits until Circle and its helper processes have ended and starts it again afterwards. Installing, updating and removing Circle do not go through Windows’ Restart Manager, so the installer closes no other program; quit Circle before you remove it, or Windows removes the files it holds at the next restart. On Linux the same check downloads circle-desktop-<version>-linux-<arch>.tar.gz, checks its sha256 and the CIRCLE_VERSION file inside, and replaces the application folder when that folder and its parent can be written. Replacing it by hand is the procedure in Installation: quit Circle, delete the old Circle-linux-* folder, then unpack. The archive always creates that folder name, so unpacking beside it collides, and unpacking onto the old files mixes the copies and drops setuid. Replacing the folder drops the setuid bit on chrome-sandbox. Where that helper was setuid, the update does not start Circle again. Before it quits, the about page and a confirm dialog show the commands; the next launch shows them again, and so does the installer log:

sudo chown root:root <folder>/chrome-sandbox
sudo chmod 4755 <folder>/chrome-sandbox

Run those, then start Circle. Without them the new copy stops at once. When the folder cannot be written, check now opens the release page in the browser and says so, and the about page keeps the same steps. On Windows outside C:\Program Files\Circle, and wherever macOS runs Circle from a folder it may not write, check now opens the release page the same way. CIRCLE_DESKTOP_RELEASES points the check at another copy of the releases page (https, or a local address for tests). The switch labelled check for updates is the daily check. Check now asks immediately, including while a newer version is already listed.