Docs

Concepts

Understanding how Agentastic works will help you get the most out of its features. This guide covers the fundamental concepts behind text expansion, AI integration, and the system architecture.

Text Expansion Fundamentals

Triggers and Expansions

At its core, Agentastic transforms triggers (short text snippets) into expansions (longer text):

  • Trigger: What you type (e.g., eml)
  • Expansion: What it becomes (e.g., john.doe@example.com)

When you type a trigger followed by a delimiter (like space or enter), Agentastic automatically replaces it with the expansion.

Trigger Types

Agentastic supports several trigger types:

  1. Simple Triggers: Direct text replacement

    • Example: addr → Your full address

  2. Dynamic Triggers: Include variables and logic

    • Example: date → Current date in your preferred format

  3. AI-Powered Triggers: Generate content using AI

    • Example: ;;email → Contextual email composition

Match Patterns

You can define how triggers should match:

  • Word Match: Trigger must be a complete word
  • Prefix Match: Trigger can be part of a word
  • Case Sensitive: Distinguish between SQL and sql
  • Regex Match: Use regular expressions for complex patterns

The Agentastic Architecture

Three Core Components

Agentastic consists of three main components working together:

1. Core Engine (Rust)

The heart of Agentastic, responsible for:

  • Detecting keyboard input across all applications
  • Matching triggers against your expansion library
  • Injecting expanded text back into applications
  • Managing configuration and settings

2. Settings App (Tauri)

A modern desktop application for:

  • Creating and managing expansions
  • Configuring AI models and preferences
  • Viewing usage statistics and memory
  • Authenticating and syncing settings

3. AI Launcher (SwiftUI)

A macOS-native overlay for:

  • Quick AI interactions with ⌘⇧Space
  • Running AI commands with special tags
  • Managing conversations and context
  • Accessing powerful AI tools

How They Work Together

User Types → Core Engine Detects → Matches Trigger →
  → Simple Expansion: Injects Text
  → AI Expansion: Sends to Launcher → AI Processes → Returns Result → Injects

AI Integration Concepts

Agent Mode vs. Chat Mode

Agentastic supports two AI interaction modes:

Chat Mode (Default)

  • Quick, conversational responses
  • Best for simple queries and text generation
  • Faster response times
  • Limited tool access

Agent Mode (Advanced)

  • Can use external tools and APIs
  • Performs multi-step reasoning
  • Access to calendar, email, search, files
  • More powerful but slower

Enable Agent Mode by:

  • Clicking the infinity (∞) button in the launcher
  • Using the /agent tag in your prompt

Special Tags

Special tags modify how the AI processes your request:

  • /email - Optimize for email composition
  • /search - Enable web search capabilities
  • /calendar - Access calendar tools
  • /vision - Enable image understanding
  • /model:name - Switch AI models
  • /memory:channel - Use specific memory context

See the AI Commands documentation for a complete list.

Memory and Context

Agentastic uses a sophisticated memory system:

Conversation Memory

  • Remembers the current chat session
  • Maintains context across messages
  • Resets when you start a new conversation

Memory Channels

  • Persistent memory across sessions
  • Organized by topic or project
  • Store important context, preferences, facts
  • Use with /memory:channel-name

Example: Create a work channel with company-specific information, then use /memory:work to access that context in any conversation.

Configuration System

Hierarchical Configuration

Agentastic uses YAML files for configuration:

~/Library/Application Support/agentastic/
  ├── config.yml          # Global settings
  ├── matches.yml         # Your expansions
  └── models.yml          # AI model configuration

App-Specific Overrides

You can create app-specific configurations that override global settings:

# Chrome-specific expansions
app_filter:
  application: "Google Chrome"
triggers:
  - trigger: "gmail"
    expansion: "Navigate to Gmail"

Privacy and Security

Local-First Design

Agentastic prioritizes your privacy:

  • Text expansions happen entirely on your device
  • No keylogging: Only active when a trigger is typed
  • Encrypted storage: Sensitive data is encrypted at rest
  • Optional cloud sync: You control what syncs

AI Processing

When using AI features:

  • Local models (if configured) process everything on-device
  • Cloud models send only your prompts, not keystrokes
  • Memory channels are encrypted and private
  • You control which AI provider to use

Performance Optimization

Efficient Detection

Agentastic uses advanced techniques to minimize resource usage:

  • Event-driven architecture: Only processes relevant keystrokes
  • Smart matching: Fast trie-based trigger detection
  • Lazy loading: Loads expansions on-demand
  • Platform-native: Uses macOS APIs for optimal performance

Background Operation

The core engine runs as a lightweight daemon:

  • Minimal CPU usage (< 1% typically)
  • Small memory footprint (< 50MB)
  • Automatic updates without interruption
  • Efficient power consumption

Best Practices

Organizing Expansions

  1. Use prefixes: Group related triggers (em-work, em-personal)
  2. Be descriptive: Choose memorable triggers
  3. Avoid conflicts: Don't override common words
  4. Test thoroughly: Verify expansions work as expected

Leveraging AI

  1. Start with chat mode: Use agent mode only when needed
  2. Use specific tags: /email is more focused than generic prompts
  3. Maintain memory: Keep relevant context in memory channels
  4. Choose the right model: Balance speed vs. capability

Performance Tips

  1. Limit regex triggers: They're slower than simple matches
  2. Use app filters: Scope expansions to relevant apps
  3. Disable when not needed: Toggle off in password fields
  4. Regular maintenance: Clean up unused expansions

Understanding the Workflow

Typical Text Expansion Flow

  1. User types a trigger (e.g., eml)
  2. Core engine detects the pattern
  3. Engine checks if trigger is active in current app
  4. If matched, replaces trigger with expansion
  5. User continues typing seamlessly

AI-Powered Expansion Flow

  1. User activates launcher (⌘⇧Space)
  2. Types prompt with optional tags
  3. Launcher sends to configured AI model
  4. AI processes with requested tools/context
  5. Response appears in launcher
  6. User can copy, edit, or inject response

What's Next?

Now that you understand the concepts:

Key Takeaway: Agentastic is designed to be invisible when you don't need it, and powerful when you do. The best workflows combine simple expansions for common tasks with AI-powered features for complex ones.