RunMaestro · chr1syy · Feb 17, 2026 · Feb 17, 2026 · Feb 17, 2026 · Feb 17, 2026
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -10,21 +10,22 @@ Open Settings with `Cmd+,` / `Ctrl+,` or via **Quick Actions** (`Cmd+K` / `Ctrl+
 
 Settings are organized into tabs:
 
-| Tab | Contents |
-|-----|----------|
-| **General** | About Me (conductor profile), shell configuration, input send behavior, default toggles (history, thinking), automatic tab naming, power management, updates, privacy, usage stats, storage location |
-| **Display** | Font family and size, terminal width, log level and buffer, max output lines per response, document graph settings, context window warnings |
-| **Shortcuts** | Customize keyboard shortcuts (see [Keyboard Shortcuts](./keyboard-shortcuts)) |
-| **Themes** | Dark, light, and vibe mode themes, custom theme builder with import/export |
-| **Notifications** | OS notifications, custom command notifications, toast notification duration |
-| **AI Commands** | View and edit slash commands, [Spec-Kit](./speckit-commands), and [OpenSpec](./openspec-commands) prompts |
-| **SSH Hosts** | Configure remote hosts for [SSH agent execution](./ssh-remote-execution) |
+| Tab               | Contents                                                                                                                                                                                             |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **General**       | About Me (conductor profile), shell configuration, input send behavior, default toggles (history, thinking), automatic tab naming, power management, updates, privacy, usage stats, storage location |
+| **Display**       | Font family and size, terminal width, log level and buffer, max output lines per response, document graph settings, context window warnings                                                          |
+| **Shortcuts**     | Customize keyboard shortcuts (see [Keyboard Shortcuts](./keyboard-shortcuts))                                                                                                                        |
+| **Themes**        | Dark, light, and vibe mode themes, custom theme builder with import/export                                                                                                                           |
+| **Notifications** | OS notifications, custom command notifications, toast notification duration                                                                                                                          |
+| **AI Commands**   | View and edit slash commands, [Spec-Kit](./speckit-commands), and [OpenSpec](./openspec-commands) prompts                                                                                            |
+| **SSH Hosts**     | Configure remote hosts for [SSH agent execution](./ssh-remote-execution)                                                                                                                             |
 
 ## Conductor Profile
 
 The **Conductor Profile** (Settings → General → **About Me**) is a short description of yourself that gets injected into every AI agent's system prompt. This helps agents understand your background, preferences, and communication style so they can tailor responses accordingly.
 
 **To configure:**
+
 1. Open **Settings** (`Cmd+,` / `Ctrl+,`) → **General** tab
 2. Find the **About Me** text area at the top
 3. Write a brief profile describing yourself
@@ -58,15 +59,74 @@ When you start a session, Maestro includes your conductor profile in the system
 
 You can reference your conductor profile in [slash commands](./slash-commands) using the `{{CONDUCTOR_PROFILE}}` template variable. This is useful for commands that need to remind agents of your preferences mid-conversation.
 
+## Global Environment Variables
+
+Configure environment variables once in Settings and they automatically apply to all AI agent processes and terminal sessions. This is perfect for managing API keys, proxy settings, custom tool paths, and other shared configuration.
+
+### How to Configure
+
+1. Open **Settings** (`Cmd+,` / `Ctrl+,`) → **General** tab
+2. Expand **Shell Configuration** section
+3. Scroll to **Global Environment Variables**
+4. Add your variables in `KEY=VALUE` format (one per line)
+5. Variables apply immediately to new agent sessions and terminals
+
+### Example Configuration
+
+```
+ANTHROPIC_API_KEY=sk-proj-xxxxx
+HTTP_PROXY=http://proxy.company.com:8080
+HTTPS_PROXY=http://proxy.company.com:8080
+DEBUG=maestro:*
+MY_TOOL_PATH=~/tools/custom
+```
+
+### Important Features
+
+- **Path expansion**: Use `~/` for home directory (e.g., `~/workspace` expands to `/Users/username/workspace`)
+- **Quotes for special characters**: Variables with spaces or special characters should be quoted
+- **Applied to both agents and terminals**: Global vars are available to all agent processes (Claude, OpenCode, etc.) and all terminal sessions
+- **Agent-specific overrides**: You can override global variables with agent-specific settings (in agent configuration)
+- **Persist across sync**: Global environment variables are included when you export or sync settings to another device
+
+### Environment Variable Precedence
+
+When an agent or terminal is spawned, variables are merged in this order (highest to lowest priority):
+
+1. **Session-level overrides** - Temporary per-session customizations
+2. **Global environment variables** (Settings) - Applied to all agents and terminals
+3. **Agent-specific configuration** - Default settings for a particular agent
+4. **System environment** - System and parent process variables
+
+This means a session-level override will take precedence over the global setting, which takes precedence over agent defaults.
+
+### Use Cases
+
+- **API keys**: Set `ANTHROPIC_API_KEY` once → all Claude sessions can access it
+- **Proxy settings**: Set `HTTP_PROXY` and `HTTPS_PROXY` → all network requests respect the proxy
+- **Custom tool paths**: Set `MY_TOOLS=/opt/mytools` → agents can find custom utilities
+- **Debugging**: Set `DEBUG=maestro:*` → enable consistent logging across all sessions
+- **Language settings**: Set `LANG=en_US.UTF-8` → consistent text encoding
+
+### Agent-Specific Overrides
+
+To override a global variable for a specific agent:
+
+1. In the agent configuration panel, scroll to **Environment Variables (optional)**
+2. Add the variable with the override value
+3. This session-specific value takes precedence over the global setting
+
 ## Checking for Updates
 
 Maestro checks for updates automatically on startup (configurable in Settings → General → **Check for updates on startup**).
 
 **To manually check for updates:**
+
 - **Quick Actions:** `Cmd+K` / `Ctrl+K` → "Check for Updates"
 - **Menu:** Click the hamburger menu (☰) → "Check for Updates"
 
 When an update is available, you'll see:
+
 - Current version and new version number
 - Release notes summary
 - **Download** button to get the latest release from GitHub
@@ -77,10 +137,12 @@ When an update is available, you'll see:
 By default, Maestro only notifies you about stable releases. If you want to try new features before they're officially released, you can opt into the pre-release channel.
 
 **To enable beta updates:**
+
 1. Open **Settings** (`Cmd+,` / `Ctrl+,`) → **General** tab
 2. Toggle **Include beta and release candidate updates** on
 
 **What changes:**
+
 - Update checks will include pre-release versions (e.g., `v0.11.1-rc`, `v0.12.0-beta`)
 - You'll receive notifications for beta, release candidate (rc), and alpha releases
 - The Update dialog will show all available pre-release versions
@@ -107,11 +169,13 @@ Configure audio and visual notifications in **Settings** (`Cmd+,` / `Ctrl+,`)
 ### OS Notifications
 
 Enable desktop notifications to be alerted when:
+
 - An AI task completes
 - A long-running command finishes
 - The agent requires attention
 
 **To enable:**
+
 1. Toggle **Enable OS Notifications** on
 2. Click **Test Notification** to verify it works
 
@@ -120,6 +184,7 @@ Enable desktop notifications to be alerted when:
 Execute a custom command when AI tasks complete. Use any notification method that fits your workflow.
 
 **To configure:**
+
 1. Toggle **Enable Custom Notification** on
 2. Set the **Command Chain** — the command(s) that accept text via stdin:
    - **macOS:** `say` (text-to-speech), `afplay /path/to/sound.wav` (audio file)
@@ -130,6 +195,7 @@ Execute a custom command when AI tasks complete. Use any notification method tha
 4. Click **Stop** to interrupt a running test
 
 **Command chaining:** Chain multiple commands together using pipes to mix and match tools. Examples:
+
 - `say` — speak aloud using macOS text-to-speech
 - `tee ~/log.txt | say` — log to a file AND speak aloud
 - `notify-send "Maestro" && espeak` — show desktop notification and speak (Linux)
@@ -139,15 +205,16 @@ Execute a custom command when AI tasks complete. Use any notification method tha
 
 In-app toast notifications appear in the corner when events occur. Configure how long they stay visible:
 
-| Duration | Behavior |
-|----------|----------|
-| **Off** | Toasts are disabled entirely |
+| Duration                 | Behavior                                  |
+| ------------------------ | ----------------------------------------- |
+| **Off**                  | Toasts are disabled entirely              |
 | **5s / 10s / 20s / 30s** | Toast disappears after the specified time |
-| **Never** | Toast stays until manually dismissed |
+| **Never**                | Toast stays until manually dismissed      |
 
 ### When Notifications Trigger
 
 Notifications are sent when:
+
 - An AI task completes (OS notification + optional custom notification)
 - A long-running command finishes (OS notification)
 
@@ -156,13 +223,15 @@ Notifications are sent when:
 Maestro can prevent your computer from sleeping while AI agents are actively working, ensuring long-running tasks complete without interruption.
 
 **To enable:**
+
 1. Open **Settings** (`Cmd+,` / `Ctrl+,`) → **General** tab
 2. Scroll to the **Power** section
 3. Toggle **Prevent sleep while working** on
 
 ### When Sleep Prevention Activates
 
 Sleep prevention automatically activates when:
+
 - Any session is **busy** (agent processing a request)
 - **Auto Run** is active (processing tasks)
 - **Group Chat** is in progress (moderator or agents responding)
@@ -171,19 +240,21 @@ When all activity stops, sleep prevention deactivates automatically.
 
 ### Platform Support
 
-| Platform | Support Level | Notes |
-|----------|---------------|-------|
-| **macOS** | Full support | Equivalent to running `caffeinate`. Check Activity Monitor → View → Columns → "Preventing Sleep" to verify. |
-| **Windows** | Full support | Uses `SetThreadExecutionState`. Verify with `powercfg /requests` in admin CMD. |
-| **Linux** | Varies by desktop environment | Works on GNOME, KDE, XFCE via D-Bus. See notes below. |
+| Platform    | Support Level                 | Notes                                                                                                       |
+| ----------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **macOS**   | Full support                  | Equivalent to running `caffeinate`. Check Activity Monitor → View → Columns → "Preventing Sleep" to verify. |
+| **Windows** | Full support                  | Uses `SetThreadExecutionState`. Verify with `powercfg /requests` in admin CMD.                              |
+| **Linux**   | Varies by desktop environment | Works on GNOME, KDE, XFCE via D-Bus. See notes below.                                                       |
 
 ### Linux Desktop Environment Notes
 
 Sleep prevention on Linux uses standard freedesktop.org interfaces:
+
 - **GNOME, KDE, XFCE**: Full support via D-Bus screen saver inhibition
 - **Minimal window managers** (i3, sway, dwm, bspwm): May not work. These environments typically don't run a screen saver daemon.
 
 **If sleep prevention doesn't work on Linux:**
+
 1. Ensure `xdg-screensaver` is installed
 2. Verify a D-Bus screen saver service is running
 3. Some systems may need `gnome-screensaver`, `xscreensaver`, or equivalent
@@ -217,17 +288,20 @@ Maestro can sync settings, sessions, and groups across multiple devices by stori
 6. Repeat on your other devices, selecting the same synced folder
 
 **What syncs:**
+
 - Settings and preferences
 - Session configurations
 - Groups and organization
 - Agent configurations
 - Session origins and metadata
 
 **What stays local:**
+
 - Window size and position (device-specific)
 - The bootstrap file that points to your sync location
 
 **Important limitations:**
+
 - **Single-device usage**: Only run Maestro on one device at a time. Running simultaneously on multiple devices can cause sync conflicts where the last write wins.
 - **No conflict resolution**: If settings are modified on two devices before syncing completes, one set of changes will be lost.
 - **Restart required**: Changes to storage location require an app restart to take effect.