Quickstart

Get Jarvis running in under 5 minutes

Quickstart Guide

This guide will get you from zero to a working Jarvis installation in under 5 minutes.

This quickstart assumes you’re on macOS 13+ with Xcode Command Line Tools already installed.

Prerequisites Check

Before you begin, verify you have:

1. macOS 13 or later

   Check your version with:

   sw_vers -productVersion
   
2. Xcode Command Line Tools

   Install if needed:

   xcode-select --install
   
3. Python 3.10 or newer

   Check your version:

   python3 --version
   

   Install with Homebrew if needed:

   brew install python@3.12
   

One-Command Install

Clone the repository and run the automated setup script:

# Clone Jarvis
git clone https://github.com/your-org/jarvis.git
cd jarvis

# Run setup script
./setup.sh

The setup script will:

1. Create a Python virtual environment (.venv)
2. Install Python dependencies from requirements.txt
3. Build the Swift/Metal application
4. Create the config directory at ~/.config/jarvis/

The initial Swift build may take 2-3 minutes depending on your machine.

Configure Environment

Create a .env file in the project root:

touch .env

Add your API credentials:

.env

CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
GOOGLE_API_KEY=your-gemini-api-key-here  # optional

Keep your .env file secure and never commit it to version control. It contains sensitive API credentials.

Get Your Claude OAuth Token

If you have a Claude Max subscription, run the login script to set up authentication:

./login.sh

This script will:

1. Launch the Claude Code OAuth flow in your browser
2. Extract the access token from macOS Keychain after authentication
3. Automatically write CLAUDE_CODE_OAUTH_TOKEN to your .env file

The OAuth token expires periodically. Re-run ./login.sh whenever the code assistant stops authenticating.

Launch Jarvis

Start the application:

./start.sh

You should see:

• The Metal window opens with the 3D orb
• Console output: JARVIS — Personal AI Assistant
• Status: Metal display active. PTT: Left Control

First Voice Command

Try your first voice interaction:

1. Activate Push-to-Talk

   Hold down Left Control (or Option + Period)

2. Speak a command

   Say: “Help me with code”

   The orb will visualize your audio input as you speak.

3. Release to send

   Release the key when done speaking. Whisper will transcribe your audio locally.

4. AI responds

   A chat panel opens with Claude Opus 4.6 Assistant ready to help:

   Opus 4.6 Assistant 1 ready. Type or speak your request.
   

Try Some Commands

Once the assistant panel is open, try these:

Voice Commands

# Launch games
"Play asteroids"
"Launch kart bros"
"Open minesweeper"

# Open utilities
"New window"          # Spawn another AI assistant panel
"Open chat"           # Launch live chat
"Open localhost:3000" # Open a URL in embedded browser

# Code assistance
"Read main.py"
"Search for TODO in the project"
"Run the tests"

Quick Examples

Example 1: Code Review

1. Activate voice

   Hold Left Control

2. Request review

   Say: “Review the router.py file and suggest improvements”

3. AI analyzes

   The assistant will:

   • Read skills/router.py
   • Analyze the code structure
   • Provide suggestions with inline examples

Example 2: Spawn Multiple Assistants

1. Open first assistant

   Say: “Help me with code”

2. Split window

   Say: “New window” or “Split window”

3. Work in parallel

   Now you have 2 independent AI panels. Ask different questions in each:

   • Panel 1: Frontend work
   • Panel 2: Backend work

   Switch panels by clicking or using voice commands in each.

Example 3: Game Break

1. Open a game

   Say: “Play asteroids” or “Launch kart bros”

2. Invite friends (optional)

   For multiplayer games like Kart Bros, the presence system lets you send invites to online friends.

3. Return to work

   Say: “Close window” or press Escape to exit the game and return to the assistant.

Troubleshooting

Swift build fails

Ensure you have Xcode Command Line Tools:

xcode-select --install

Check Swift version:

swift --version  # Should be 5.9+

Claude assistant not responding

Your OAuth token may have expired. Re-authenticate:

./login.sh

Verify the token in .env:

grep CLAUDE_CODE_OAUTH_TOKEN .env

No audio / voice not working

Check microphone permissions:

1. Open System Settings → Privacy & Security → Microphone
2. Ensure Terminal (or your terminal app) has microphone access

Test audio device:

python -c "import sounddevice; print(sounddevice.query_devices())"

Gemini skills disabled

This is normal if GOOGLE_API_KEY is not set. Voice routing will still work with Claude-only mode.

To enable Gemini skills:

1. Get an API key from Google AI Studio
2. Add to .env: GOOGLE_API_KEY=your-key-here
3. Restart Jarvis

View Logs

If something isn’t working, check the logs:

# Python logs
tail -f jarvis.log

# Or ask Jarvis to copy logs to clipboard
# In the assistant panel, say: "show logs"

Next Steps

Installation Guide

Deep dive into configuration and advanced setup

Skills & Commands

Explore all available voice commands and skills

Plugin System

Build custom panels and tools

Manual

Complete technical reference

Enjoying Jarvis? Star the project on GitHub and share your vibe coding sessions!