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
| File | Scope |
|---|
~/.oharness/config.json | You, on this computer. Every key below can go here. |
oharness.config.json (or .oharness.json) in a project | Everyone 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 spentsync.url, sync.token, sync.team: where your transcripts goruntimePlugins: 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
| Key | What it does |
|---|
model | The model new conversations start on, by id or alias. |
smallModel | The 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. |
thinking | Default 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". |
cache | Prompt caching where the provider supports it. On by default. |
models, providers, catalog, openAiCompatible, oauthProviders | Add 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
| Key | What it does |
|---|
permissionMode | The mode new conversations start in: default, acceptEdits, plan, auto or bypassPermissions. |
permissions | allow, ask and deny rules. A deny rule wins over every mode, including Bypass. |
workspaceMode | Where 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. |
writableRoots | More directories the agent may write to. |
readableRoots | More directories the agent may read but not write. |
audit | Keep a record of every permission decision with its session. On unless set to false. |
auditLog | Also 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
| Key | What it does |
|---|
maxTurns | How many model calls one prompt may take before the agent stops and reports. Default 60. |
systemPrompt | Replaces the built-in system prompt. Rarely what you want. |
appendSystemPrompt | Text added after the built-in system prompt. |
instructionsFile | A project instructions file other than the default, relative to the project root. |
| Key | What 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. |
claudeAgent | Offer your own Claude Code as a subagent and as @claude, paid for by your Claude plan. Off unless set to true. |
imports | Read Claude Code's and Codex's skills, agents and MCP servers from where they live. Both on unless set to false. |
skillDirs, agentDirs | More directories to scan for skills and subagent definitions. |
disabledSkills | Skills switched off by name. |
mcpServers, hooks, subagents, plugins, runtimePlugins | See Plugins. |
schedules | Prompts that run on a cron schedule. |
Sessions and worktrees
| Key | What it does |
|---|
sessionDir | Where 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. |
worktree | Getting 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, sync | See Memory and sync. |
Billing and logs
| Key | What it does |
|---|
team | Charge 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. |
logLevel | debug, info, warn, error or silent. |
Environment variables
An environment variable overrides the matching config key where there is one.
| Variable | What it does |
|---|
OHARNESS_HOME | Use another directory instead of ~/.oharness. |
OHARNESS_TEAM | Same as team. |
OHARNESS_SYNC | 0, false, off or no switches sync off whatever the config says. |
OHARNESS_SYNC_TOKEN | Sync credential, when it is not in the config. |
OHARNESS_SITE_URL | A self-hosted or development Cloud address. |
OHARNESS_CATALOG | Use this file as your model catalog. |
OHARNESS_NO_BUILTIN_MODELS | 1 leaves out the bundled model catalog, so only your own entries remain. |
OHARNESS_NO_CLAUDE_AGENT | 1 never offers Claude Code as a subagent. |
OHARNESS_BROWSER_PATH | The Chrome or Chromium binary the built-in browser starts. |
OHARNESS_BROWSER_HEADLESS | 0 gives the built-in browser a visible window. |
OHARNESS_CLAUDE_HOME, OHARNESS_CODEX_HOME | Where to read Claude Code's and Codex's files, when they are not in the usual place. |