Quickstart

Circle runs in your terminal and works on the files in a folder you choose. To use it you need a model endpoint: a base URL and an API key for a service or gateway that speaks the OpenAI or Anthropic API.

1. Install

Circle runs on macOS, Linux and Windows 10 or newer, on x64 and arm64. A release carries its own Node.js, so nothing else needs to be installed first. The Windows build has not yet been tried in a real console; read the Windows entries in Known issues first.

On macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/circle-platforms/circle/main/install.sh | bash

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/circle-platforms/circle/main/install.ps1 | iex

The installer downloads the release for your system, checks it, puts circle on your PATH, and adds that folder to your shell’s startup file if needed. Open a new terminal afterwards. To pin a version, set CIRCLE_VERSION, for example CIRCLE_VERSION=1.0.0. If it stops with a certificate error, or you want to install from source, see Installation and updates.

Verify:

circle --version

To upgrade later, run circle update; to remove Circle again, run circle uninstall (add --purge to delete the data folder too).

2. Start Circle

Change to the folder you want Circle to work in, then start it:

cd /path/to/project
circle

The first time, Circle walks you through two steps. Both are asked in the input box at the bottom of the session screen, under the welcome block, so the screen you answer them on is the one you then work in.

Connect a model. Paste the API base URL and the key (it shows as dots). Circle asks the endpoint for its models and lists them: type to search, and press enter on the one you want. If it cannot list the endpoint’s models, it asks whether the API is OpenAI-style or Anthropic-style, and you type the model id your provider documents. See Choose a model.

Trust the folder. Circle asks before it works in a folder for the first time, and says what the folder can supply: instructions, skills, commands and extensions, and that extensions run code. Trusting records the folder in your settings; nothing is written into the folder. Choose trust this folder (or press y).

After that, circle goes straight to the session.

3. Give Circle a task

Circle shows each file read, search, command and edit it performs. Before it runs a command or changes a file, it asks you. A card replaces the input box and shows what Circle wants to do:

● Bash needs your permission
  $ pytest tests/test_quicksort.py -q

1 Allow once
2 Allow this exact command for this session
3 Allow "pytest …" for this session
4 Reject and explain

Press 1 to allow it once, 2 to stop being asked for the same command in this session, 3 to stop being asked for every pytest command, or 4 to reject and tell Circle what to do instead. esc rejects. See Security for exactly what is checked and what is not.

Try a task that matches your work:

Explain how this repository is structured and how to run its checks.

Add type hints to quicksort.py and write pytest tests for it.

Find where the config file is read and tell me which settings can be overridden.

Press esc to stop a turn. You can type while Circle is working: enter gives the message to the model after its current step, and ctrl+q keeps it for when the turn ends. See Steer a running turn.

4. Continue

Everything you type is kept in your prompt history: press ↑ in an empty prompt to bring back earlier messages, or ctrl+r to search.

Inside a session, /new starts a fresh conversation, /export writes the transcript to a Markdown file, and /exit (or ctrl+d on an empty box) leaves. Circle keeps each conversation in its data folder: circle -c goes on with the last one in this folder, and /resume lists the others. See Sessions.

To use Circle from a script, run one prompt with circle -p "…"; the answer is printed. See CLI.

Where to go next