Skip to content

.openharness/settings.yaml now holds only core workspace configuration: the default agent, optional model aliases, engine behavior toggles, imports, and extra skill directories.

Prompt configuration has moved to the dedicated prompts.yaml file.

default_agent: build
default_agent: build
models:
default:
ref: platform/openai-default
temperature: 0.2
max_tokens: 2048
planner:
ref: workspace/repo-planner
skill_dirs:
- ./.codex/skills
imports:
tools:
- docs-server
skills:
- repo-explorer
engine:
session_memory:
enabled: false
workspace_memory:
enabled: false
FieldRequiredDescription
default_agentNoDefault primary agent. At runtime it must resolve to a visible agent and cannot point to a pure subagent-only definition
modelsNoModel alias map that agents can reference; when omitted, agents use the platform default model
skill_dirsNoAdditional skill search directories
engineNoOptional runtime engine behavior toggles. compact is built in; session_memory and workspace_memory represent two different memory layers
runtimeNoRecords which runtime the workspace was initialized from
importsNoTools and skills to import during runtime initialization

tip

If a runtime needs stable model selection, prefer having agents reference these aliases via `model: <alias>`. Then switching models only requires editing `settings.yaml`.
models:
default: platform/openai-default
cheap: workspace/repo-model
tuned:
ref: platform/openai-default
temperature: 0.2
top_p: 0.9
max_tokens: 2048
RuleDetails
keyAlias used by agent frontmatter, for example model: default
value shapeEither a shorthand string such as platform/<name> / workspace/<name> or an object with ref plus optional inference defaults
refConcrete model ref, must be platform/<name> or workspace/<name>
temperature / top_p / max_tokensDefault inference parameters for that model alias
resolution timeResolved when the workspace loads; the runtime still operates on concrete model_refs internally
scopeOnly affects agents that declare a non-default alias or canonical model ref; agents without an explicit model use the platform default model

If an agent omits model, or declares model: default while models.default is not defined, the runtime uses the platform default model. Other missing aliases still fail during workspace loading.

Use this file to decide both which concrete model each alias points to and which inference defaults it carries; use agent frontmatter only to choose the alias.

engine:
session_memory:
enabled: true
workspace_memory:
enabled: true
FieldDescription
compact.enabledEnables the automatic compaction behavior. It defaults to on and does not need to be configured explicitly. Only set compact: { enabled: false } when you want to disable it
session_memory.enabledEnables session-scoped memory used for continuity within the current conversation. It is distinct from workspace-persistent memory
workspace_memory.enabledEnables workspace-scoped persistent memory. This maps to the .openharness/memory/ directory
skill_dirs:
- ./.codex/skills
- ./.shared/skills
RuleDetails
Default directory.openharness/skills/* is always scanned
Additiveskill_dirs adds directories; it does not replace the default
Path resolutionRelative to the workspace root
Priority.openharness/skills/* > skill_dirs declaration order
Name conflictFirst match wins by scan order; later directories with the same skill name are ignored
Duplicate inside one rootIf one skill root resolves to duplicate names, loading fails
imports:
tools:
- docs-server
skills:
- repo-explorer
FieldDescription
toolsPlatform tools to copy into the workspace from paths.tool_dir
skillsPlatform skills to copy into the workspace from paths.skill_dir

These are only used during runtime initialization. Imported tools and skills are copied into the workspace’s own .openharness/ tree, and the runtime then works from that Active Workspace Copy instead of reading the platform directory live. Referencing a nonexistent tool or skill causes initialization to fail.