Text Expansion

Text expansion is the cornerstone of Agentastic, allowing you to type less and accomplish more. This guide covers everything from basic expansions to advanced templating features.

How Text Expansion Works

When you type a trigger followed by a delimiter (usually space), Agentastic:

1. Detects the trigger pattern
2. Removes the trigger text
3. Inserts the replacement text
4. Positions your cursor appropriately

This happens instantly, maintaining your typing flow.

Pattern Matching Behavior

By default, Agentastic resets pattern detection when you use arrow keys. This prevents accidental expansions but can interrupt complex patterns like [text].

Enable cursor-aware matching to maintain pattern detection through navigation:

enable_cursor_aware_matching: true

This allows you to:

• Edit patterns mid-typing without breaking detection
• Navigate with arrow keys while preserving match state
• Fix typos in triggers without retyping everything

Types of Expansions

Simple Text Replacement

The most basic form - one trigger, one replacement:

Trigger: addr
Replacement: 123 Main Street, New York, NY 10001

Multi-line Expansions

Create formatted content with line breaks:

Trigger: sig
Replacement:
Best regards,
John Doe
Senior Developer
Acme Corp

Dynamic Expansions

Use variables for content that changes:

Trigger: mtgnotes
Replacement:
Meeting Notes - {{date}}
Attendees: {{cursor}}
Topics:
- 
Action Items:
- 

Formatted Expansions

Preserve rich text formatting:

• Bold text
• Italic text
• Lists and bullets
• Code blocks
• Tables

Variables and Placeholders

Agentastic supports dynamic variables to make expansions more powerful:

Date and Time Variables

• {{date}} - Current date (November 15, 2024)
• {{date:short}} - Short date (11/15/24)
• {{date:iso}} - ISO format (2024-11-15)
• {{time}} - Current time (2:30 PM)
• {{time:24}} - 24-hour format (14:30)
• {{datetime}} - Combined date and time

System Variables

• {{clipboard}} - Current clipboard contents
• {{selected}} - Currently selected text
• {{cursor}} - Cursor position after expansion
• {{user}} - System username
• {{machine}} - Computer name

Custom Variables

Define your own variables:

{{name}} - Your name
{{email}} - Your email
{{phone}} - Your phone number

Set these in Settings → Variables.

Advanced Features

Nested Expansions

Expansions can trigger other expansions:

Trigger: emailsig
Replacement: {{sig}}
{{contact}}

Conditional Expansions

Different expansions based on context:

Trigger: greet
Morning replacement: Good morning
Afternoon replacement: Good afternoon
Evening replacement: Good evening

Script Expansions

Execute scripts and insert output:

Trigger: uuid
Script: uuidgen
Result: Inserts a unique UUID

Form Fill Expansions

Interactive expansions with input fields:

Trigger: bugrep
Form:
- Bug Title: [input]
- Severity: [dropdown: Low, Medium, High]
- Description: [textarea]

Application-Specific Expansions

Configure expansions to work differently in different apps:

Email Clients

App: Mail, Outlook
Trigger: fup
Replacement: Following up on my previous email...

Code Editors

App: VS Code, Xcode
Trigger: func
Replacement:
function {{name}}({{params}}) {
    {{cursor}}
}

Web Browsers

App: Safari, Chrome
Trigger: lorem
Replacement: Lorem ipsum dolor sit amet...

Managing Expansions

Organization Strategies

1. Naming Conventions

   • Use prefixes: e. for email, c. for code
   • Group by function: addr.home, addr.work
   • Be consistent: all lowercase or camelCase

2. Categories

   • Personal
   • Work
   • Code snippets
   • Templates
   • Quick replies

3. Folders

   • Create folders in expansion manager
   • Drag and drop to organize
   • Enable/disable by folder

Import and Export

Export expansions:

1. Settings → Expansions → Export
2. Choose format (JSON, CSV)
3. Select expansions to export
4. Save file

Import expansions:

1. Settings → Expansions → Import
2. Select file
3. Review expansions
4. Merge or replace

Backup Strategies

• Automatic cloud backup (Pro)
• Manual export weekly
• Version control for teams
• Time Machine compatible

Best Practices

Creating Effective Triggers

Do:

• Use unique combinations unlikely to type normally
• Keep triggers short (3-6 characters)
• Use consistent patterns
• Add context prefixes

Don't:

• Use common words as triggers
• Create triggers that conflict
• Make triggers too long
• Use only lowercase letters

Examples of Good Triggers

Troubleshooting

Expansion Not Working

1. Check trigger spelling
2. Verify expansion is enabled
3. Check app-specific settings
4. Ensure proper permissions

Unwanted Expansions

1. Adjust trigger to be more unique
2. Enable word boundaries
3. Use case sensitivity
4. Add app exclusions

Performance Issues

1. Limit active expansions
2. Optimize complex scripts
3. Clear expansion cache
4. Update Agentastic

Power User Tips

Quick Expansion Creation

• Select text → Right-click → "Create Expansion"
• Use launcher → ⌘+N → Quick create
• Duplicate and modify existing expansions

Expansion Analytics

Track your most-used expansions:

• View usage statistics
• Identify optimization opportunities
• Remove unused expansions

Team Collaboration

• Share expansion libraries
• Maintain team standards
• Version control expansions
• Regular reviews and updates

Next Steps

Master text expansion, then explore:

• AI Completions for dynamic content
• Advanced templating for complex expansions
• Launcher integration for quick access

Text expansion is just the beginning of what Agentastic can do for your productivity!