Configuration

Config Directory

Default: ~/.oculus/. Override with the OCULUS_CONFIG_DIR environment variable.

settings.json

The main configuration file. All fields are optional; Oculus ships with sensible defaults.

{
  "defaultMode": "default",
  "model": "gemini-2.5-flash",
  "theme": "dark",
  "verbose": false,
  "lenses": {
    "focus": { "model": "claude-opus-4-6", "provider": "anthropic" },
    "scan": { "model": "gemini-2.5-flash", "provider": "gemini" },
    "craft": { "model": "codex", "provider": "codex" },
    "categoryRoutes": {
      "security": { "lens": "focus", "model": "claude-opus-4-6" },
      "testing": { "lens": "craft", "model": "claude-sonnet-4-6" }
    },
    "complexity": {
      "enabled": true,
      "simpleModel": "claude-haiku-4-5",
      "standardModel": "claude-sonnet-4-6",
      "complexModel": "claude-opus-4-6"
    }
  },
  "costCeiling": 5.00,
  "maxSteps": 100,
  "maxQueryDuration": "5m",
  "fallback_models": {
    "claude-opus-4-6": ["claude-sonnet-4-6", "gemini-2.5-flash"],
    "claude-sonnet-4-6": ["gemini-2.5-flash"]
  },
  "skillTriggers": [
    { "keywords": ["deploy", "release"], "skill": "deployment", "context": "Use CI/CD best practices" }
  ],
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "command": "echo checking..." }]
  },
  "mcpServers": {
    "context7": { "command": "npx -y @upstash/context7-mcp" }
  }
}

OCULUS.md

Project-specific instructions loaded into every system prompt. Place at project root or .oculus/OCULUS.md.

• Also reads CLAUDE.md as a fallback for compatibility.
• Supports @include path/to/file.md directives.

Environment Variables

Permission Modes

Safeguards

Session-level spending and execution limits configured in settings.json:

All three are also editable from the /settings interactive page under the Safeguards tab.

Fallback Models

Define ordered fallback chains per primary model. On provider error, Oculus retries with the next model automatically.

"fallback_models": {
  "claude-opus-4-6": ["claude-sonnet-4-6", "gemini-2.5-flash"],
  "claude-sonnet-4-6": ["gemini-2.5-flash"]
}

The chain resets after a successful response.

Category Routes

Route task categories to specific lenses and models. Configured under lenses.categoryRoutes:

"lenses": {
  "categoryRoutes": {
    "security": { "lens": "focus", "model": "claude-opus-4-6" },
    "testing": { "lens": "craft", "model": "claude-sonnet-4-6" },
    "documentation": { "lens": "scan", "model": "gemini-2.5-flash" }
  }
}

Default routes are built in. Overrides merge with defaults.

Complexity Routing

Automatic model selection based on estimated task complexity. Configured under lenses.complexity:

"lenses": {
  "complexity": {
    "enabled": true,
    "simpleModel": "claude-haiku-4-5",
    "standardModel": "claude-sonnet-4-6",
    "complexModel": "claude-opus-4-6"
  }
}

When enabled, Oculus classifies each query's complexity and routes to the appropriate model tier.

Skill Triggers

Keyword-based skill context injection. When user input matches trigger keywords, skill context is injected into the system prompt.

"skillTriggers": [
  {
    "keywords": ["deploy", "release", "ci"],
    "skill": "deployment",
    "context": "Use CI/CD best practices"
  }
]

Built-in triggers are always active. Custom triggers are additive.

Orchestration

Ralph loop state files:

• .oculus/prd.json — PRD with stories and acceptance criteria
• .oculus/progress.txt — Append-only learnings log

CLI flags:

oculus --ralph "task description"    # Start ralph loop
oculus --plan "task description"     # Start consensus planning

Debug Mode

Enable centralized debug logging:

# Via CLI flag
oculus --debug

# Via environment variable
export CLAUDE_DEBUG=1

Outputs provider communication, tool dispatch, and routing decisions to stderr.