Cosmo

Set up Cosmo

A few minutes, start to finish. Do it step by step, or jump to the one-command script at the bottom.

Step by step

  1. 1 · Check the prerequisites

    You'll need Node.js 20 or newer, npm (ships with Node), and git. Cosmo is built for macOS — it runs elsewhere, but voice and AppleScript features are macOS-only.

    node -v   # should print v20.x or higher
npm -v
git --version

    No Node? Grab the LTS from nodejs.org (on macOS: brew install node).

  2. 2 · Get the code

    Clone the repository, then move into it. (The repo link is handed to you when you grab Cosmo — hit Get Cosmo.)

    git clone <your-cosmo-repo-url> cosmo
cd cosmo

  3. 3 · Install dependencies

    npm install

  4. 4 · Build

    npm run build

  5. 5 · Launch

    Start Cosmo in development mode. His eyes appear, always on top.

    npm run dev

  6. 6 · Configure (in-app)

    Click the gear ⚙ to open Setup, then:

    • Pick your AI provider + model — OpenAI, Anthropic, Gemini, Grok, DeepSeek, Groq, Cerebras, or local Ollama.
    • Paste your API key — it's encrypted in your OS keychain, never stored as plaintext.
    • Choose your voice and finish onboarding.

    Then say "Cosmo" or tap the mic and say hi. 👋

  7. 7 · Optional — a fully local brain

    Want zero cloud? Install Ollama and pull a small model:

    ollama pull qwen2.5:7b

    Then choose Ollama as the provider in Setup.

  8. 8 · Optional — build an app you can share

    npm run dist   # produces a .dmg in dist/

…or the one-command way

A single script that checks prerequisites, fetches the code, installs, builds, and offers to launch. Works on macOS, Linux, and Windows (via Git Bash or WSL).

Already cloned the repo? From inside it:

./setup.sh

Starting from scratch? One line:

curl -fsSL https://raw.githubusercontent.com/<your-user>/cosmo/main/setup.sh | bash

The script is safe to re-run — it updates an existing clone instead of starting over, and never overwrites your settings.

Get the repo link →