stella.toml

stella.toml is Stella's config file in TOML instead of JSON. It reads across the same three scopes as settings.json, merges by the same rules, and is gated by the same project trust boundary — the file format changed, nothing about who is trusted did. What TOML adds is what JSON structurally cannot hold: comments that survive a write, and a [meta] block that turns forward compatibility into a mechanism instead of a warning.

Where each scope's file lives

The scope hierarchy — precedence, the trust boundary, which fields merge per-field versus whole-block versus concatenate — is unchanged from JSON. See The scope hierarchy for the full rules; shows the same shape either format reads through.

Getting there: stella migrate config

stella migrate config          # write the TOML for every scope that has JSON
stella migrate config --dry-run

Every value it writes is serialized from the settings.json stella actually parsed — never re-typed — and the generated file is re-parsed and re-validated before it touches disk. The original JSON is never deleted; you remove it once you've confirmed the TOML says what you meant. Full walkthrough: stella migrate.

TOML and settings.json are never merged

If both files exist at a scope, Stella reads the TOML whole and ignores the JSON — never a field-by-field composite of the two. A composite would make "which file configures this?" unanswerable from either file alone; the actual failure mode that guards against is someone editing the JSON, seeing no effect, and having nothing to look at.

! ~/.stella/stella.toml and ~/.stella/settings.json both exist — reading the TOML and
  IGNORING the JSON. Delete the JSON once you have confirmed the migration.

This notice prints once per launch, at every scope where it applies. A missing TOML file falls back to the JSON exactly as before; a missing file at either format is fine and is simply skipped.

The [meta] block

The one section with no JSON equivalent — settings.json has no version field at all, so a typo and a key from a future release look identical to serde. [meta] is what makes that distinguishable.

[meta]
schema_version = 1
scope          = "project"   # "user" | "managed" | "project"

What moved, and why

Four things changed shape in the port. Everything else kept its name.

trace_capture and create_worktrees needed no such move: both shipped straight into their [run] table home, so neither ever had a bare-root JSON form to retire.

Every section, in the TOML shape

Merge rules below are identical to their JSON counterparts — restated here only so this page is a complete reference on its own; see the linked section for the full explanation.

[run]

[run]
recap          = "on"
trace_capture  = "off"
create_worktrees = "ask"

[providers]

Identical shape and rules to JSON's providers map — a table keyed by provider id, merged per-id and per-field. See The providers map.

[providers.zai]
name          = "ZAI Provider"
base_url      = "https://api.z.ai/api/coding/paas/v4"
api_key_env   = "ZAI_API_KEY"
default_model = "n-5.2"

[models]

[models]
allowed = ["anthropic/claude-fable-5", "zai/glm-5.2", "openrouter/openai/gpt-5.5"]

[models.output_caps]
"anthropic/claude-sonnet-5" = 64000
"deepseek-chat"             = 32000

[agents]

The flattened, closed-set engine config — see Agent engine config for the full schema, model precedence, auto modes, and generation parameters, all unchanged. Flattening [agents.judge] (rather than the JSON nesting's [agents.agents.judge]) is safe only because exactly four names exist and none of them can collide with a root scalar like default_model.

[agents]
default_model         = "zai/glm-5.2"
pipeline_judge_model  = "anthropic/claude-fable-5"
pipeline_triage_model = "deepseek/deepseek-chat"
auto_mode             = "off"
effort_auto           = "on"

[agents.judge]
provider  = "openrouter"
model     = "openai/gpt-5.5"
effort    = "high"
reasoning = "on"

  [agents.judge.params]
  temperature = 0.2
  max_tokens  = 4096

[tools]

Same open map, same deny-list, same name-over-group-over-"*" precedence as The tools section. The one TOML-specific wrinkle: * is not a valid bare TOML key, so the wildcard needs quotes.

[tools]
bash    = "off"
process = "off"
"*"     = "on"

[hooks]

Same schema and the same concatenate-across-scopes rule (the one block that isn't per-field or whole-block last-wins) as Lifecycle hooks — and the same project-trust gate. TOML expresses the event arrays as array-of-tables rather than JSON's bracketed arrays:

[[hooks.PreToolUse]]
matcher = "bash"
  [[hooks.PreToolUse.hooks]]
  type      = "command"
  command   = "./scripts/guard.sh"
  timeoutMs = 5000

[mcp]

registry_url carries over unchanged — see The mcp section.

[mcp]
registry_url = "https://registry.example.internal/mcp"

[context] and [context_providers]

Unchanged shape and rules — whole-block last-wins for context, per-entry last-wins for context_providers. See The context block and External context providers.

[ui]

Unchanged — see The ui section.

[ui]
theme = "stella-light"

[reward]

What a finished turn's verdict is worth as a training label (#1043). Whole-block last-wins, like [ui]; carries no credential or egress authority, so a project setting a weight is stating an opinion about its own judge, not borrowing permission.

[reward]
judge_weight = 0.3   # trust this workspace's judge less than the 0.5 default

[authority] — managed scope only

Unchanged — see Managed authority ceilings. Present in a user or project stella.toml, it is ignored; only the file at the managed-scope path grants it.

[enterprise_telemetry] — managed scope only

Unchanged — see Enterprise telemetry enrollment. Round-trips as an untyped table and is validated fail-open by its own adapter, so its shape is not pinned by this schema.

Comments and edits survive a write

The whole reason to migrate: stella.toml is edited through toml_edit, which rewrites only the keys a save actually touches and preserves everything else — comments, key order, blank lines — byte-for-byte. /theme, the tool-switch editor, and the engine config panel all edit stella.toml in place once one exists for that scope. A settings.json re-render through serde_json::Value cannot make this promise — JSON has nothing to preserve besides keys — which is why comment loss was the risk this whole format port was built to avoid.

What is not built yet

Phase 1 — the format port covered on this page — is complete. docs/design/config-system/DESIGN.md lays out five further phases that are design only, not yet functional: pipeline-stage toggles, an open (non-four-name) agent set with per-agent tool scope, [models] pin / track_latest policy, provider fallback (provider_preference), and declarative [integrations.<id>] blocks for tools with interchangeable backends. None of those keys do anything if you write them today — read the design doc on GitHub if you want the plan before it ships: docs/design/config-system/DESIGN.md.

A complete example file

Everything above, in one project-scope file:

[meta]
schema_version = 1
scope          = "project"

[run]
recap = "on"

[providers.zai]
base_url      = "https://api.z.ai/api/coding/paas/v4"
api_key_env   = "ZAI_API_KEY"
default_model = "n-5.2"

[models]
allowed = ["zai/glm-5.2", "anthropic/claude-fable-5"]

[agents]
default_model = "zai/glm-5.2"
auto_mode     = "on"

[tools]
process     = "off"
read_output = "on"

[[hooks.PreToolUse]]
matcher = "bash"
  [[hooks.PreToolUse.hooks]]
  type      = "command"
  command   = "./scripts/guard.sh"
  timeoutMs = 5000

[ui]
theme = "stella-dark"

Check what actually resolved — the same two commands regardless of which format loaded it:

stella config
stella models

Security

Same posture as settings.json: a stella.toml may carry an api_key in plaintext at user or managed scope, so treat it like any other secret file at those scopes. Project scope removes the temptation entirely — see [providers] above — which is the one thing the JSON format could never enforce, because .stella/settings.json had no single canonical location to enforce it from.