### Install MCP Proxy for Home Assistant

Source: https://github.com/isair/jarvis/blob/main/README.md

Command to install the mcp-proxy tool, required for Home Assistant integration.

```bash
uv tool install git+https://github.com/sparfenyuk/mcp-proxy
```

--------------------------------

### Install CUDA Libraries for GPU Acceleration

Source: https://github.com/isair/jarvis/blob/main/README.md

Install NVIDIA CUDA libraries for GPU acceleration on Windows. This is typically handled by the Windows installer, but can be done manually for development.

```bash
pip install nvidia-cublas-cu12 nvidia-cudnn-cu12
```

--------------------------------

### setup_location_database

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/utils/location.spec.md

Checks for the existence of the location database and provides setup instructions if it is missing.

```APIDOC
## setup_location_database()

### Description
Checks the status of the location database. If the database is not found, it prints instructions on how to set it up.

### Returns
- **bool** - Returns a boolean indicating the success or failure of the check and potential setup guidance.
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/settings_window.spec.md

Illustrates the structure for configuring MCP servers, including name, command, arguments, and environment variables. This section is not metadata-driven and uses a custom page.

```python
# Example structure for MCP server configuration
# name: str
# command: str
# args: str (space-separated)
# env_vars: dict[str, str] (KEY=VALUE pairs)
```

--------------------------------

### Get System Prompts

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/prompts/prompts.spec.md

The `get_system_prompts` function retrieves the appropriate set of prompt components tailored to the specified model size. These components guide the model's behavior, especially in tool usage.

```APIDOC
## get_system_prompts

### Description
Retrieves system prompts tailored to the specified model size.

### Signature
`get_system_prompts(model_size: ModelSize) -> PromptComponents`

### Parameters
#### Path Parameters
- **model_size** (ModelSize) - Required - The size category of the model (e.g., SMALL, LARGE).
```

--------------------------------

### Agentic Flow: Simple Single-Tool

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/reply.spec.md

Example of a user query that triggers a single tool call by the LLM. Demonstrates a straightforward interaction where the LLM directly uses a tool to answer the user.

```text
User: "What's the weather in London?"
Turn 1: LLM → {content: "", tool_calls: [{function: {name: "webSearch", arguments: {query: "London weather today"}}}]}
Turn 2: LLM → {content: "It's 18°C and sunny in London today with light winds."}
```

--------------------------------

### Configure MCP Server Integration

Source: https://github.com/isair/jarvis/blob/main/README.md

Integrate Jarvis with external tools using MCP servers. This example shows how to configure a GitHub integration, specifying the command, arguments, and environment variables like a GITHUB_TOKEN.

```json
{
  "mcps": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}
```

--------------------------------

### Configure Home Assistant MCP Server

Source: https://github.com/isair/jarvis/blob/main/README.md

Configuration for the Home Assistant MCP server. Ensure you have a Long-lived Access Token and have installed the mcp-proxy.

```json
{
  "mcps": {
    "home_assistant": {
      "command": "mcp-proxy",
      "args": ["http://localhost:8123/mcp_server/sse"],
      "env": { "API_ACCESS_TOKEN": "YOUR_TOKEN" }
    }
  }
}
```

--------------------------------

### Echo Detection Example

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/listening/listening.spec.md

Illustrates a scenario where TTS output is followed by user input. The example shows how both fuzzy matching and an intent judge process the transcriptions to identify echoes and real speech.

```text
TTS: "The weather is sunny and 72 degrees"
TTS finished: 12:30:14

Transcript:
[12:30:15] "The weather is sunny and 72 degrees" ← Echo (fuzzy score 100, rejected)
[12:30:18] "Ni hao" ← Real speech (fuzzy score < 70, sent to judge)

Judge output: {"directed": true, "query": "Ni hao", "reasoning": "New speech directed at assistant"}
```

--------------------------------

### Jarvis Browser Automation

Source: https://github.com/isair/jarvis/blob/main/README.md

Jarvis can automate browser actions, such as opening websites, based on user commands. This example shows Jarvis opening YouTube.

```text
  📝 Heard: "Open YouTube Jarvis."
  🧠 Intent (wake word): directed → "open YouTube"

✨ Working on it: open YouTube
  💬 Generating response...

🤖 Jarvis
I have opened YouTube for you.
```

--------------------------------

### Detect Model Size and Get System Prompts

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/reply.spec.md

Detects the size of the Ollama chat model (SMALL or LARGE) and retrieves the corresponding system prompts. This is crucial for tailoring agentic behavior, especially for smaller models that require more explicit guidance.

```python
from jarvis.reply.prompts import detect_model_size, get_system_prompts

model_size = detect_model_size(cfg.ollama_chat_model)  # SMALL or LARGE
prompts = get_system_prompts(model_size)
```

--------------------------------

### Listener Startup and Model Warmup Output

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/listening/listening.spec.md

This output shows the listener initializing and warming up its models. It indicates which models are being loaded and their readiness status. The 'Listening!' message signifies that the listener is ready for user input.

```text
  🔥 Warming up models...
     🎤 Whisper 'small' loaded on cpu
     💬 Chat model 'llama3.1' ready
     🧠 Intent judge 'gemma4:e2b' ready
🎙️  Listening! Try:
      "How's the weather, Jarvis?"          ← when location is known
      "How's the weather in [your city], Jarvis?"  ← when location is disabled or not configured
      "I just ate a Big Mac, Jarvis."
      "What are you thinking, Jarvis?"
      "What do you know about me, Jarvis?"
```

--------------------------------

### Jarvis Desktop App Startup Flow Diagram

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/desktop_app.spec.md

Visual representation of the Jarvis Desktop App's startup sequence, including dependency checks and user interaction points.

```mermaid
flowchart TD
    A[Launch App] --> B[Single Instance Check]
    B -->|Already Running| B2[Show Conflict Dialog]
    B2 -->|User: Exit| Z[Exit]
    B2 -->|User: Kill Existing| B3[Terminate Old Instance]
    B3 --> B4[Retry Lock]
    B4 -->|Failed| Z
    B4 -->|OK| C
    B -->|OK| C[Show Splash Screen]
    C --> D{Setup Completed Before?}
    D -->|No| E[Show Setup Wizard]
    D -->|Yes| F{Ollama Running?}
    E --> F
    F -->|No| G[Auto-Start Ollama]
    G --> H[Wait for Ollama]
    H --> I{Started?}
    I -->|No, Timeout| J[Continue Anyway]
    I -->|Yes| K[Check Model Support]
    F -->|Yes| K
    J --> K
    K -->|Unsupported| L[Show Warning Dialog]
    K -->|OK| M[Initialize Tray]
    L --> M
    M --> N[Start Daemon Thread]
    N --> O[Close Splash]
    O --> P[Enter Qt Event Loop]
```

--------------------------------

### Multi-person conversation example

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/listening/listening.spec.md

Illustrates how the intent judge synthesizes a complete query from a multi-person conversation, resolving vague references and context.

```text
[12:28:30] Person A: "I wonder what the weather will be like tomorrow"
[12:28:45] Person B: "Yeah, we should check before planning the picnic"
[12:29:00] Person A: "Jarvis, what do you think?"

The intent judge synthesizes: "what do you think about the weather tomorrow for the picnic"
```

--------------------------------

### Prompt Components Structure

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/prompts/prompts.spec.md

Defines the structure of `PromptComponents`, a dataclass containing various prompt strings used to guide the language model's responses and actions.

```APIDOC
## PromptComponents

### Description
A data structure holding all prompt strings for a given model size.

### Fields
- **asr_note** (str) - Handles voice transcription errors.
- **inference_guidance** (str) - Encourages inference over clarification.
- **voice_style** (str) - Defines the desired response style (concise, conversational).
- **tool_incentives** (str) - Guides when and how aggressively to use tools.
- **tool_guidance** (str) - Rules for handling tool results, including anti-confabulation.
- **tool_constraints** (str) - Explicit behavioral rules for tool usage.
```

--------------------------------

### Loop Integration: Tool Allow-list Expansion

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/tools/builtin/tool_search.spec.md

Illustrates how toolSearchTool integrates into the agentic loop's allow-list. The initial routing provides 'base_tools', and the loop exposes 'base_tools' plus 'stop' and 'toolSearchTool'. Invoking toolSearchTool merges newly found tools into the allow-list for subsequent turns.

```text
allow-list = <router's picks> + stop + toolSearchTool
```

--------------------------------

### Configure Task-list Planner Settings

Source: https://github.com/isair/jarvis/blob/main/README.md

Control the task-list planner's behavior, including enabling/disabling it, specifying a model for planning, and setting a timeout for LLM calls. The planner decomposes multi-step queries into sub-tasks for improved reliability, especially with small models.

```json
{
  "planner_enabled": true,
  "planner_model": "",
  "planner_timeout_sec": 6.0
}
```

--------------------------------

### Jarvis Echo Detection

Source: https://github.com/isair/jarvis/blob/main/README.md

Jarvis is designed to ignore its own speech to prevent feedback loops. This example shows Jarvis detecting and filtering its previous output as echo.

```text
🤖 Jarvis
I have opened YouTube for you.

👂 Listening for follow-up (3s)...
  📝 Heard: "I have opened YouTube for you."
  🔇 Heard (echo): "i have opened youtube for you."
💤 Returning to wake word mode
```

--------------------------------

### Jarvis Personalized News Search

Source: https://github.com/isair/jarvis/blob/main/README.md

Jarvis can search for news tailored to user interests by utilizing memory and web search tools. This example demonstrates a personalized news search.

```text
  📝 Heard: "What are some news from today that might interest me Jarvis?"
  🧠 Intent (wake word): directed → "what are some news from today that might interest me"

✨ Working on it: what are some news from today that might interest me
  🧰 Tool: searchMemory…
  🧰 Tool: webSearch…
  💬 Generating response...

🤖 Jarvis
Here's a quick snapshot of today's headlines...
```

--------------------------------

### Build Initial System Message with Model Size

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/prompts/prompts.spec.md

Detects the model size and retrieves corresponding system prompts to build the initial system message. Ensure `cfg.ollama_chat_model` is configured.

```python
from jarvis.reply.prompts import detect_model_size, get_system_prompts

model_size = detect_model_size(cfg.ollama_chat_model)
prompts = get_system_prompts(model_size)

# Build system message from prompts.to_list()
```

--------------------------------

### Jarvis Natural Wake Word Placement

Source: https://github.com/isair/jarvis/blob/main/README.md

Jarvis can be activated by its wake word placed naturally within a sentence. This example shows Jarvis responding to a request for a discussion topic.

```text
  📝 Heard: "Give me a random topic to discuss Jarvis."
  🧠 Intent (wake word): directed → "give me a random topic to discuss"

✨ Working on it: give me a random topic to discuss
  💬 Generating response...

🤖 Jarvis
How about the Fermi Paradox? Given the vast number of stars...
```

--------------------------------

### Sounddevice Query for Input Devices

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/settings_window.spec.md

Demonstrates how to query available input-capable sound devices using the sounddevice library. This is used to populate the device dropdown in the Voice Input tab.

```python
sounddevice.query_devices()
```

--------------------------------

### Jarvis Desktop App Package Structure

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/desktop_app.spec.md

Outlines the directory and file structure for the Jarvis Desktop App.

```tree
src/desktop_app/
├── __init__.py          # Package exports, main() entry point
├── app.py               # JarvisSystemTray, windows, startup flow
├── splash_screen.py     # Animated startup splash
├── setup_wizard.py      # First-run setup wizard
├── settings_window.py   # Auto-generated settings UI from config metadata
├── face_widget.py       # Animated face visualization
├── themes.py            # Qt stylesheets and color palette
├── diary_dialog.py      # End-of-session diary update dialog
├── memory_viewer.py     # Flask-based memory browser
├── updater.py           # Update checking logic
├── update_dialog.py     # Update notification dialogs
└── desktop_assets/      # Icons and images
```

--------------------------------

### Jarvis Health-Aware Advice

Source: https://github.com/isair/jarvis/blob/main/README.md

Jarvis can provide personalized advice by integrating with health-related tools and considering user goals and current status. This example shows Jarvis advising on ordering pizza.

```text
  📝 Heard: "Should I order pizza tonight considering my health goals Jarvis?"
  🧠 Intent (wake word): directed → "should I order pizza tonight considering my health goals"

✨ Working on it: should I order pizza tonight considering my health goals
  🧰 Tool: fetchMeals…
  💬 Generating response...

🤖 Jarvis
Looking at your week — you mentioned wanting to lose 5kg by June...
Today you've had about 860 calories so far. Given your 1,800 calorie target,
you've got room for pizza! But maybe consider thin crust to save calories.
```

--------------------------------

### Windows GPU Library Recovery Action

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/desktop_app.spec.md

Illustrates the logic for adding and executing the 'Reinstall GPU libraries' action in the system tray menu on Windows.

```python
# This code is a conceptual representation based on the description.
# The actual implementation details are within the jarvis codebase.

# Example of how the tray might check for conditions and add the action:
# if is_windows() and nvidia_driver_detected() and install_cuda_script_exists():
#     tray_menu.add_action('🎮 Reinstall GPU libraries', reinstall_gpu_libraries)

# Example of the recovery function:
# def reinstall_gpu_libraries():
#     if confirm_user_action("This will reinstall GPU libraries. Continue?"):
#         try:
#             subprocess.run(['powershell.exe', '-File', 'path/to/install_cuda.ps1'], check=True, shell=True)
#             show_message("GPU libraries reinstalled successfully.")
#         except Exception as e:
#             show_error("Failed to reinstall GPU libraries.", e)

```

--------------------------------

### get_runtime / shutdown_runtime

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/tools/external/mcp_runtime.spec.md

Module-level helpers for managing the lifecycle of the persistent MCP runtime. `get_runtime()` initializes the runtime if it hasn't been started, and `shutdown_runtime()` gracefully stops all active server workers and the event loop.

```APIDOC
## get_runtime() / shutdown_runtime()

### Description
These are module-level helper functions used primarily by the daemon's startup and shutdown procedures to manage the global MCP runtime instance. `get_runtime()` ensures the runtime is initialized and accessible, creating the background thread and event loop on its first call. `shutdown_runtime()` is responsible for gracefully terminating all active server workers and stopping the event loop, ensuring a clean exit.

### Method
(Internal SDK methods)

### Endpoint
(Module-level functions)

### Parameters
None

### Request Example
```python
# To get the runtime instance
runtime = get_runtime()

# To shut down the runtime
shutdown_runtime()
```

### Response
- **get_runtime()**: Returns the singleton `_PersistentMCPRuntime` instance.
- **shutdown_runtime()**: Returns None. Initiates a graceful shutdown process.
```

--------------------------------

### Clone and Run Jarvis from Source on Linux

Source: https://github.com/isair/jarvis/blob/main/README.md

Clone the Jarvis repository and execute the Linux run script. This enables Chatterbox TTS.

```bash
git clone https://github.com/isair/jarvis.git
cd jarvis

# Linux
bash scripts/run_linux.sh
```

--------------------------------

### Widget Mapping for Field Types

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/settings_window.spec.md

Illustrates the mapping between different 'field_type' values and their corresponding Qt widgets, along with any specific notes on their usage.

```markdown
| field_type | Widget | Notes |
|-----------|--------|-------|
| `bool` | QCheckBox | |
| `int` | QSpinBox | With bounds, step, suffix |
| `int` (nullable) | QCheckBox + QSpinBox | Checkbox enables/disables the spinbox |
| `float` | QDoubleSpinBox | With bounds, step, suffix |
| `str` | QLineEdit | Placeholder if nullable |
| `choice` | QComboBox | Pre-defined options |
| `device` | QComboBox | Dynamically populated from sounddevice |
| `list` | QListWidget + Add/Edit/Remove buttons | Stores as JSON array in config |
```

--------------------------------

### Configure Composio MCP Server

Source: https://github.com/isair/jarvis/blob/main/README.md

Configuration for the Composio MCP server. Requires a Composio API key.

```json
{
  "mcps": {
    "composio": {
      "command": "npx",
      "args": ["-y", "@composiohq/rube"],
      "env": { "COMPOSIO_API_KEY": "your-key" }
    }
  }
}
```

--------------------------------

### Configure Notion MCP Server

Source: https://github.com/isair/jarvis/blob/main/README.md

Configuration for the Notion MCP server. Requires a Notion API key.

```json
{ "mcps": { "notion": { "command": "npx", "args": ["-y", "@makenotion/mcp-server-notion"], "env": { "NOTION_API_KEY": "your-token" } } } }
```

--------------------------------

### Import Public API for Prompts Module

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/prompts/prompts.spec.md

Import necessary components from the prompts module, including the ModelSize enum, detect_model_size function, and get_system_prompts function.

```python
from jarvis.reply.prompts import (
    ModelSize,           # Enum: SMALL, LARGE
    detect_model_size,   # (model_name: str) -> ModelSize
    get_system_prompts,  # (model_size: ModelSize) -> PromptComponents
    PromptComponents,    # Dataclass with all prompt strings
)
```

--------------------------------

### Clone and Run Jarvis from Source on Windows

Source: https://github.com/isair/jarvis/blob/main/README.md

Clone the Jarvis repository and execute the Windows run script using PowerShell. This enables Chatterbox TTS.

```powershell
git clone https://github.com/isair/jarvis.git
cd jarvis

# Windows (with Micromamba)
pwsh -ExecutionPolicy Bypass -File scripts\run_windows.ps1
```

--------------------------------

### Daemon Threading Model

Source: https://github.com/isair/jarvis/blob/main/src/desktop_app/desktop_app.spec.md

Illustrates the threading model where the desktop app's main thread interacts with the Qt event loop, while the daemon runs in a separate QThread. This diagram shows signal flow and communication between the main thread and the daemon thread.

```text
┌─────────────────────────────────────────┐
│           Desktop App (Main Thread)      │
│  ┌─────────────────────────────────┐    │
│  │         Qt Event Loop            │    │
│  │  - Tray icon interactions        │    │
│  │  - Window management             │    │
│  │  - Signal/slot communication     │    │
│  └─────────────────────────────────┘    │
│                   │                      │
│                   │ signals              │
│                   ▼                      │
│  ┌─────────────────────────────────┐    │
│  │      DaemonThread (QThread)      │    │
│  │  - Runs jarvis.daemon.main()     │    │
│  │  - Captures stdout/stderr        │    │
│  │  - Emits logs to LogViewer       │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
```

--------------------------------

### Dynamic Context Injection Format

Source: https://github.com/isair/jarvis/blob/main/src/jarvis/reply/reply.spec.md

Shows the format for injecting dynamic context, including time and location, into system messages for LLM calls. This ensures the model has up-to-date information.

```text
[Context: Monday, September 15, 2025 at 17:53 UTC, Location: San Francisco, CA, United States (America/Los_Angeles)]

{original system prompt content}
```

--------------------------------

### Configure Slack MCP Server

Source: https://github.com/isair/jarvis/blob/main/README.md

Configuration for the Slack MCP server. Requires Slack bot and user tokens.

```json
{ "mcps": { "slack": { "command": "npx", "args": ["-y", "slack-mcp-server"], "env": { "SLACK_BOT_TOKEN": "xoxb-...", "SLACK_USER_TOKEN": "xoxp-..." } } } }
```