◉ Oculus

Go-native AI coding CLI with multi-model lens architecture.

Built by HowlerOps — achieving feature parity with leading AI coding tools while delivering Go's memory efficiency and startup speed.

Install

# Go (recommended)
go install github.com/howlerops/oculus/cmd/oculus@latest

# npm
npm install -g @howlerops/oculus

# Binary (macOS/Linux/Windows)
# Download from https://github.com/howlerops/oculus/releases

Quick Start

# Interactive REPL (launches TUI)
oculus

# Single prompt (non-interactive)
oculus -p "Explain this codebase"

# With specific model
oculus -m opus -p "Review this PR"

# Permission mode shortcuts
oculus --yolo "Fix all the tests"
oculus --auto-edit "Refactor the auth package"

# Ralph persistence loop
oculus --ralph "Implement auth system"

# Consensus planning
oculus --plan "Design new API layer"

On first run, Oculus will open your browser for OAuth authentication with Anthropic when needed. You can also bring your own provider credentials directly, including ANTHROPIC_API_KEY, OPENAI_API_KEY, LITELLM_BASE_URL, BEDROCK_REGION / BEDROCK_ENDPOINT_FAMILY / BEDROCK_BASE_URL, or GOOGLE_API_KEY / GEMINI_API_KEY.

Features

🔭 Three-Lens Architecture

Oculus routes work through specialized lenses:

• Focus — Reasoning, planning, orchestration
• Scan — File search, codebase exploration, research
• Craft — Code writing, editing, command execution

Each lens can target a different model and provider.

🌐 Multi-Provider Bridges

• Anthropic — Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 (streaming + extended thinking)
• OpenAI — GPT-4o, o3, and any OpenAI-compatible endpoint
• LiteLLM — OpenAI-compatible gateway routing through LITELLM_BASE_URL or settings.providers.litellm
• Bedrock OpenAI-compatible — Amazon Bedrock runtime or mantle OpenAI-compatible endpoints via BEDROCK_REGION/BEDROCK_ENDPOINT_FAMILY, or an explicit BEDROCK_BASE_URL
• Google AI — Native Gemini 2.5 API bridge via the official Go SDK (google.golang.org/genai)
• Ollama — Local models (Llama 3, Mistral, Qwen) via OpenAI-compatible interface
• CLI Bridges — Claude Code CLI, Codex CLI (session continuity + resume), Gemini CLI (best-effort text bridge)

🔄 Orchestration Engine

• Ralph Loop (/ralph or --ralph) — PRD-driven persistence with story tracking, acceptance criteria verification, and evidence-based progress logging
• Boulder Crash Recovery (/resume) — Automatically resume interrupted Ralph sessions with full state restoration
• Consensus Planning (/plan or --plan) — Planner → Architect → Critic review loop (up to 5 rounds)
• Ultrawork — Parallel dispatch with dependency DAG and model tier routing
• 5 Agent Personas — Architect, Critic, Executor, Explorer, Planner (with semi-formal reasoning protocols)
• Smart Model Routing — Complexity-aware model selection with 3-tier routing (Haiku → Sonnet → Opus)
• Category-Based Task Routing — 6 task categories with automatic classification and optimal agent assignment
• Fallback Model Chain — Auto-retry on rate limit with configurable fallback provider sequence
• Wisdom Accumulation (/wisdom) — Cross-task learning that carries insights between sessions
• Skill Auto-Injection — Keyword triggers automatically activate relevant skills (e.g., "autopilot" → autopilot mode)

🚀 Multi-Provider Onboarding

Auto-detects API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY), configured LiteLLM endpoints, Bedrock runtime/mantle OpenAI-compatible endpoints, installed CLIs (Claude, Codex, Gemini), and local Ollama instances. Works without Anthropic — any provider can be primary. The /setup command recommends optimal lens configuration based on what's available.

🧠 Context Management

Episode-based compaction with LCM dual-threshold engine:

• Below 70%: Zero overhead
• 70-90%: Async compaction between turns
• Above 90%: Blocking compaction with TF-IDF keyword extraction

Prompt caching via ephemeral cache control blocks for identity, tool descriptions, and user context.

🛠 Built-in Tools (32 packages)

Bash, File Read/Write/Edit, Glob, Grep, Agent spawning, WebSearch, WebFetch, REPL, Notebook editing, LSP (gopls), MCP (client/auth/ListResources/ReadResource), Task/Team/TodoWrite, Cron scheduling, Plan mode, Brief mode, Worktree, Config, Sleep, ToolSearch, SyntheticOutput, RemoteTrigger, AskUser, Skill runner, SendMessage, PowerShell.

💬 50 Slash Commands

/help, /model, /diff, /commit, /compact, /permissions, /config, /settings, /init, /memory, /plan, /review, /skills, /plugin, /agents, /advisors, /issue, /branch, /add-dir, /copy, /continue, /status, /doctor, /version, /setup, /lsp-install, /upgrade, /security-review, /release-notes, /pr_comments, /feedback, /onboarding, /good, /btw, /terminal-setup, /desktop, /mobile, /install-github-app, /install-slack-app, /backfill-sessions, /break-cache, /cost, /wisdom, /categories, /triggers, and session commands (/login, /logout, /resume, /session).

🖥 Full Terminal UI (36+ files + components) — Charm v2

Built on the Charm v2 ecosystem (bubbletea v2, lipgloss v2, bubbles v2):

• Interactive model picker with provider-grouped display and pricing info
• Interactive /settings page with tabbed interface for runtime configuration
• Permission mode picker at startup (Ask, Auto Edit, Don't Ask, Bypass All, Plan)
• Inline permission dialogs with queued approval workflow
• Loading animations with mini-dot spinners and elapsed time tracking
• Color-coded tool call badges with per-tool progress tracking
• Markdown rendering with syntax highlighting (glamour)
• Multi-line input with Ctrl+R history search and autocomplete dropdown
• Scrollable viewport, task panel, status bar, context bar, help bar
• Git branch display in status bar
• Hierarchical tree view for file path display
• Runtime permission management with /permissions switching
• Mouse toggle (Ctrl+M) for easy copy/paste
• Vim mode, keybindings, diff viewer
• Splash screen with ASCII branding

🔒 Security & Permissions

• 5 Permission Modes: Ask (safe default), Auto Edit (auto-approve edits), Don't Ask (allow most), Bypass All (YOLO), Plan (read-only)
• Interactive mode picker at startup with runtime switching via /permissions
• Permission pre-flight for team orchestration — validates permissions before dispatching work
• CLI shortcuts: --yolo and --auto-edit flags
• Bash command safety analysis (24 dangerous patterns)
• Rule-based permission system with glob matching and priority (deny > ask > allow)
• Cost ceiling and step limits (/cost) with real-time warnings when approaching thresholds
• OAuth PKCE authentication with keychain storage
• SSRF guard on HTTP hooks

🐛 Debugging & Testing

• --debug flag with centralized structured logging
• E2E testing harness — tmux-based test runner for full TUI integration tests

🔌 Extensibility

• Plugins — Loader, manager, marketplace integration
• Skills — Extensible skill system with loader
• Hooks — Lifecycle hooks with HTTP and UI integration
• MCP — Full Model Context Protocol client support

Configuration

Config directory: ~/.oculus/ (auto-migrates from ~/.claude/)

OCULUS.md

Create project-specific instructions:

# Project Instructions

- Use pnpm, not npm
- Run tests with `go test ./...`
- Follow conventional commits

settings.json

{
  "model": "gemini-2.5-flash",
  "defaultMode": "default",
  "providers": {
    "litellm": { "baseURL": "http://localhost:4000/v1", "apiKeyEnv": "LITELLM_API_KEY" },
    "bedrock": { "region": "us-east-1", "endpointFamily": "runtime", "apiKeyEnv": "BEDROCK_API_KEY" }
  },
  "lenses": {
    "focus": { "model": "claude-opus-4-6", "provider": "anthropic" },
    "scan": { "model": "gemini-2.5-flash", "provider": "gemini" },
    "craft": { "model": "codex", "provider": "codex" }
  }
}

Architecture

cmd/oculus/          CLI entry point (cobra)
pkg/
├── api/             Anthropic streaming client (retry, errors, provider)
├── auth/            OAuth PKCE + keychain + onboarding + trust
├── bridge/          Multi-provider abstraction (anthropic, openai-compatible, litellm, gemini, cli, ollama)
├── commands/        50 slash commands (builtins, login, resume)
├── config/          Settings, model defs, env, validation, cache, merge
├── constants/       Models, limits, OAuth, shared constants
├── context/         Git context, OCULUS.md/CLAUDE.md loader, system prompt (with cache control)
├── hooks/           Hook engine (lifecycle, HTTP, settings, UI)
├── lens/            Focus/Scan/Craft routing (manager, router, worker)
├── memdir/          In-memory directory abstraction
├── migrations/      Config migration helpers
├── orchestration/   Ralph loop, consensus planning, ultrawork, agent personas
├── plugins/         Plugin loader, manager, marketplace
├── query/           Conversation loop + tool dispatch engine (session tracking)
├── services/        16 service packages:
│   ├── analytics, agentsummary, bridge, compact, cost, episodes,
│   │   history, mcp, memory, notifications, plugins, policylimits,
│   │   ratelimit, sessions, tokencount, toolsummary
├── skills/          Skill loader
├── state/           State store + selectors
├── task/            Background task management
├── tool/            Tool registry + dispatch
├── tools/           32 tool implementations (each in own package)
├── tui/             Bubbletea v2 terminal UI (36+ files)
│   ├── model, init, update, view, messages, handlers
│   ├── permission, permission_mode_picker, permissions_runtime
│   ├── statusbar, contextbar, taskpanel, viewport, progress
│   ├── input, autocomplete, keybindings, vim, markdown
│   ├── toolcall, diff, modelpicker, settings, splash, helpbar, treeview
│   └── components/
├── types/           Shared types (messages, tools, permissions, hooks, IDs)
└── utils/           Utility packages:
    ├── array, bash, claudemd, filestate, format, git,
    │   log, messages, permissions, platform, theme

Documentation

Full docs: howlerops.github.io/oculus

License

MIT © HowlerOps