Features

Built-in Tools

Oculus ships with a broad built-in tool surface covering core software development workflows:

• File Operations — Read, Write, Edit (exact string replacement), Glob (pattern match), Grep (ripgrep-powered search)
• Shell — Bash execution with timeout, background mode, and security analysis
• Web — WebSearch (real-time), WebFetch (URL content extraction)
• Orchestration — Agent (subagent spawning), TeamCreate/Delete/SendMessage, TaskCreate/Update/List
• Planning — EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree
• Code Intelligence — LSP, NotebookEdit, ToolSearch, Skill invocation
• Configuration — Config, AskUserQuestion, TodoWrite

Multi-Model Lens System

Oculus routes work through three specialized lenses, each configurable to a different model and provider:

Use Opus for Focus, Sonnet for Scan, and a local Ollama model for Craft — or any combination that fits your workflow.

Provider Options

Context Management

Episode-based compaction with an LCM dual-threshold engine:

• Below τ_soft (70%) — Zero overhead, no compaction.
• τ_soft to τ_hard (70–90%) — Async compaction between turns.
• Above τ_hard (90%) — Blocking compaction before the next API call.

TF-IDF keyword extraction preserves the most important content during compaction so long sessions stay coherent.

Terminal UI

• Permission dialog (approve / deny / always-allow)
• Markdown rendering with syntax highlighting (glamour)
• Tool call badges with colored display
• Per-tool progress spinners
• Multi-line input with Ctrl+R history search
• Scrollable viewport with mouse wheel
• Task panel, status bar, context usage bar
• Vim mode with motions and operators

Settings Page

Interactive full-screen settings editor accessible via /settings. Five tabbed sections:

• Models — Configure Focus, Scan, and Craft lens models
• Permissions — Set default permission mode (ask, auto-edit, yolo, plan)
• Safeguards — Cost ceiling, max steps, max query duration
• Routing — Complexity-based model routing (simple, standard, complex)
• Skills — View and manage skill trigger keywords

Navigate with Tab / arrows, edit inline, save with Ctrl+S.

Cost Ceiling & Safeguards

Session-level spending and execution guardrails:

• Cost Ceiling — Set a maximum dollar amount per session. Oculus halts when the ceiling is reached.
• Max Steps — Limit the number of tool-call iterations per query (default: 100).
• Max Query Duration — Time-box individual queries (e.g. 5m, 30s).

Fallback Chains

Define ordered fallback models for automatic failover. When the primary model returns an error or is unavailable, Oculus transparently retries with the next model in the chain.

• Configured per-model in settings.json under fallback_models
• Automatic retry with next fallback on provider errors
• Chain resets on successful response

Security

• Bash command safety analysis (24 dangerous patterns)
• Full permission system (allow / deny / ask rules with glob matching)
• Mode-based defaults (default, acceptEdits, bypassPermissions, plan)
• OAuth PKCE authentication with macOS Keychain storage
• SSRF guard on HTTP hooks

Permission Pre-flight

Before executing a multi-step plan, Oculus can present a pre-flight summary of all permissions that will be needed. Approve once upfront instead of getting prompted for each individual tool call during execution.

Category Routing

Route task categories to specific lenses and models. Categories like security, testing, documentation, and refactoring can each target a different lens/model combination.

• Default routes built in; override via lenses.categoryRoutes in settings
• Pattern matching on user input to detect task category
• Pairs with lens routing for fine-grained model selection

Smart Model Routing (Complexity)

Automatically route to different models based on estimated task complexity:

• Simple — Quick lookups, short answers → routes to a fast/cheap model (e.g. Haiku)
• Standard — Normal coding tasks → routes to the default model (e.g. Sonnet)
• Complex — Architecture, deep analysis → routes to the strongest model (e.g. Opus)

Configure via lenses.complexity in settings or the Settings page Routing tab.

Skill Triggers

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

• Built-in triggers for common patterns (testing, deployment, security, etc.)
• Custom triggers configurable in settings.json under skillTriggers
• Each trigger defines keywords, a skill name, and injection context

Orchestration Engine

Native orchestration patterns for complex multi-step tasks:

• Ralph Loop (/ralph or --ralph) — PRD-driven persistence loop. Creates a Product Requirements Document, iterates through stories, verifies acceptance criteria, tracks progress. Doesn't stop until every story passes.
• Consensus Planning (/plan or --plan) — Multi-agent planning with Planner → Architect → Critic loop. Up to 5 rounds until consensus. Produces a verified implementation plan.
• Ultrawork — Parallel task dispatch with dependency DAG. Routes tasks to appropriate model tiers (Haiku for lookups, Sonnet for standard work, Opus for complex analysis).
• Specialized Agents — 5 built-in personas: Architect (design review), Critic (quality evaluation), Executor (implementation), Explorer (codebase search), Planner (task decomposition).

Boulder Recovery

Crash-resilient state for Ralph loops. If a session is interrupted mid-loop, Oculus persists boulder state to .oculus/boulder.json and can resume from the last checkpoint on restart.

Wisdom Store

Per-project pattern learning. Oculus records lessons and patterns encountered during sessions in .oculus/wisdom.json. These entries are loaded in future sessions to avoid repeating mistakes and reinforce successful approaches.

Multi-Provider Onboarding

Interactive setup wizard that auto-detects your environment:

• Scans for API keys (Anthropic, OpenAI, Google AI)
• Detects installed CLIs (Claude, Codex, Gemini)
• Checks for a local Ollama instance
• Recommends optimal lens configuration based on what's available
• Works without Anthropic — any provider can be primary

Debug Mode

Enable with the --debug flag or CLAUDE_DEBUG=1 environment variable. Centralized logging output for diagnosing provider communication, tool dispatch, and routing decisions.