User config

Your own settings, rather than a project’s: how CORA logs and colors its output and whether it writes for a screen reader, where it keeps a project’s state, how cora-mcp runs its browser, whether cora scan shows its own, and how long CORA waits on its service. Every cora command and cora-mcp read them in every project, from config.json in your per-user config directory. CORA never writes the file. None of its keys changes the config’s hash, configHash. It holds JSON, and a key under another, such as log.level, sits in that key’s object:

{
  "$schema": "https://cora.vispero.com/docs/0.10/schemas/cora-user-config/v1.json",
  "log": { "level": "debug", "file": true, "format": "json", "filesKept": 20 },
  "color": false,
  "screenReader": true,
  "stateDirectory": ".cache/cora",
  "page": { "timeout": 120000 },
  "server": { "timeout": 180000, "reuseExistingServer": true },
  "mcp": {
    "headless": true,
    "callTimeout": 120000,
    "actionTimeout": 10000,
    "navigationTimeout": 90000
  },
  "service": { "requestTimeout": 60000 },
  "browser": { "headed": true, "setupTimeout": 60000 }
}

A setting can take its value from a flag, its environment variable, the user config or the project’s config, and otherwise from its default. Which value wins gives the order they apply in. NO_COLOR, FORCE_COLOR or NODE_DISABLE_COLORS decides color only where the user config leaves it out. ACCESSIBLE decides screenReader only where CORA_SCREEN_READER and the user config leave it out. Each of the two files holds only the keys of its own reference page.

Where it lives

Linux: $XDG_CONFIG_HOME/cora, or ~/.config/cora when XDG_CONFIG_HOME is unset or relative
macOS: ~/Library/Application Support/cora
Windows: %APPDATA%\cora, or %USERPROFILE%\AppData\Roaming\cora when APPDATA is unset

Where CORA keeps state outside a project

Outside a project, cora and cora-mcp keep their state, such as their runs and their log files, in .cora/ in the directory they run in, which stateDirectory moves as it does in a project, resolved against that directory. Scanning without a project shows what works there.

What a release does not take

Every CORA release on the machine reads this one file, so a release ignores what it does not take rather than failing, with a warning naming the file: a key it does not know, such as one a later release reads, and a value it does not accept, each named in the warning, so the setting comes from the next source down as if the file left it out. It ignores the whole file when the file is not JSON, is not a JSON object, or holds a version key, which only a later version of the format has. cora info shows whether a release read the file, and what it ignored.

$schema

Type: string

The JSON Schema an editor validates this file against and completes its keys from: the user config’s schema in the docs of a CORA minor, https://cora.vispero.com/docs/<minor>/schemas/cora-user-config/v1.json, such as 0.6 for cora 0.6.2. Every release on the machine reads the file, so name the minor of the one you run most. VS Code downloads the schema once you trust cora.vispero.com: its warning that the location is untrusted offers the quick fix Configure Trusted Domains. Nothing in CORA acts on it: each release takes what it knows of the file, whatever the schema says.

log

Type: object

How CORA logs, in every project: the cora commands and cora-mcp alike. A command’s flags and the CORA_LOG_* variables override each key.

log.level

Type: “trace”, “debug”, “info”, “warn”, “error” or “silent”
Default: "warn" for cora, "info" for cora-mcp
Environment: CORA_LOG_LEVEL
Command line: cora --log-level, cora --verbose or -v, cora --quiet or -q, cora --debug

The least severe records CORA writes, on stderr and to a log file: trace, debug, info, warn, error, or silent for none. Left out, it is warn for the cora commands and info for cora-mcp. --log-level, -v, -q, --debug and CORA_LOG_LEVEL override it, and so does CI debug mode.

log.file

Type: boolean or string
Environment: CORA_LOG_FILE
Command line: cora --log-file, cora --debug

Whether CORA also writes a log file: true writes one in the state directory’s logs/, a path writes it there, relative to the working directory, and false writes none. Left out, CORA writes none. cora hook keeps its own log whatever this says: hooks-<session>.log in logs/, one for each coding-agent session its events name. --log-file, --debug and CORA_LOG_FILE override it.

log.format

Type: “human” or “json”
Default: "human"
Environment: CORA_LOG_FORMAT
Command line: cora --log-format

How CORA writes its records on stderr: human, a line each, or json, as JSON Lines. --log-format and CORA_LOG_FORMAT override it.

log.filesKept

Type: integer
Default: 10
Environment: CORA_LOG_FILES_KEPT
Command line: none

How many log files of each kind, and how many crash files, the state directory’s logs/ keeps: a positive integer. A process that opens one of a kind deletes the oldest of that kind beyond it. CORA_LOG_FILES_KEPT overrides it.

color

Type: boolean
Environment: NO_COLOR, FORCE_COLOR, NODE_DISABLE_COLORS, when it is left out
Command line: cora --color or cora --no-color

Whether the cora commands color what they write for people: their lines on stderr, their help, and the reports cora info, cora status and cora auth status print on stdout. true colors them even where the stream is not a terminal, and false never colors them, the report of an invalid argument included. It wins over NO_COLOR, FORCE_COLOR and Node.js’s own NODE_DISABLE_COLORS, which decide only when it is left out. Left out, the commands write plain text in CI and under a coding agent, on a terminal too, unless FORCE_COLOR is set; elsewhere, with none of those variables set, they color a stream that is a terminal. Machine output, such as --json, is never colored, and neither is cora-mcp’s stderr, which is its client’s log. --color and --no-color override it.

screenReader

Type: boolean
Default: false
Environment: CORA_SCREEN_READER, then ACCESSIBLE where neither it nor the user config sets it
Command line: none

Whether the cora commands write for a screen reader, such as NVDA, JAWS or VoiceOver, which speaks whatever a terminal shows anew: a line rewritten in place is spoken again at each change, but NVDA ignores a change of one character, which it takes for a typed one, so a count that moves by one digit goes unspoken. With it on, a question is asked line by line, without a frame, its choices in words and its answer typed; progress is printed as new lines rather than as one line rewritten in place, at most one every 10 seconds while nothing else is printed, so nothing moves the cursor or redraws a line; and a file’s diff, such as cora init shows, names each line’s change in words, added:, removed: or unchanged:, rather than by its mark, and each stretch of it by its lines. It leaves the colors to color, and cora-mcp’s output, which its client reads, as it is. CORA_SCREEN_READER overrides it, and where both leave it out, ACCESSIBLE, which other tools’ prompts read, turns it on when it is set to anything but 0 or false.

stateDirectory

Type: string
Default: ".cora"
Environment: CORA_STATE_DIRECTORY
Command line: none

Where CORA keeps a project’s state: its run files, its log files, the remediation loop’s records, the files of cora-mcp’s browser tools, and the report directory cora scan and cora report merge write unless told otherwise. A path relative to the project root, or to the working directory outside a project, or an absolute one, which names the directory too, and never that directory or one that holds it. The directory ignores itself in git wherever it is. The baseline, which is committed, stays in the project root, or in the working directory outside a project. CORA_STATE_DIRECTORY overrides it.

page.timeout

Type: integer
Default: 60000
Environment: CORA_PAGE_TIMEOUT
Command line: cora scan --page-timeout

How long one visit of a page may take on this machine, from opening it to closing it, in milliseconds: a positive integer up to a day, 86400000. It replaces the project config’s page.timeout in every project, such as on a slow machine, though a route’s own value still wins on the pages it matches. A page that takes longer is recorded timed-out, naming the setting. cora scan --page-timeout and CORA_PAGE_TIMEOUT override it.

server

Type: object

How cora scan treats the app’s server on this machine, in every project whose config names one in its server key, over that key’s values. Without a server there, these do nothing.

server.timeout

Type: integer
Default: 60000
Environment: CORA_SERVER_TIMEOUT
Command line: none

How long cora scan waits on this machine for the app’s server to answer at its URL, from running its command, in milliseconds: a positive integer up to a day, 86400000. It replaces the project config’s server.timeout in every project, such as on a slow machine. A server not ready within it fails with server.timed-out, naming the setting and its value. CORA_SERVER_TIMEOUT overrides it.

server.reuseExistingServer

Type: boolean
Default: false
Environment: CORA_SERVER_REUSE_EXISTING_SERVER
Command line: none

Whether cora scan on this machine scans a server that already answers at the URL of the project config’s server, and starts none, rather than failing with server.already-running, such as a server you keep running yourself while you work. It replaces the project config’s server.reuseExistingServer in every project. CORA_SERVER_REUSE_EXISTING_SERVER overrides it.

mcp

Type: object

cora-mcp’s settings for this machine, in every project. The CORA_MCP_* variables override each key.

mcp.headless

Type: boolean
Default: false
Environment: CORA_MCP_HEADLESS
Command line: cora-mcp --headless

Whether cora-mcp’s browser runs without a window; false shows its window, where the person sees the agent browse and can sign in. Where no display can show the window, on Linux without an X11 or Wayland display, as under WSL without WSLg, and on macOS and Windows in an SSH session, the browser runs without one all the same, with a warning naming this setting. cora-mcp’s --headless argument and CORA_MCP_HEADLESS override it.

mcp.callTimeout

Type: integer
Default: 60000
Environment: CORA_MCP_CALL_TIMEOUT
Command line: none

How long cora-mcp works on a tool call before it stops waiting and closes its browser, in milliseconds: a positive integer up to a day, 86400000. Its default is the request timeout of the MCP SDK’s client, which Codex keeps. CORA_MCP_CALL_TIMEOUT overrides it.

mcp.actionTimeout

Type: integer
Default: 5000
Environment: CORA_MCP_ACTION_TIMEOUT
Command line: none

How long one of cora-mcp’s browser tools waits for an action on the page, such as a click, in milliseconds: a positive integer up to a day, 86400000. Its default is playwright-mcp’s own. CORA_MCP_ACTION_TIMEOUT overrides it.

mcp.navigationTimeout

Type: integer
Default: 60000
Environment: CORA_MCP_NAVIGATION_TIMEOUT
Command line: none

How long one of cora-mcp’s browser tools waits for a page it navigates to, in milliseconds: a positive integer up to a day, 86400000. Its default is playwright-mcp’s own. CORA_MCP_NAVIGATION_TIMEOUT overrides it.

service

Type: object

How the cora commands and cora-mcp reach the CORA service, in every project. The CORA_SERVICE_* variables override each key.

service.requestTimeout

Type: integer
Default: 30000
Environment: CORA_SERVICE_REQUEST_TIMEOUT
Command line: none

How long the cora commands and cora-mcp wait on each request to the CORA service, its answer included, in milliseconds: a positive integer up to a day, 86400000. A request that takes longer fails as service.unreachable. Raise it on a network whose proxy or VPN is slow. CORA_SERVICE_REQUEST_TIMEOUT overrides it.

browser

Type: object

How the browser CORA launches runs on this machine, in every project. The CORA_BROWSER_* variables override each key.

browser.headed

Type: boolean
Default: false
Environment: CORA_BROWSER_HEADED
Command line: cora scan --headed

Whether cora scan shows its browser’s window, so you can watch it scan. A scan runs without a window, with a warning naming this setting, where no one may watch it, in CI or under a coding agent, and where no display can show the window: on Linux without an X11 or Wayland display, as under WSL without WSLg, and on macOS and Windows in an SSH session. cora-mcp’s browser follows mcp.headless instead. cora scan --headed and CORA_BROWSER_HEADED override it.

browser.setupTimeout

Type: integer
Default: 60000
Environment: CORA_BROWSER_SETUP_TIMEOUT
Command line: none

How long the project config’s browser.setup may run on this machine, in milliseconds: a positive integer up to a day, 86400000. It replaces the project config’s browser.setupTimeout in every project, such as on a slow connection, where signing in to an identity provider takes longer. A setup still running then fails with signin.setup-failed, naming the setting and its value. CORA_BROWSER_SETUP_TIMEOUT overrides it.