Docs

Launcher

The Agentastic Launcher is your command center for AI assistance and text expansion management. This floating interface provides instant access to all features without leaving your current application.

Opening the Launcher

The launcher can be opened in two ways:

Global Hotkey

Press ⌘+\ (default) to open the launcher from anywhere. The translucent overlay appears over your current application, ready for input.

Text Selection Popup

When enabled, selecting text anywhere on your screen shows a small purple popup button. Click this popup to instantly open the launcher with your selected text as context.

To enable/disable the Text Selection Popup:

  1. Open Settings app
  2. Navigate to the General settings page
  3. Find "Text Selection Popup" toggle
  4. Switch on/off as desired

Key Features:

  • Single popup enforcement: Only one popup button appears at a time - selecting new text immediately replaces any existing popup
  • Instant cleanup: Previous popups disappear instantly when you make a new selection
  • Smart detection: Popups appear reliably on mouse selection events

Note: Disabling the text selection popup does not affect the global hotkey - it remains fully functional.

Customizing the Hotkey

  1. Open Settings (⌘+, from launcher)
  2. Navigate to General settings
  3. Find "Agentastic Hotkey"
  4. Click on the shortcut recorder field
  5. Press your preferred key combination
  6. Click "Save All" to apply changes

Launcher Interface

Main Input Field

The central text field where you:

  • Type AI prompts and questions
  • Search for expansions
  • Enter commands
  • Create quick notes

Visual Indicators

  • Infinity icon (∞) - Agent mode status (gray when off, highlighted when active)
  • Eye icon (👁️) - Vision mode status
  • Model indicator - Current AI model
  • Loading spinner - Processing status
  • Character count - Input length

Action Buttons

  • Agent (∞) - Toggle agent mode for advanced AI capabilities
  • Settings (⚙️) - Access preferences
  • History (🕐) - Recent queries
  • Vision (👁️) - Toggle screen capture
  • Minimize (−) - Minimize to Dock
  • Close (✕) - Dismiss launcher

Window Management

The launcher overlay provides flexible window management:

  • Minimize to Dock: Click the minimize button (−) or press ⌘+M to minimize the launcher to the Dock
  • Restore from Dock: Click the Agentastic icon in the Dock to restore the minimized window
  • Content Preservation: Your conversation and input are preserved when minimized
  • Dock Icon: Appears automatically when the launcher is visible, disappears when closed
  • Window State: The launcher remembers its position and size between sessions

Window Modes

The launcher supports two display modes that you can switch between at any time:

Overlay Mode (Default)

  • Appearance: Borderless, floating window with transparent background
  • Behavior: Hovers above other windows, always on top
  • Use Case: Quick AI assistance without losing focus on your work
  • Shortcut: Default mode, or press ⌥+⌘+O to switch back from window mode

Standard Window Mode

  • Appearance: Traditional macOS window with title bar and standard controls (close, minimize, maximize)
  • Behavior: Behaves like a regular application window
  • Use Case: When you prefer a more traditional window experience or need standard window controls
  • Shortcut: Press ⌥+⌘+O to switch to window mode, or launch with --window flag

Switching Between Modes

  • Keyboard: Press ⌥+⌘+O to toggle between overlay and standard window mode
  • Command Line: Launch with agentastic launcher --window to start in standard window mode
  • Preservation: Your conversation and context are preserved when switching modes
  • Auto-Expand: When switching to overlay mode, the full overlay is always shown (never stuck in minimized state)

Window Size Toggle

Within overlay mode, you can toggle between two sizes:

  • Full Overlay: Shows complete interface with conversation history and all controls
  • Text-Field Only: Minimized view showing only the input field for quick queries
  • Shortcut: Press ⌘+F to toggle between full and minimized overlay sizes

Core Launcher Features

AI Assistance

Type naturally to get AI help:

"Write a thank you email"
"Explain this error message"
"Translate this to Spanish"

Quick Expansion Search

Find and insert expansions:

  1. Type part of trigger or content
  2. See matching expansions
  3. Select with arrow keys
  4. Insert with Return

Command Mode

Use special commands:

  • /email - Email assistance
  • /calendar - Schedule events
  • /search - Web search
  • /settings - Quick settings
  • /tab: - Select browser tabs for context

Vision Mode

Enable visual context:

  1. Click eye icon or press ⌘+2
  2. Launcher can now see your screen
  3. Ask questions about visible content
  4. Disable when done for privacy

Screenshot Selection

Capture specific regions of your screen interactively with precise visual selection.

How to use:

  1. Open the launcher with ⌘+\
  2. Press ⌘+4 to enter screenshot selection mode
  3. Your screen dims with a semi-transparent overlay
  4. Click and drag to select the region you want to capture
  5. Release the mouse to capture the selected area
  6. The screenshot is automatically added to your conversation

Visual feedback during selection:

  • Dashed rectangle border shows your selection area in real-time
  • Size label displays width × height dimensions while dragging
  • Crosshair cursor for precise positioning
  • Transparent overlay dims non-selected areas for better focus

Features:

  • Auto-enables vision mode - Vision mode turns on automatically after capture
  • Clipboard integration - Screenshot is copied to clipboard automatically
  • Image thumbnail - Captured image appears as a thumbnail in the conversation
  • Multi-monitor support - Works seamlessly across multiple displays
  • Cancel anytime - Press Escape to cancel the selection
  • Minimum size validation - Selections must be at least 5×5 pixels

Example workflows:

# Capture specific UI element
⌘+4 → Drag around button → "What does this button do?"

# OCR text from image
⌘+4 → Select text region → "Extract the text from this"

# Debug visual issues
⌘+4 → Capture problem area → "Why does this look wrong?"

# Compare designs
⌘+4 → Capture first design → ⌘+4 → Capture second → "Compare these"

Requirements:

  • macOS 14.0 (Sonoma) or later
  • Screen Recording permission enabled

Voice Input (Push-to-Talk)

Quick voice input without clicking:

  1. Hold down the Space bar for 1 second (when text field not focused)
  2. Speak your message
  3. Release Space to stop recording and transcribe
  4. Text appears in input field automatically

Note: Requires microphone permission. The spacebar must be held for at least 1 second to activate voice input, preventing accidental activation while typing. The hotkey only works when you're not actively typing in the text field.

Browser Tab Selection

Include browser tabs as context in your prompts:

  1. Type /tab: in the input field
  2. Tab selector dropdown appears with all open Chrome and Safari tabs
  3. Select one or multiple tabs using:
    • Single click - Select one tab and confirm
    • Cmd+Click - Toggle individual tabs
    • Shift+Click - Select a range
    • Cmd+A - Select all filtered tabs
  4. Selected tab information is included in your AI prompt

Features:

  • Search/filter tabs by title, domain, or URL
  • Visual checkboxes show selected tabs
  • Live updates without losing selection
  • Keyboard navigation with arrow keys and Space to toggle

Navigation and Controls

Keyboard Navigation

  • ↑/↓ - Navigate suggestions
  • ⏎ - Execute/insert (Send message when input field focused)
  • ⌘+Q - Close launcher overlay
  • ⌘+M - Minimize launcher to Dock
  • ⎋ - Cancel current API request (if one is in progress)
  • ⌘+⏎ - Insert and continue
  • ⌥+⏎ - Copy to clipboard
  • ⌘+1 - Toggle Agent Mode (advanced AI capabilities)
  • ⌘+2 - Toggle Vision Mode (screen capture for AI)
  • ⌘+F - Toggle window size (minimize ↔ expand overlay)
  • ⌥+⌘+O - Toggle window mode (overlay ↔ standard window)
  • ⌘+4 - Screenshot Selection (drag to capture region)
  • ⌘+T - Create new conversation tab
  • ⌘+W - Close current conversation tab
  • ⌥+⌘+W - Close all conversation tabs
  • ⌘+S - Bookmark current conversation
  • ⌘+N - Start new conversation
  • Hold Space (1 sec) - Push-to-talk voice input after 1 second hold (when text field not focused)

Mouse Controls

  • Click outside to dismiss
  • Drag to reposition
  • Scroll through long responses
  • Right-click for context menu

Text Selection

  • ⌘+A - Select all
  • ⌘+C - Copy selection
  • ⌘+X - Cut selection
  • ⌘+V - Paste content

Advanced Launcher Features

Multi-Modal Input

Combine text with:

  • Screen captures (vision mode)
  • Selected text context
  • Clipboard contents
  • File references

Response Actions

After receiving AI response:

  • Insert - Place in active app
  • Copy - Save to clipboard
  • Edit - Refine the response
  • Save - Create expansion
  • Share - Send to others

Conversation Mode

Continue interactions:

  1. Get initial response
  2. Type follow-up question
  3. Maintain context
  4. Iterate until satisfied

Conversation Management

Save and resume conversations:

  1. Bookmark Current Conversation: Press ⌘+S to bookmark your current chat
  2. View Bookmarked Conversations: Open Settings app → Bookmarks page
  3. Load Previous Conversations: Click "Load" button next to any bookmarked conversation
  4. Continue Where You Left Off: Launcher opens with your bookmarked conversation fully restored
  5. Start Fresh: Press ⌘+N to begin a new conversation

Benefits:

  • Never lose important conversations
  • Resume complex discussions across sessions
  • Build on previous AI assistance
  • Maintain context for long-term projects

Conversation Tabs

Work with multiple AI conversations simultaneously using tabs:

Creating New Tabs:

  • Click the "+" button in the header to create a new tab
  • Press ⌘+T for instant new tab creation
  • New tabs become active immediately

Tab Management:

  • Left Sidebar: View all open conversation tabs
  • Visual Indicators: Active tab is highlighted
  • Easy Switching: Click any tab to switch
  • Close Tabs: Click × button on tabs (when multiple tabs exist), press ⌘+W to close active tab, or ⌥+⌘+W to close all tabs

Tab Features:

  • Each tab maintains independent conversation history
  • Agent and vision modes are separate per tab
  • Browser tab selections preserved per conversation
  • Closing tabs removes unsaved conversations

Use Cases:

  • Research in one tab while coding in another
  • Compare different AI responses side-by-side
  • Keep project contexts separated
  • Manage multilingual conversations

Quick Actions

Built-in shortcuts:

  • ⌘+T - New conversation tab
  • ⌘+W - Close current tab
  • ⌥+⌘+W - Close all tabs
  • ⌘+N - New conversation (clears current chat)
  • ⌘+S - Bookmark current conversation
  • ⌘+1 - Toggle Agent Mode
  • ⌘+2 - Toggle Vision Mode
  • ⌘+F - Toggle window size (minimize ↔ expand)
  • ⌥+⌘+O - Toggle window mode (overlay ↔ standard window)
  • ⌘+4 - Screenshot Selection (drag to capture)
  • ⌘+K - Search everything
  • ⌘+/ - Show shortcuts
  • ⌘+, - Open settings
  • Hold Space (1 sec) - Voice input (push-to-talk after 1 second)

Launcher Workflows

Email Workflow

  1. Open launcher (⌘+Space)
  2. Type: "Reply thanking for the meeting"
  3. Add /email for email-specific help
  4. Review and insert response

Research Workflow

  1. Select text to research
  2. Open launcher
  3. Type: "Explain this concept"
  4. Get contextual explanation

Code Workflow

  1. Enable vision mode (⌘+V)
  2. Type: "What's wrong with this code?"
  3. Get debugging assistance
  4. Apply fixes directly

Translation Workflow

  1. Select text to translate
  2. Open launcher
  3. Type: "Spanish" (auto-detects translation need)
  4. Insert translated text

Conversation Management Workflow

  1. Start a complex project discussion in launcher
  2. Bookmark the conversation with ⌘+S when taking a break
  3. Later, open Settings app and navigate to the Bookmarks page
  4. Find your bookmarked conversation and click "Load"
  5. Launcher opens with the entire bookmarked conversation restored
  6. Continue where you left off with full context preserved

Customization Options

Appearance

  • Theme: Light, dark, or auto
  • Opacity: Adjust transparency
  • Size: Compact or expanded
  • Position: Remember last location

Behavior

  • Auto-close: After insertion
  • Stay on top: Always visible
  • Animation: Smooth or instant
  • Sound: Feedback sounds

Default Settings

  • Model: Preferred AI model
  • Vision: Start with vision enabled
  • Bookmarks: Number of saved items
  • Shortcuts: Custom bindings

Font Configuration

Customize the launcher overlay's typography for optimal readability and personal preference.

Configuration Location: Edit ~/Library/Application Support/agentastic/config/config.yml

Available Settings:

# Font family: 'system', 'inter', 'syncopate', or custom font name
overlay_font_family: system

# Font sizes (in points)
overlay_font_size: 14          # Response text
overlay_input_font_size: 16    # Input field
overlay_ui_font_size: 11       # UI elements
overlay_code_font_size: 13     # Code blocks

# Font weight options
overlay_font_weight: regular   # Options: ultraLight, thin, light, regular, medium, semibold, bold, heavy, black

# Code font family
overlay_code_font_family: monospaced

Font Options:

  • system: macOS native San Francisco font (default)
  • inter: Modern, highly-legible font with extensive weights
  • syncopate: Distinctive display font
  • Custom: Any installed system font (e.g., 'Helvetica', 'Monaco')

Example Configurations:

# Better readability with Inter
overlay_font_family: inter
overlay_font_size: 15
overlay_font_weight: medium

# Accessibility - larger fonts
overlay_font_size: 18
overlay_input_font_size: 20
overlay_ui_font_size: 14

# Developer setup
overlay_code_font_family: Monaco
overlay_code_font_size: 14

Note: Restart the launcher after changing font settings.

Performance Tips

Faster Responses

  1. Use keyboard shortcuts
  2. Enable quick mode
  3. Choose appropriate model
  4. Keep prompts concise

Efficient Workflows

  1. Learn common commands
  2. Create expansion shortcuts
  3. Use conversation mode
  4. Customize layout

Resource Management

  • Close when not needed
  • Disable vision mode when done
  • Clear history periodically
  • Monitor memory usage

Troubleshooting

Launcher Won't Open

  1. Check keyboard shortcut
  2. Verify Agentastic is running
  3. Look for conflicts with other apps
  4. Restart Agentastic

Slow Performance

  1. Check internet connection
  2. Switch to faster model
  3. Disable vision mode
  4. Clear cache

Display Issues

  1. Adjust opacity settings
  2. Check display scaling
  3. Try different position
  4. Reset to defaults

Tips and Tricks

Power User Tips

  1. Chain commands: /email /formal /model:smart
  2. Quick snippets: Type trigger directly
  3. Instant search: Start with /
  4. Voice input: Hold Space for push-to-talk (when not typing)

Productivity Hacks

  1. Create launcher-specific expansions
  2. Use vision mode for OCR
  3. Build command combinations
  4. Set up quick actions

Hidden Features

  • Double-tap ⌘+Space for last query
  • Drag corner to resize
  • ⌘+Click links to open
  • Shake to clear input

Integration Points

With Expansions

  • Search and insert
  • Create from responses
  • Edit existing
  • Preview before inserting

With AI Features

  • Natural language processing
  • Context awareness
  • Model selection
  • Response refinement

With System

  • Clipboard integration
  • File system access
  • Application awareness
  • Screen capture

Next Steps

Master the launcher, then explore:

The launcher is your gateway to Agentastic's full potential. The more you use it, the more indispensable it becomes!