Skip to main content

​
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 [email protected]

​
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: 
# 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

Ensure you have Xcode Command Line Tools:
xcode-select --install
Check Swift version:
swift --version  # Should be 5.9+
Your OAuth token may have expired. Re-authenticate:
./login.sh
Verify the token in .env:
grep CLAUDE_CODE_OAUTH_TOKEN .env
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())"
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!

Build docs developers (and LLMs) love

Get started for freeTalk to us