Documentation

First Steps

Get OScar running in under five minutes. You'll install the app, connect a language model, and send your first message.

01 — Prerequisites

What you need before starting

OScar requires macOS 13 Ventura or later and an API key for at least one supported LLM provider.

Supported providers: Anthropic (Claude), OpenAI, Google (Gemini). The key is set as an environment variable — OScar never stores it on disk.

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."
# or
export GOOGLE_API_KEY="..."

Add the export to your shell profile (~/.zshrc, ~/.bash_profile) so it persists across reboots.

02 — Install OScar

Download and launch the app

01.

Download the latest release

Grab the OScar.app.zip from the Releases page on GitHub. Unzip and move OScar.app to your Applications folder.

02.

Launch OScar

Double-click OScar.app. A small icon appears in the menu bar — OScar runs entirely as a menu bar app with no Dock entry.

03.

Install cagent via the Settings UI

Open Settings (click the menu bar icon → Settings). On the Update tab, click Install cagent. OScar downloads and installs the cagent binary automatically via Homebrew.

Manual install: If you prefer, run brew install docker/tap/cagent in Terminal. Requires Homebrew.
03 — Create an agent config

Your first agent.yaml

cagent is driven by a YAML configuration file that declares which model and tools the agent can use. OScar ships with a template you can generate from the command line:

make init-config
# writes ~/.config/oscar/agent.yaml

A minimal config looks like this:

model: claude-sonnet-4-5
tools:
  - shell
  - filesystem

Point OScar at your config in Settings → General → Agent Config Path. See the Agents page for the full reference.

04 — Send your first message

Open Quick Entry and ask something

01.

Open Quick Entry

Press ⌥⌘O (Option + Command + O) from anywhere. A floating window appears — type your question and press Return.

02.

Watch the stream

A conversation window opens. Tokens stream in real time. Tool calls (shell commands, file reads) appear inline as they execute.

03.

Continue the conversation

Type follow-up messages at the bottom of the window. Sessions persist — find them by clicking the menu bar icon or via Spotlight (⌘Space).

Next

Where to go from here

Configure a custom agent with specific tools and models on the Agents page. Learn about keyboard shortcuts and Spotlight integration on the Usage page. Run agents in an isolated Docker environment on the Sandboxes page.