Skip to content

Personal AI, On Personal Devices

Python

Docs/onboarding feedback mac (#290)

Robby Manihanideabda0c4b23
diff --git a/README.md b/README.md
index 3151cf62..7062a916 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,7 @@ You also need a local inference backend: [Ollama](https://ollama.com), [vLLM](ht
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync
+uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml # required for memory + security features
uv run jarvis init
# 2. Start Ollama and pull a model
@@ -82,9 +83,11 @@ uv run jarvis ask "What is the capital of France?"
Install any preset with one command:
```bash
-jarvis init --preset morning-digest-mac # or any preset below
+uv run jarvis init --preset morning-digest-mac # or any preset below
```
+> Prefix every `jarvis ...` invocation with `uv run`, or activate the venv first (`source .venv/bin/activate`) so plain `jarvis ...` works for the rest of your shell session.
+
| Preset | Use Case | What it does |
|--------|----------|-------------|
| `morning-digest-mac` | Daily Briefing (Mac) | Spoken briefing from email, calendar, health, news with Jarvis voice |
@@ -97,14 +100,14 @@ jarvis init --preset morning-digest-mac # or any preset below
```bash
# Example: Morning Digest on Mac
-jarvis init --preset morning-digest-mac
-jarvis connect gdrive # one OAuth flow covers Gmail, Calendar, Tasks
-jarvis digest --fresh # generate and play your first briefing
+uv run jarvis init --preset morning-digest-mac
+uv run jarvis connect gdrive # one OAuth flow covers Gmail, Calendar, Tasks
+uv run jarvis digest --fresh # generate and play your first briefing
# Example: Deep Research
-jarvis init --preset deep-research
-jarvis memory index ./docs/ # index your documents
-jarvis ask "Summarize all emails about Project X"
+uv run jarvis init --preset deep-research
+uv run jarvis memory index ./docs/ # requires the Rust extension — see Setup above
+uv run jarvis ask "Summarize all emails about Project X"
```
### Skills
diff --git a/docs/getting-started/macos.md b/docs/getting-started/macos.md
index 67a6fe1b..427605a8 100644
--- a/docs/getting-started/macos.md
+++ b/docs/getting-started/macos.md
@@ -22,6 +22,7 @@ elsewhere — and is suitable for both Apple Silicon and Intel Macs.
| Tool | Purpose |
|------|---------|
+| Xcode Command Line Tools | Apple's compiler toolchain — required by Homebrew, Rust, and `git` |
| Homebrew | macOS package manager — installs everything else |
| uv | Python version and dependency manager |
| Git | Clones the OpenJarvis repo |
@@ -35,6 +36,27 @@ elsewhere — and is suitable for both Apple Silicon and Intel Macs.
## Step-by-Step Installation
+### Step 0 — Install Xcode Command Line Tools
+
+On a fresh Mac, you need Apple's developer command line tools before anything else
+(`git`, `cc`, build headers). Install them with:
+
+```bash
+xcode-select --install
+```
+
+A GUI installer will pop up — accept and let it finish. If the tools are already
+installed the command instead prints
+`xcode-select: error: command line tools are already installed, use "Software Update" to install updates`
+and exits non-zero, which is fine — you can move on.
+
+!!! note "Homebrew will ask too"
+ Step 1's Homebrew installer also requests the Command Line Tools if it doesn't see
+ them. Running `xcode-select --install` upfront avoids the second prompt and confirms
+ the tools landed correctly.
+
+---
+
### Step 1 — Install Homebrew
Homebrew is the standard macOS package manager. Everything else in this guide is installed
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 7603598b..1f8c7102 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -7,6 +7,11 @@ search:
# Quick Start
+!!! tip "Running `jarvis` commands"
+ Every `jarvis ...` example below assumes you have either activated the project venv
+ (`source .venv/bin/activate`) or are prefixing each command with `uv run`. A bare
+ `jarvis init --preset ...` from a fresh clone will fail with `command not found`.
+
## What You Can Build
OpenJarvis is a modular AI assistant framework. Here's what developers build with it:
@@ -30,6 +35,13 @@ OpenJarvis is a modular AI assistant framework. Here's what developers build wit
jarvis ask "How do I configure the engine?"
```
+ !!! warning "Requires the Rust extension"
+ `jarvis memory index` and `jarvis memory search` import `openjarvis_rust`. If you
+ skipped the `uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml`
+ step in [Installation](installation.md), these commands fail with
+ `ModuleNotFoundError: No module named 'openjarvis_rust'`. Build the extension
+ once and any preset (including `deep-research`) will work.
+
=== "5-Line Python SDK"
```python