Installation
Oculus ships as a single statically-linked binary with no runtime dependencies. Pick the install path that suits your environment.
Via go install
Requires Go 1.22 or later. This is the canonical install path and always pulls the latest stable release.
go install github.com/howlerops/oculus/cmd/oculus@latestThe binary is placed in $GOPATH/bin (usually ~/go/bin). Make sure that directory is on your $PATH:
export PATH="$PATH:$(go env GOPATH)/bin"Via Homebrew
Recommended for macOS and Linux users who prefer a managed install with automatic updates.
brew install howlerops/tap/oculusTo upgrade later:
brew upgrade oculusVia npm
For Node.js developers who want Oculus in a project's dev dependencies or alongside frontend tooling.
# Global install
npm install -g @howlerops/oculus
# Or add to a project
npm install --save-dev @howlerops/oculus
npx oculusRun oculus --version to confirm the binary is on your PATH and print the version string.
Authentication — First Run
On first launch Oculus checks for credentials and walks you through the auth flow if none are found.
The OAuth flow uses PKCE (Proof Key for Code Exchange) — no client secret is ever stored on disk. After consent, the access token is placed in your OS keychain (Keychain on macOS, libsecret on Linux, Credential Manager on Windows).
Using an API Key Instead
If you prefer explicit API key auth, set the appropriate environment variable before launching:
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
# OpenAI-compatible provider
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.openai.com/v1" # optional, defaults to OpenAI
# LiteLLM gateway
export LITELLM_BASE_URL="http://localhost:4000/v1"
export LITELLM_API_KEY="..."
# Bedrock OpenAI-compatible endpoints
export BEDROCK_REGION="us-east-1"
export BEDROCK_ENDPOINT_FAMILY="runtime" # or mantle
export BEDROCK_API_KEY="..."
# optional explicit override
# export BEDROCK_BASE_URL="https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1"
# Google AI / Gemini native bridge
export GOOGLE_API_KEY="..."
# or
export GEMINI_API_KEY="..."
# Ollama (no key required — just set the host)
export OLLAMA_HOST="http://localhost:11434"Environment variables always take precedence over the keychain. You can also persist them in ~/.oculus/settings.json — see the Configuration reference.
Interactive REPL
Running oculus with no arguments opens the interactive REPL — a full TUI with history, markdown rendering, and tool-execution output.
oculusKey bindings in the REPL:
| Key | Action |
|---|---|
Enter | Submit message |
Shift+Enter | Insert newline |
Ctrl+C | Cancel current generation / quit if idle |
Ctrl+L | Clear screen |
Up / Down | Navigate message history |
Tab | Autocomplete slash command |
Esc (vim mode) | Enter normal mode |
Type /help at the prompt to see all 44 slash commands. See the full Commands Reference for descriptions.
Type /settings to open the full-screen settings editor. Configure models, permissions, safeguards, routing, and skill triggers without touching JSON files.
Print Mode
Use the -p / --print flag to send a single prompt and print the response to stdout — useful for scripts, pipes, and one-off queries.
# Basic one-shot query
oculus -p "What does this function do?" < pkg/auth/token.go
# Pipe output
oculus -p "Summarise this diff" < <(git diff HEAD~1)
# Choose a lens
oculus -p "Scan the repo for unused exports" --lens scan
# Choose a specific model
oculus -p "Refactor with generics" --model gpt-4o --provider openai
# Output raw text (no TUI chrome)
oculus -p "Generate a Makefile" --raw > MakefileFile-writing tools are disabled by default in print mode. Pass --allow-writes to enable them. Bash execution still prompts for confirmation unless --yes is set.
OCULUS.md — Project Instructions
Create an OCULUS.md file in your project root (or any parent directory) to give Oculus persistent context about your codebase. It is loaded automatically on every session start.
# OCULUS.md
## Project: acme-api
Go 1.22 REST API using Chi router and sqlc for database access.
## Conventions
- Use `errors.New` from `pkg/errors`, not the stdlib
- All handlers live in `internal/handlers/`
- Tests use `testify/require`, never `assert`
- Run `make lint` before committing
## Out of scope
- Do not modify `vendor/` or `generated/`
- Do not alter migration files; create new ones instead
## Useful commands
- `make dev` — hot-reload dev server
- `make test` — full test suite
- `make lint` — golangci-lintOculus also reads CLAUDE.md files if OCULUS.md is absent, making it easy to adopt Oculus in projects that already have one.
Orchestration Modes
# Ralph persistence loop - won't stop until done
oculus --ralph "fix all failing tests and add missing coverage"
# Consensus planning - multi-agent plan review
oculus --plan "redesign the authentication system"
# Or use slash commands in the TUI
/ralph add pagination to the API
/plan migrate from SQLite to PostgreSQLNext Steps
Explore Features
Lens system, 40 tools, MCP support, episode context, and more.
Configuration
Tune settings.json, environment variables, hooks, and per-lens model assignment.
Commands Reference
All 54 slash commands with descriptions and usage examples.
Architecture
Deep dive into the package structure, lens routing, and episode store.