A coding agent for your own model endpoint, in the terminal and in its own window.
Docs · Quickstart · Known issues · Changelog · 中文
Circle reads and edits the code in a folder you choose, and runs commands there. It works with any service or gateway that speaks the OpenAI or Anthropic API. It asks before it runs a command or changes a file, and the screen shows at a glance whether it is working or waiting for you. The same agent runs in the terminal and in the desktop application.
Circle is early software. There is no operating-system sandbox. Read Known issues and Run Circle safely before you point it at anything you care about.
Install a prebuilt release. It carries its own Node.js; nothing else needs to be installed first.
macOS and Linux (x64 or arm64):
curl -fsSL https://raw.githubusercontent.com/circle-platforms/circle/main/install.sh | bashWindows (x64 or arm64), in PowerShell:
irm https://raw.githubusercontent.com/circle-platforms/circle/main/install.ps1 | iexThe installers download the latest release for your platform, verify its SHA-256, start it once, and put circle on your PATH. macOS and Linux need bash, curl, tar, and sha256sum or shasum. Windows needs PowerShell 5.1 or newer.
Restart your terminal after installing, then run circle. Upgrade with circle update; remove an installation with circle uninstall (--purge deletes the data folder too). See Installation and updates and Releases.
Each release also has Circle as a desktop application: the same agent in its own window, with a browser you and Circle use together. The desktop application says what the window shows. It carries everything it needs and does not use the circle command. It keeps its settings, key and sessions in its own data folder, apart from ~/.circle.
| System | File |
|---|---|
| macOS, Apple silicon | circle-desktop-<version>-darwin-arm64.dmg |
| macOS, Intel | circle-desktop-<version>-darwin-x64.dmg |
| Windows x64 | circle-desktop-<version>-windows-x64.msi |
| Linux x64 | circle-desktop-<version>-linux-x64.tar.gz |
Take the file from Releases. It is signed ad hoc, not by Apple or Microsoft, so the first launch asks you to confirm. The Windows installer puts Circle in C:\Program Files\Circle and on the Start menu. On Linux the sandbox helper needs one root command. The steps are in Installation.
On macOS and Windows the application updates itself: settings → about & updates → check now, then update and restart. On Linux the same check replaces a folder it can write. Circle 1.6.0 and the published 1.7.4 do not have that updater: one manual update, in Installation, is what installs it. Releases up to 1.2.0 do not update themselves on any system.
The window follows the system language the first time, and can be English or 简体中文. The terminal stays English. To run it from a checkout, see apps/desktop.
Does your organization sign its own certificates? Put the CA's PEM file somewhere readable and list it under trust_cert_files in ~/.circle/settings.json. Start circle with no environment variables: it adds those authorities to the ones it trusts, and the commands and tools it starts get one merged bundle through SSL_CERT_FILE, the system store included. See Settings and Security.
cd ~/code/my-project
circleThe first time, Circle asks for a base URL, a key and a model, then asks you to trust the folder. After that, type a task and press enter. Type / to see the commands and ? to see the keys.
circle "fix the failing test" # start with a message
circle -c # go on with the last conversation here
circle -r # pick a conversation from a list
circle -p "summarize README.md" # one prompt, answer on stdout
git diff | circle -p "review this change"While Circle works you can keep typing: enter steers the running turn. esc twice goes back to an earlier point of the conversation, ctrl+l switches models and ctrl+f finds text. The CLI also has a JSON event stream and an RPC mode for scripts and editors.
The terminal interface uses conversation cards, status lamps and an auto theme that follows terminal colours. Use /themes dark or /themes light when your terminal cannot report its colours. See The interface for the signals and limits.
Ask Circle to open a page, such as a device's web interface on your network, and it uses the browser as you would. It reads the page, moves a pointer to click and type, and answers the page's dialogs. It passes a certificate warning only after you approve, and it tells you about downloads, files a page asks for and sign-ins. In the terminal the browser is a Chrome, Edge or Chromium window with a new, empty profile; in the desktop application it is a browser panel you share with Circle and can take over. Control is approved site by site, and some things are always yours to decide: giving a page files, camera or location permissions, and which client certificate identifies you.
Ask Circle to reach a device you administer — a switch, a router, a server's console — and it opens an SSH or Telnet terminal and works it the way you would in SecureCRT: it reads what the device answers and types what you approve, approved device by device, with host keys you trust and passwords kept only as %NAME% secrets. In the terminal interface the device screen is a page you can attach to and type on yourself; in the desktop application it is a terminal panel you share. /terminals lists the open consoles and your saved sessions. See Device terminals.
Save a password with /secrets NAME, or under settings → variables & secrets in the desktop application. The model writes %NAME% wherever the password is needed, in a browser field or in any other tool, and never sees the value: Circle puts it in when the tool runs and hides it again in what comes back. /variables NAME=value keeps plain values the same way. See The browser and Secrets by name.
| Quickstart | Install, connect a model, run a first task. |
| The interface | What the lamps, tints and frame mean. |
| Run Circle safely | What is asked, what is refused, what is not protected. |
| Choose a model | Endpoints, switching, thinking depth. |
| The browser | Web pages Circle and you use together. |
| Device terminals | SSH and Telnet consoles Circle and you work together. |
| Skills, Commands, MCP, Extensions | Make Circle yours. |
| The desktop application | The same agent in its own window. |
| All documentation | Guides and reference. |
Circle is written in TypeScript and runs on Node.js 24 or newer.
git clone https://github.com/circle-platforms/circle
cd circle
npm ci
npm run check # type check, tests, build
CIRCLE_HOME=$(mktemp -d) npm run dev -- ~/code/my-projectCode pushes do not publish a new version: the release workflow publishes when a v* tag is pushed. See Releasing.
See CONTRIBUTING.md, AGENTS.md for coding agents, and the architecture. Report security problems as described in SECURITY.md. Everyone taking part follows the Code of Conduct.
circle-hub is the team hub a Circle connects to as an MCP server. The compatibility matrix says what each expects of the other.
Circle is released under the Apache License 2.0. The NOTICE file names the copyright holder and reserves the Circle and Circle Hub names, logos and icons: the license covers the code and its documentation, not the marks. The architecture and design specifications listed in docs/design/README.md are under CC BY 4.0 and must be credited, with a link to the original, when reused. Versions up to 1.2.1 were released under the MIT License. The model catalogs in src/data/ carry metadata from models.dev, and many prompts in src/prompts/ come from OpenCode, each under its own MIT license; see THIRD_PARTY_NOTICES.md. Contributions are accepted under the contributor terms.