Settings

Master Agentastic's configuration system to customize every aspect of your experience. From basic preferences to advanced automation, settings give you complete control.

Configuration Overview

Agentastic uses a hierarchical configuration system:

1. Default settings - Base configuration
2. User settings - Your customizations
3. App-specific - Per-application overrides
4. Runtime options - Temporary changes

Configuration Files

File Locations

macOS

~/Library/Application Support/agentastic/
├── config.yaml          # Main configuration
├── prompts.yaml         # Custom prompts
├── expansions.yaml      # Text expansions
└── apps/               # App-specific configs
    ├── Mail.yaml
    ├── Xcode.yaml
    └── Chrome.yaml

File Format

All configuration files use YAML format:

# config.yaml
version: 2
settings:
  launcher:
    shortcut: "cmd+space"
    theme: "auto"
  expansions:
    case_sensitive: false
    word_boundaries: true

Core Settings

Launcher Configuration

launcher:
  # Keyboard shortcut
  shortcut: "cmd+\"  # Default hotkey to open launcher
  
  # Text Selection Popup
  show_agentastic_shortcut: true  # Enable/disable text selection popup
  
  # Appearance
  theme: "auto"  # auto, light, dark
  opacity: 0.95
  size: "medium"  # compact, medium, large
  position: "center"  # center, remember
  
  # Behavior
  auto_close: true
  stay_on_top: true
  animation_speed: "fast"  # instant, fast, smooth
  sound_effects: true

Text Selection Popup: When show_agentastic_shortcut is enabled, selecting text anywhere on your screen shows a small purple popup button. Clicking this popup opens the launcher with your selected text as context. This can be disabled while keeping the global hotkey functional.

Text Selection Popup Advanced Settings

# Text selection popup configuration
show_agentastic_shortcut: true  # Enable/disable popup feature

# Timer-based monitoring (advanced option)
enable_text_selection_timer_monitoring: false  # Default: false (recommended)

Timer Monitoring Options:

• false (default, recommended): Popups only appear when you select text with the mouse. This provides reliable detection and prevents duplicate popups.
• true (use with caution): Enables additional periodic checking for text selection every 0.5 seconds. Only enable if mouse selection isn't detected in specific applications. May cause duplicate popups.

Key Features:

• Single popup enforcement: Only one popup button appears at a time
• Instant replacement: Selecting new text immediately replaces any existing popup
• Smart cleanup: Previous popups disappear instantly when new selections are made

Font Configuration

Customize the launcher overlay's typography for better readability and personal preference:

# Font settings for launcher overlay
overlay_font_family: system       # system, inter, syncopate, or custom font name
overlay_font_size: 14             # Response text size (points)
overlay_input_font_size: 16       # Input field text size
overlay_ui_font_size: 11          # UI elements (buttons, tooltips)
overlay_font_weight: regular      # ultraLight, thin, light, regular, medium, semibold, bold, heavy, black
overlay_code_font_family: monospaced  # Code block font
overlay_code_font_size: 13        # Code block text size

Available Font Families:

• system - macOS native San Francisco font (default)
• inter - Modern, highly-legible font with extensive weight support
• syncopate - Distinctive display font for unique styling
• Custom fonts - Any installed system font (e.g., 'Helvetica', 'Monaco', 'Courier New')

Example Configurations:

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

# Accessibility-focused (larger fonts)
overlay_font_family: system
overlay_font_size: 18
overlay_input_font_size: 20
overlay_ui_font_size: 14

# Developer preferences
overlay_font_family: Helvetica
overlay_code_font_family: Monaco
overlay_code_font_size: 14

Note: Font changes require restarting the launcher to take effect.

Expansion Settings

expansions:
  # Trigger behavior
  case_sensitive: false
  word_boundaries: true
  trigger_key: "space"  # space, tab, return
  
  # Expansion behavior
  preserve_case: true
  expand_inside_words: false
  undo_enabled: true
  undo_timeout: 5000  # milliseconds
  
  # Performance
  max_expansions: 1000
  cache_size: 50

AI Configuration

ai:
  # Default model
  default_model: "smart"  # fast, smart, genius
  
  # Model selection
  auto_select: true
  complexity_threshold: 0.7
  
  # Performance
  timeout: 30000  # milliseconds
  max_retries: 3
  cache_responses: true
  cache_duration: 3600  # seconds
  
  # Privacy
  send_context: true
  store_history: true
  analytics: false

App-Specific Settings

Creating App Configs

# apps/Mail.yaml
app:
  name: "Mail"
  bundle_id: "com.apple.mail"
  
settings:
  expansions:
    enabled: true
    trigger_key: "tab"
    
  ai:
    default_model: "smart"
    auto_formal: true
    
  shortcuts:
    quick_reply: "cmd+r"
    compose: "cmd+shift+n"

App Detection

app_detection:
  method: "bundle_id"  # bundle_id, name, path
  fallback: "name"
  case_sensitive: false

Inheritance

# App config inherits from main config
inherit: true
override:
  - expansions.trigger_key
  - ai.default_model

Memory Configuration

Memory System

memory:
  enabled: true
  default_retention: "30d"
  max_storage: "1GB"
  
  # Channels
  channels:
    - name: "general"
      retention: "30d"
      auto_archive: true
      
    - name: "work"
      retention: "90d"
      keywords: ["project", "meeting", "deadline"]
      
    - name: "personal"
      retention: "7d"
      private: true

Privacy Settings

privacy:
  # Data collection
  telemetry: false
  crash_reports: true
  usage_analytics: false
  
  # Local storage
  encrypt_memory: true
  secure_delete: true
  
  # Sensitive data
  detect_pii: true
  mask_secrets: true
  exclude_patterns:
    - "password"
    - "ssn"
    - "credit card"

Keyboard Shortcuts

Global Shortcuts

shortcuts:
  launcher: "cmd+\"  # Default hotkey to open launcher
  quick_expand: "ctrl+space"
  undo_expansion: "cmd+z"
  
  # AI shortcuts
  ai_complete: "cmd+shift+space"
  vision_mode: "cmd+shift+v"
  
  # Navigation
  next_suggestion: "tab"
  previous_suggestion: "shift+tab"
  accept_suggestion: "return"

Custom Shortcuts

custom_shortcuts:
  - key: "cmd+shift+e"
    action: "insert_email"
    
  - key: "cmd+shift+d"
    action: "insert_date"
    
  - key: "cmd+shift+t"
    action: |
      @ai Generate a thank you message

Advanced Settings

Middleware Configuration

middleware:
  pipeline:
    - "matcher"
    - "rate_limiter"
    - "renderer"
    - "validator"
    - "injector"
    
  rate_limiter:
    max_per_minute: 100
    burst: 20
    
  validator:
    max_length: 10000
    allowed_apps: []
    blocked_apps: ["Terminal"]

Cursor-Aware Matching

Enable pattern matching that persists through arrow key navigation:

# Maintains matching state when using arrow keys
enable_cursor_aware_matching: true

What it does:

• Preserves pattern detection when navigating with arrow keys
• Tracks cursor position within the input buffer
• Maintains matching context during text editing

When to use:

• Writing markdown with brackets: [link text](url)
• Editing code patterns: function() { code }
• Complex text patterns requiring navigation
• Fixing typos without breaking pattern detection

Example behavior:

# Default behavior (cursor-aware disabled):
Type: [hello
Press: ← (left arrow)
Type: ]
Result: No match - state was reset

# With cursor-aware matching:
Type: [hello
Press: ← ← ← ← ← (move cursor after '[')
Type: ]
Result: Matches "[]" pattern

Performance Tuning

performance:
  # Processing
  thread_pool_size: 4
  max_concurrent_ai: 2
  batch_size: 10
  
  # Caching
  cache_strategy: "lru"
  cache_size: "100MB"
  cache_ttl: 3600
  
  # Resource limits
  max_memory: "500MB"
  cpu_limit: 80  # percentage

Logging and Debugging

logging:
  level: "info"  # debug, info, warn, error
  file: "~/Library/Logs/agentastic.log"
  max_size: "10MB"
  rotation: 5
  
  # Debug options
  log_expansions: false
  log_ai_requests: false
  log_performance: true

Import and Export

Exporting Settings

# Export all settings
agentastic config export > my-settings.yaml

# Export specific sections
agentastic config export --section expansions
agentastic config export --section shortcuts

Importing Settings

# Import full configuration
agentastic config import my-settings.yaml

# Import and merge
agentastic config import --merge team-settings.yaml

Backup Strategy

backup:
  enabled: true
  frequency: "daily"
  location: "~/Documents/Agentastic Backups"
  versions: 7
  include:
    - config
    - expansions
    - prompts
    - memory

Configuration Templates

Minimal Setup

# Minimal config for basic use
version: 2
settings:
  launcher:
    shortcut: "cmd+space"
  expansions:
    enabled: true

Developer Setup

# Developer-focused configuration
version: 2
settings:
  expansions:
    apps:
      - "VS Code"
      - "Xcode"
      - "Terminal"
  ai:
    default_model: "genius"
    code_mode: true
  shortcuts:
    code_complete: "tab"
    documentation: "cmd+shift+d"

Writer Setup

# Writer-focused configuration
version: 2
settings:
  ai:
    default_model: "smart"
    style: "creative"
  memory:
    channels:
      - name: "writing"
        retention: "forever"
  expansions:
    preserve_formatting: true

Settings Management

Via UI

1. Open launcher (⌘+Space)
2. Click settings icon (⚙️)
3. Navigate sections
4. Make changes
5. Changes auto-save

Via CLI

# View current settings
agentastic config show

# Update setting
agentastic config set launcher.theme dark

# Reset to defaults
agentastic config reset

Via Files

1. Edit YAML files directly
2. Save changes
3. Agentastic auto-reloads
4. Check logs for errors

Troubleshooting Settings

Settings Not Applied

1. Check YAML syntax
2. Verify file location
3. Look for errors in log
4. Restart Agentastic

Conflicts

1. Check app-specific overrides
2. Review inheritance rules
3. Use debug logging
4. Test with minimal config

Performance Issues

1. Reduce cache sizes
2. Lower concurrent limits
3. Disable unused features
4. Profile with debug logs

Best Practices

Organization

1. Use clear section names
2. Comment complex settings
3. Group related options
4. Keep backups

Security

1. Encrypt sensitive data
2. Use secure defaults
3. Limit permissions
4. Regular audits

Maintenance

1. Review settings quarterly
2. Clean up unused options
3. Update documentation
4. Test after changes

Next Steps

• Explore Memory System
• Create Custom Prompts
• Review Complete Reference

Settings are the foundation of a personalized Agentastic experience. Take time to configure them properly - your future self will thank you!