AUTO-DETECTED VIA A PACKAGE-SCOPED ENV — LIVE SCHEMAS

Settings schema

Settings defaults schema — top-level keys (auto-detected). Each key is discovered from the loaded environment; expand its schema only when you need its complete default shape.

`context`

Context policy: cap = runaway guard overall limit (default 0.9); turn = cumulative growth limit for one turn (default 0.4). Fractional values above 1 mean percentages. autocompact = fractional compaction trigger (default 0.4; true = 0.4; false/0/1/100 disable only this trigger). autocompactMax = absolute token trigger (default 200000; nonnegative safe integer, 0 disables only this trigger). Either enabled trigger can start compaction at its limit; the absolute trigger works without a known model window. Set both to 0 to disable auto-compaction. Successful compaction continues the turn unless the guard trips: compaction does not erase pre-compaction usage or cumulative growth. Endpoint and model context settings override per key. Read when an Agent is created or selects a model.

Schema

{
  "cap": "number",
  "turn": "number",
  "autocompact": "boolean | number (default 0.4; true = 0.4; fractions < 1 or percentages > 1; false/0/1/100 disable)",
  "autocompactMax": "nonnegative safe integer (tokens; default 200000; 0 disables)"
}

`env`

Child-process environment (name -> value): inherited KEY/TOKEN/AUTH/OAUTH/PASSWORD/PASS/SECRET names are omitted by default; false removes, true explicitly passes the inherited value, and a non-nullish value sets it. Explicit tool/MCP additions merge last and require caller authorization.

Schema

{
  "<NAME>": "false | true | string"
}

`extensions`

Installed npm package names or existing folder paths (name/path -> true/false) to load as Omoya content roots (JSON settings, providers, tools, skills, prompts, themes). Package/user scope only; project settings cannot add extensions.

Schema

{
  "<package-or-folder>": "boolean"
}

`maxActive`

Default cap on concurrently RUNNING Agents (endpoint and model limits override it; false excludes one).

Schema

"number"

`mcp`

MCP servers (name -> either {command, args?, env?} or {url, headers?}, plus timeout?, safe?, description?). HTTP requires https or loopback http; optional oauth {clientId?, issuer?} triggers explicit user sign-in with separate user-only token files. Header ${VAR} references use the settings-filtered child environment. Published as mcp and mcp-<name> — package/settings scope only.

Schema

{
  "<server>": {
    "command": "string",
    "args": "string[]",
    "env": "object",
    "timeout": "number",
    "safe": "boolean",
    "description": "string"
  }
}

`projects`

Env.settings.projects: global pin records keyed by absolute folder (folder -> {models: {<endpoint>/<model>: ISO timestamp}, description?: string, groups?: {<group>: true}}), kept in the user settings folder's projects.json. A pinned project's newest available model is selected before global last-model memory. Pin reads add derived name (shortest unique folder suffix) and folder; neither derived field nor any alias persists. Instance env.settings.projects reads reachable records (own folder even when unpinned, plus pins sharing a group) keyed by absolute folder and name aliases pointing to the same records; this aliases the own folder record. Both views permit global pin writes through folder keys or name aliases; instance writes may create new folder pins despite its filtered reads. Assigning a new folder pin through env.settings.projects[folder] inherits every true group from that Env's own current global pin, making the new entry reachable; Env.settings.projects writes do not auto-add groups.

Schema

{
  "<absolute folder or name alias>": {
    "folder": "absolute folder",
    "name": "shortest unique folder suffix",
    "models?": "<endpoint>/<model> -> ISO timestamp",
    "groups?": "<group> -> boolean",
    "description?": "string"
  }
}

`prompts`

Extra prompt roots (path -> true/false).

Schema

{
  "<path>": "boolean"
}

`providers`

Manually configured endpoints (name -> {provider, url, model?, timeout?, maxActive?, disabled?, secret?, filter?, ...}; disabled: true hides and refuses the endpoint; filter is a regex source: non-matching models publish as secret). providers.tools.<tool> controls the global default for provider-hosted tools (false lets a same-named package tool serve instead); model and endpoint tool settings override it.

Schema

{
  "tools": {
    "<tool>": "boolean"
  },
  "<endpoint>": {
    "provider": "string",
    "url": "string",
    "model": "string",
    "timeout": "number",
    "contextWindow": "number",
    "models": "object"
  }
}

`read`

Finite read budgets: scanBytes, files, entries, fileBytes, grepFileSizeLimit, outputBytes, artifactBytes, regexMs, timeoutMs. Positive safe integer host settings; invalid/nonpositive values use defaults. Query args cannot disable budgets.

Schema

{
  "scanBytes": "number",
  "files": "number",
  "entries": "number",
  "outputBytes": "number",
  "artifactBytes": "number",
  "fileBytes": "number",
  "grepFileSizeLimit": "number",
  "regexMs": "number",
  "timeoutMs": "number"
}

`retry`

Failed provider requests: attempts per turn including the first (default 3), base = the first retry delay (default 2s, doubling per retry), max = the delay ceiling (default 30s). Durations accept ms or unit strings. Read when an Agent is created.

Schema

{
  "attempts": "number",
  "base": "number",
  "max": "number"
}

`sessions`

Session log folder (default: <settings folder>/sessions). Relative paths in project settings resolve against the project; package/user settings paths resolve against the settings folder. Reads answer the resolved folder; host Env sessionsDir overrides without persistence.

Schema

"string"

`skills`

Extra skill roots (path -> true/false).

Schema

{
  "<path>": "boolean"
}

`theme`

Shared theme selection for TUI and web. Both interfaces inherit it unless a legacy tui.theme or web.theme override is set; selecting a theme in either interface updates this shared value.

Schema

"unknown"

`themes`

Named themes (name -> role tokens), shared by the TUI and web. themes/*.json files in the package, extension and user folders and the project's ai-themes/ folder each hold { <name>: {...} } and load here, never at the settings root.

Schema

{
  "<theme>": {
    "parent": "theme name | default",
    "<role>": {
      "fg": "color | {dark, light, default}",
      "bg": "color | {dark, light, default}",
      "bold": "boolean",
      "dim": "boolean",
      "italic": "boolean",
      "underline": "boolean",
      "reverse": "boolean",
      "strike": "boolean"
    },
    "tool.preview": {
      "maxRows": "positive integer"
    },
    "message.thinking.preview": {
      "maxRows": "positive integer"
    }
  }
}

`tools`

Tool policy: folders (extra roots as path -> true/false; package/user only), timeout (default 120s), timeoutLimit (default 20m), concurrency (read-only dispatch group size, default 3). Durations accept milliseconds or unit strings. Project files may set policy but never folders.

Schema

{
  "folders": {
    "<path>": "boolean"
  },
  "timeout": "number",
  "timeoutLimit": "number",
  "concurrency": "number"
}

`tui`

Terminal UI settings: cursor {blink, shape}, alt-screen flag (default true; false selects inline when --screen is omitted), key overrides, mouse flag (true managed, false off, unset mode default), OSC 52 clipboard, scrollbar, and legacy theme override (tui.theme overrides shared theme until the next UI selection).

Schema

{
  "cursor": {
    "blink": "number",
    "shape": "string"
  },
  "alt": "boolean",
  "keys": {
    "<key>": "key binding"
  },
  "osc52": "boolean",
  "scroll": {
    "show": "boolean",
    "track": "string",
    "thumb": "string"
  },
  "theme": "string"
}

`web`

Web tools: debug (show the taken HTTP access point), search {backends, engines, cache}, fetch {timeout, cacheSeconds, ...}, limit {calls:8, windowMs:40000} shared by package fetch/search; throttle {startAt:0.2, step:0.05, stepMs:1000}: success pauses capped at half the actual remaining tools.timeout; parallel pauses overlap. Full burst waits only below half the remaining deadline, otherwise busy. Dispatch respects Agent deadlines or tools.timeout/tools.timeoutLimit defaults. mcp {server, searchTool, fetchTool, shadow}, readability.

Schema

{
  "autocomplete": "boolean",
  "collapse": {
    "thinking": "boolean",
    "tools": "boolean"
  },
  "theme": "string",
  "limit": {
    "calls": "number",
    "windowMs": "number"
  },
  "throttle": {
    "startAt": "number",
    "step": "number",
    "stepMs": "number"
  }
}