Skip to content

config.md

Latest commit

 

History

History
182 lines (141 loc) · 4.33 KB

config.md

File metadata and controls

182 lines (141 loc) · 4.33 KB

Configuration

OMA reads JSONC configuration locally. Config files are validated on startup.

Canonical paths

  1. ~/.config/oma/oma.jsonc (global)
  2. .oma/oma.jsonc (project-local, overrides global)

Precedence order

  1. Embedded agent definitions
  2. Embedded runtime defaults
  3. Global OMA config
  4. Project-local OMA config
  5. Mandatory runtime policy overrides

Supported top-level keys

  • $schema
  • version
  • agent
  • workflow
  • memory
  • github
  • mcp
  • disabledTools
  • commandSurface

version may be 1 or 2. Canonical examples use version: 2.

Agent overrides

Only registered agent names are valid under agent. Run oma --agents to see the full catalog.

Supported fields per agent:

  • model — e.g., openai/gpt-4.4, anthropic/claude-sonnet-4-6
  • variant — provider-specific variant identifier
  • temperature — must be between 0 and 1
  • steps — positive integer; max conversation turns
  • hidden — hide from agent catalog
  • disable — disable this agent
  • color — hex color for TUI display (#RRGGBB)
  • fallback — fallback provider config
  • promptExtension — prepend/append to agent system prompt
  • disabledTools — tools unavailable to this agent

Fallback

"fallback": {
  "model": "anthropic/claude-opus-4-6",
  "variant": "high"
}

fallback.model is required when fallback is provided.

Workflow

"workflow": {
  "hookProfile": "standard",
  "orchestration": {
    "maxParallelAgents": 3,
    "timeoutMs": 300000,
    "retryPolicy": "none"
  }
}
  • hookProfile: off | standard | strict
  • maxParallelAgents: caps active child-session background tasks per parent session
  • timeoutMs: default timeout for background_task_start when call omits timeoutMs
  • retryPolicy: reserved for future use; v2.0.0 validates but does not yet enforce retries

Memory

"memory": {
  "enabled": true,
  "directory": ".cache/oma-memory",
  "maxProjectInstincts": 50,
  "maxRecentOutcomes": 25
}

Memory is stored under the XDG state path by default: $XDG_STATE_HOME/oma/projects/<project-id>/memory/ (fallback ~/.local/state/oma/projects/<project-id>/memory/).

The directory field, if provided, is resolved relative to the worktree root.

For safety, OMA only accepts repo-local overrides when they stay within the worktree and are outside .oma/. If the resolved path leaves the worktree or resolves into .oma/ (including symlink traversal through .oma), OMA ignores it and falls back to the XDG state memory path.

Because of this safeguard, .oma/memory and other .oma/* overrides are unsupported for ongoing writes. Legacy data under .oma/* is migrated once during runtime initialization to app-owned memory state.

GitHub

"github": {
  "enabled": true,
  "host": "github.com",
  "token": "ghp_...",
  "tokenEnvVar": "GITHUB_TOKEN"
}

Token precedence: github.token value takes priority over the environment variable referenced by github.tokenEnvVar.

MCP

MCP is configured via the mcp section in oma.jsonc:

"mcp": {
  "context7": {
    "enabled": true,
    "url": "https://mcp.context7.com/mcp",
    "timeout": 15000
  }
}

In v2.0.0, only mcp.context7 is supported. MCP servers are configured through oma.jsonc — there is no .oma/mcp/ directory or auto-discovery.

Tool restrictions

"disabledTools": {
  "global": ["webfetch"],
  "perAgent": {
    "explorer": ["run_command"]
  }
}

Only embedded agent names are valid keys under perAgent.

Command surface policy

"commandSurface": {
  "allowDangerousCommands": false,
  "restrictedCommands": ["rm -rf"],
  "requireConfirmation": ["git push --force"]
}

Note: The current CLI does not provide an interactive confirmation flow, so requireConfirmation matches are blocked.

Minimal example

{
  "$schema": "https://oma.local/schemas/oma.schema.json",
  "version": 2,
  "workflow": {
    "hookProfile": "standard",
  },
  "agent": {
    "cto": {
      "model": "openai/gpt-4.4",
      "variant": "high",
    },
    "reviewer": {
      "temperature": 0.05,
      "fallback": {
        "model": "anthropic/claude-opus-4-6",
        "variant": "high",
      },
    },
  },
}

Full references