Settings

Circle keeps its settings in settings.json inside the data folder (~/.circle unless you set CIRCLE_HOME). Setup creates it. You can edit it by hand.

Read Before you edit by hand first.

{
  "version": 1,
  "initialized": true,
  "auth": {
    "protocol": "openai",
    "base_url": "https://gateway.example/v1",
    "model": "my-model",
    "api_key_ref": "api_key"
  },
  "trusted_folders": ["/Users/me/code/my-project"],
  "theme": "auto",
  "mcp_servers": [],
  "knowledge_sync": { "server": "", "binding": "" },
  "extensions": {},
  "credential_files": [],
  "trust_cert_files": [],
  "update_check": true
}

Keys

Key	Type	Default	Meaning
version	number	1	Settings format. Not used yet.
initialized	boolean	false	Set by setup. /logout sets it back to false, and the next start shows setup.
auth.protocol	string	"openai"	openai or anthropic. It decides which client talks to the endpoint. Circle never guesses it from the model name.
auth.base_url	string	""	The endpoint. For OpenAI style, include /v1. For Anthropic style, give the gateway root; a /v1 at its end is left out.
auth.model	string	""	The model id sent to the endpoint, the default for new sessions. alt+d in /models sets it.
auth.api_key_ref	string	"api_key"	The name of the key in credentials.json.
default_thinking	string	""	The thinking depth to start with: minimal, low, medium, high, xhigh or max. Empty means the protocol’s default. CIRCLE_REASONING_EFFORT wins over it. alt+d in /effort sets it. See Models.
default_mode	string	""	The mode new sessions start in: manual, accept-edits, plan or auto. Empty means manual. alt+d in the default mode list of /settings sets it. A project cannot set it. Read Security before choosing auto.
enabled_models	list of strings	[]	The models ctrl+p switches between. Each entry is a model id or a pattern such as step-*, matched against what the endpoint lists. Empty means every listed model.
double_escape	string	"tree"	What esc twice on an empty input box opens: tree (the session tree), fork (the fork list) or none. /settings changes it.
editor_bridge	boolean	false	Four tools that read what your editor reports over the editor bridge: the file it has open, what you selected, and a diff you are asked to look at. /bridge start opens the listener; the tools only answer once it is open. A project cannot set this.
hide_thinking	boolean	false	Start sessions with the model’s thinking rows hidden. /thinking shows them for a session; /settings changes the default.
show_hook_allow	boolean	false	Show routine hook allow notices in the terminal and desktop. They are hidden by default; denials, questions and failures remain visible. /settings or Settings → hooks turns them on. A project cannot set this preference. See Hooks.
trusted_folders	list of strings	[]	Folders you have trusted. A trusted folder covers itself and the folders inside it: trusting /a trusts /a/b, and does not trust /ab or a folder next to it. Trusting a child does not trust its parent. --trust adds the folder you start in.
theme	string	"auto"	auto follows your terminal, including when it switches between dark and light while Circle runs. dark or light overrides it, for a terminal that cannot be asked or answers wrongly. An older terminal means auto. /themes sets it. See Dark and light terminals.
mcp_servers	list of objects	[]	MCP servers to connect. See MCP.
extensions	object	{}	{"name": {"enabled": false}} turns an extension off. See Extensions.
credential_files	list of strings	[]	More file name patterns the model may not touch, on top of Circle’s own list. Each is a name, not a path (*.key, never secrets/*.key). The desktop settings page edits this list and checks a name against it. See Security.
variables	object	{}	Named values, such as {"BASE_URL": "https://example.test"}, written as Windows writes environment variables: %BASE_URL% in a tool’s arguments takes the value when the tool runs. The model is told the names and the values. Names are capital letters, digits and _, from a letter; values up to 2,000 characters. Keep passwords as secrets instead. The desktop settings and /variables edit them.
trust_cert_files	list of strings	[]	PEM files whose certificate authorities Circle trusts on top of the default ones, for terminal and desktop model requests, probes and tools. Children get a merged bundle through SSL_CERT_FILE and NODE_EXTRA_CA_CERTS. ~/ is your home folder. Restart after changing this setting. CIRCLE_TRUST_CERTS adds files for one run, separated like PATH. See Security.
allowed_commands	list of strings	[]	Wildcard patterns (*, ?); a command runs without asking when every segment of it matches one. /approvals add <pattern> writes here; a project’s settings add to the list. Read Security first.
models	object	{}	Per model: {"glm-5.3": {"context_window": 1000000}} sets the context window the footer shows and the automatic compaction uses, in place of the one from models.dev. On the Anthropic protocol the answer limit is at most a quarter of it; Models says where compaction starts. CIRCLE_MODEL_CTX sets one window for every model. {"my-model": {"images": true}} says whether the model reads images, where models.dev does not know it or is wrong; see Images and screenshots.
vision	object	{"base_url": "", "model": "", "api_key_ref": "vision_key"}	A side vision model that describes pictures for a model that cannot read them: an OpenAI-compatible chat/completions base_url and model, with the key in credentials.json under api_key_ref. CIRCLE_VISION_BASE_URL, CIRCLE_VISION_MODEL and CIRCLE_VISION_KEY win over it, for one run; CIRCLE_VISION_TIMEOUT_MS sets how long a description may take. A project cannot set it. See Images and screenshots and Environment variables.
update_check	boolean	true	Once a day, when the full-screen interface starts, ask GitHub whether a newer release exists and say so in one line. false turns it off. See Updating.
attribution	object	{"enabled": true, "author": "auto"}	Whether commits and pull requests Circle makes credit Circle, and who is the commit author: user, circle or auto. "enabled": false turns it off. A project can set it. See Crediting Circle in commits.
task_folder	string	""	Where a task that belongs to no project gets a folder of its own; empty is the built-in tasks folder inside the data folder. Settings → workspace → tasks with no project in the desktop application sets it through the system’s folder dialog, and circle --task works there. A project cannot set it. See The desktop application.
workspace_folder	string	""	The desktop application’s default workspace folder; empty is the built-in workspace folder inside its data folder. Settings → workspace → default workspace in the desktop application sets it through the system’s folder dialog. The terminal ignores it, and a project cannot set it. See The desktop application.

Global models entries also accept input_limit and output_limit when an endpoint has separate limits, for example {"my-model": {"context_window": 128000, "input_limit": 32000, "output_limit": 4096}}. For an OpenAI-compatible gateway, output_parameter can explicitly select "max_tokens" or "max_completion_tokens" for requests that set an output cap. These fields do not belong in project settings.

Project settings

A project can set a few things for its folder in .circle/settings.json, as pi’s .pi/settings.json does:

{
  "model": "step-5-preview",
  "default_thinking": "high",
  "credential_files": ["*.key"],
  "allowed_commands": ["make *"]
}

Only these keys are read: model, default_thinking, enabled_models, double_escape, hide_thinking, theme, credential_files, allowed_commands and attribution. They apply while Circle works in that folder, once it is trusted (sessions, -p, line mode and RPC mode), and are never written to your settings.json. --model on the command line wins over the project’s model. credential_files and allowed_commands are added to yours, so a project can protect more files and allow more of its own commands, but never narrow either list. The endpoint, the key, MCP servers, extensions, trusted folders, default_mode, workspace_folder, editor_bridge and show_hook_allow cannot be set by a project; a key Circle does not take is named in red at start (on standard error without the full-screen interface).

Hooks are not a key here. They live in hooks.json in the data folder and in .circle/hooks.json in a trusted project. A changed project file has to be approved again; the digest is hook-trust.json in the data folder, not a settings key. See Hooks.

When you change one of these in a session (/themes, /settings, alt+d in /models or /effort, tab in /models, /approvals add), your choice is saved as yours and used from then on in this session.

Crediting Circle in commits

In a git repository, Circle’s prompt tells the model how to credit Circle when it creates or amends a commit or a pull request. The model adds the credit; Circle installs no git hook, does not rewrite an existing commit only to credit itself, and leaves the commits you make alone.

• With author user, the commit stays yours and ends with Co-authored-by: Circle <346680939+circle-agent@users.noreply.github.com>. GitHub shows the circle-agent account on the commit; its Contributors list counts only commit authors, so Circle is not listed there.
• With author circle, Circle is the commit author (--author) and you are added as Co-authored-by, from git config user.name and user.email. Circle then appears in the repository’s Contributors list. Without a user.email the commit stays yours with the co-author line, so a commit never names Circle alone.
• auto, the default, is circle for runs nobody watches (-p, JSON, line and RPC mode) and user in the full-screen interface and the desktop application.

A pull request body gets the line Generated with [Circle](https://github.com/circle-platforms/circle). "attribution": {"enabled": false} in your settings, in a project’s .circle/settings.json, or the switch under settings → git in the desktop application turns all of this off; the model is then told not to add it.

credentials.json

The API key is not in settings.json. It is in credentials.json next to it, a flat object of names and values:

{ "api_key": "sk-..." }

auth.api_key_ref names which entry to use. Both files are readable only by you (mode 0600; on Windows the folder’s permissions protect them).

Secrets the model uses by name are in secrets.json, also next to it; see Secrets by name.

Before you edit by hand

• Circle changes one key at a time. When you change something in a session (alt+d in /models or /effort, /themes, /settings, /trust, /login, /logout), Circle reads the file from disk, changes that key and writes it back, so your hand edits and keys Circle does not know stay. The exception is auth: Circle writes back only protocol, base_url, model and api_key_ref, so the mode and oauth_provider an older release wrote are dropped. The running session goes on with what it read at start until you run /reload.
• A malformed file stops Circle at start with settings could not be read and exit code 2, also for circle --init. Keep a copy before you edit.
• circle --init replaces only the connection: auth (endpoint, protocol, model). It also clears enabled_models when the endpoint changes. See CLI.

Reloading

/reload re-reads settings.json, the project’s .circle/settings.json and credentials.json, reconnects MCP servers, reloads extensions, and rebuilds the model. It applies theme and re-reads allowed_commands. It also re-reads hooks.json (yours, the project’s and any skill’s) for later events. It does not run session_start hooks again. It does not re-read credential_files, and it does not re-apply default_mode (a session-start setting). It is refused while a turn is running.

Personal sync selection

knowledge_sync defaults to { "server": "", "binding": "" }. /knowledge connect writes the explicitly selected HTTP MCP profile name and an opaque account binding after person approval. It contains no token; existing MCP headers or private OAuth storage supply credentials. A project cannot set this key. Replacing an account requires selection again before retained local content can upload; /knowledge disconnect clears the selection and retains the local store. The authoritative sync mode comes from the server, rather than this setting. The server is any one that implements knowledge-sync v1; Circle reads where it serves sync, local tools and its team operations from the server’s discovery document. In the desktop application, settings → sync selects the connection, shows the mode and status, and changes the mode with the same checked operations.