Advanced settings

Most settings are in the app's Settings page. This page covers the ones that are not: the keys you write by hand in a config file, and the environment variables the harness reads. Keys that have their own page — providers, memory, sync, plugins — are listed briefly here, with a link to that page.

Where settings live

FileScope
~/.oharness/config.jsonYou, on this computer. Every key below can go here.
oharness.config.json (or .oharness.json) in a projectEveryone who opens that project.

The project file is merged over yours, so a project can tighten or tune what you set. Some keys are left out of a project file on purpose, because a repository you clone should not be able to make them for you:

  • team: whose credits are spent
  • sync.url, sync.token, sync.team: where your transcripts go
  • runtimePlugins: code that runs on your computer
  • switching on automatic memory extraction or merging, which spends your model credit. A project may switch them off.

OHARNESS_HOME moves the whole ~/.oharness directory. See Configuration files for the other files in it.

{
  "model": "sonnet",
  "smallModel": "haiku",
  "permissionMode": "auto",
  "permissions": { "deny": ["Bash(git push --force*)"] },
  "writableRoots": ["~/scratch"],
  "maxTurns": 100,
  "sessionRetention": { "maxAgeDays": 90 }
}

Models

KeyWhat it does
modelThe model new conversations start on, by id or alias.
smallModelThe model for chores that do not need the main one: context compaction summaries, memory extraction, background tasks such as titles, and the auto-mode reviewer. Unset, these use the conversation's own model, which can be much more expensive than they need.
thinkingDefault reasoning: { "enabled": true, "effort": "high" }. effort is fitted to what the model supports. budgetTokens applies to models that take a token budget. display is "summarized" or "omitted".
cachePrompt caching where the provider supports it. On by default.
models, providers, catalog, openAiCompatible, oauthProvidersAdd or override models and providers. See Providers and models.

Set smallModel. Auto mode calls it before every action it reviews, and compaction calls it on long conversations. A fast, cheap model makes both quicker and keeps their cost low. If the id cannot be resolved, the harness logs a warning and falls back to the conversation's model.

Permissions

KeyWhat it does
permissionModeThe mode new conversations start in: default, acceptEdits, plan, auto or bypassPermissions.
permissionsallow, ask and deny rules. A deny rule wins over every mode, including Bypass.
workspaceModeWhere writes may land: read-only, workspace-write (default: the project plus writableRoots) or full-access. This checks tool arguments; it is not an OS sandbox.
writableRootsMore directories the agent may write to.
readableRootsMore directories the agent may read but not write.
auditKeep a record of every permission decision with its session. On unless set to false.
auditLogAlso append every decision to this file, for an unattended run whose record should be collected.

Permissions explains the modes, rule syntax and how auto mode's reviewer decides.

Turns and instructions

KeyWhat it does
maxTurnsHow many model calls one prompt may take before the agent stops and reports. Default 60.
systemPromptReplaces the built-in system prompt. Rarely what you want.
appendSystemPromptText added after the built-in system prompt.
instructionsFileA project instructions file other than the default, relative to the project root.

Tools and extensions

KeyWhat it does
tools{ "allow": [...], "deny": [...] } by tool name. Globs such as mcp__github__* work. deny applies after allow. A tool left out here is never offered to the model, unlike a permission rule, which refuses the call when it is made.
browser{ "mode": "auto" } (default) lets the agent choose between your browser, through the extension, and a built-in one. builtin, extension or off pins it.
claudeAgentOffer your own Claude Code as a subagent and as @claude, paid for by your Claude plan. Off unless set to true.
importsRead Claude Code's and Codex's skills, agents and MCP servers from where they live. Both on unless set to false.
skillDirs, agentDirsMore directories to scan for skills and subagent definitions.
disabledSkillsSkills switched off by name.
mcpServers, hooks, subagents, plugins, runtimePluginsSee Plugins.
schedulesPrompts that run on a cron schedule.

Sessions and worktrees

KeyWhat it does
sessionDirWhere sessions and transcripts are kept. Defaults to storage/ in ~/.oharness. Naming another directory starts from empty: nothing recorded in the default location is imported.
sessionRetention{ "maxAgeDays": 90, "keep": 500 } deletes older sessions on startup. Nothing is deleted unless you set this.
worktreeGetting a new git worktree ready. copy lists paths or globs copied from the project when the worktree lacks them (default .env*). setup is a shell command run in the new worktree, such as npm ci.
memory, syncSee Memory and sync.

Billing and logs

KeyWhat it does
teamCharge official-plan usage to a team's credits instead of yours. The service checks that you are on the team. Allowed in your own config or OHARNESS_TEAM, never in a project file.
logLeveldebug, info, warn, error or silent.

Environment variables

An environment variable overrides the matching config key where there is one.

VariableWhat it does
OHARNESS_HOMEUse another directory instead of ~/.oharness.
OHARNESS_TEAMSame as team.
OHARNESS_SYNC0, false, off or no switches sync off whatever the config says.
OHARNESS_SYNC_TOKENSync credential, when it is not in the config.
OHARNESS_SITE_URLA self-hosted or development Cloud address.
OHARNESS_CATALOGUse this file as your model catalog.
OHARNESS_NO_BUILTIN_MODELS1 leaves out the bundled model catalog, so only your own entries remain.
OHARNESS_NO_CLAUDE_AGENT1 never offers Claude Code as a subagent.
OHARNESS_BROWSER_PATHThe Chrome or Chromium binary the built-in browser starts.
OHARNESS_BROWSER_HEADLESS0 gives the built-in browser a visible window.
OHARNESS_CLAUDE_HOME, OHARNESS_CODEX_HOMEWhere to read Claude Code's and Codex's files, when they are not in the usual place.