macOS Actions

Overview

RCLI provides 43 macOS actions that allow you to control your Mac using voice or text. The LLM automatically routes your intent to the appropriate action, executes it via AppleScript or shell commands, and returns the result.

Voice-Activated

Speak naturally - the LLM understands intent

Text Commands

Use rcli ask "<command>" for scripting

Tool Calling

LLM-native tool formats (Qwen3, LFM2)

Enable/Disable

Customize which actions are available

Action Categories

Productivity

Action	Description	Example
`create_note`	Create a note in Apple Notes	”Create a note called Meeting Notes”
`create_reminder`	Create a reminder with due date	”Remind me to call John tomorrow”
`run_shortcut`	Execute Apple Shortcuts	”Run my morning routine shortcut”

Communication

Action	Description	Example
`send_message`	Send iMessage or SMS	”Send a message to Alice saying I’m running late”
`facetime_call`	Start FaceTime video call	”FaceTime Bob”
`facetime_audio`	Start FaceTime audio call	”Call Mom on FaceTime audio”

Media

Action	Description	Example
`play_on_spotify`	Search and play on Spotify	”Play some jazz on Spotify”
`play_apple_music`	Play from Apple Music library	”Play my workout playlist”
`play_pause_music`	Toggle play/pause	”Pause the music”
`next_track`	Skip to next track	”Next song”
`previous_track`	Go to previous track	”Previous track”
`set_music_volume`	Adjust music volume	”Set music volume to 50”
`get_now_playing`	Get current track info	”What’s playing?”

System

Action	Description	Example
`open_app`	Launch an application	”Open Safari”
`quit_app`	Quit an application	”Quit Chrome”
`set_volume`	Set system volume	”Set volume to 75”
`toggle_dark_mode`	Switch light/dark mode	”Turn on dark mode”
`lock_screen`	Lock the Mac	”Lock my computer”
`screenshot`	Capture screenshot	”Take a screenshot”
`search_files`	Search files with Spotlight	”Find my tax documents”
`open_settings`	Open System Settings	”Open settings”
`open_url`	Open URL in browser	”Open github.com”
`get_battery`	Get battery status	”What’s my battery level?”
`get_wifi`	Get WiFi network name	”What WiFi am I connected to?”
`get_ip_address`	Get IP address	”What’s my IP address?”
`get_uptime`	Get system uptime	”How long has my Mac been running?”
`get_disk_usage`	Get disk space info	”How much disk space do I have?”

Window Management

Action	Description	Example
`close_window`	Close active window	”Close this window”
`minimize_window`	Minimize active window	”Minimize the window”
`fullscreen_window`	Toggle fullscreen	”Make this fullscreen”
`get_frontmost_app`	Get active app name	”What app is open?”
`list_apps`	List running apps	”What apps are running?”

Action	Description	Example
`search_web`	Google search	”Search for Apple Silicon benchmarks”
`search_youtube`	YouTube search	”Find videos about Qwen3”
`get_browser_url`	Get active tab URL	”What URL am I on?”
`get_browser_tabs`	List all open tabs	”What tabs do I have open?”
`open_maps`	Open Apple Maps	”Navigate to the Golden Gate Bridge”

Clipboard

Action	Description	Example
`clipboard_read`	Get clipboard content	”What’s in my clipboard?”
`clipboard_write`	Set clipboard content	”Copy ‘Hello World’ to clipboard”

Tool Calling Architecture

RCLI uses LLM-native tool calling with model-specific formats:

User Input

Voice or text command: “Open Safari”

STT Transcription

Speech converted to text via Zipformer/Whisper

LLM Processing

LLM receives prompt with tool definitions and user query

Tool Call Generation

LLM outputs structured tool call:

<tool_call>
{"name": "open_app", "arguments": {"app_name": "Safari"}}
</tool_call>

Action Execution

Tool engine dispatches to action handler:

// From src/actions/app_control_actions.cpp:15-45
ActionResult open_app(const std::string& args) {
    // Parse JSON args
    // Execute AppleScript
    return {success: true, output: "Opened Safari"};
}

Result to LLM

Execution result fed back to LLM:

{"success": true, "output": "Opened Safari"}

Natural Response

LLM generates friendly response: “Done! Safari is now open.”

TTS Output

Response synthesized and played via Piper/Kokoro

AppleScript Executor

Most actions are implemented using AppleScript for macOS automation:

// From src/actions/applescript_executor.cpp:20-75
ActionResult execute_applescript(const std::string& script) {
    // Escape script for shell
    std::string cmd = "osascript -e " + shell_quote(script);
    
    // Execute with popen
    FILE* pipe = popen(cmd.c_str(), "r");
    
    // Read output
    std::string output;
    char buffer[1024];
    while (fgets(buffer, sizeof(buffer), pipe)) {
        output += buffer;
    }
    
    int exit_code = pclose(pipe);
    return {exit_code == 0, output};
}

All AppleScript is executed synchronously with a 10-second timeout to prevent hanging.

Example: create_note Action

// From src/actions/notes_actions.cpp:12-45
ActionResult create_note(const std::string& args) {
    // Parse JSON: {"title": "...", "body": "..."}
    std::string title, body;
    parse_json_args(args, title, body);
    
    // Build AppleScript
    std::string script = R"(
        tell application "Notes"
            make new note with properties {name:"" + title + "", body:"" + body + ""}
        end tell
    )";
    
    // Execute
    auto result = execute_applescript(script);
    
    if (result.success) {
        return {true, "Created note: " + title};
    } else {
        // Fallback: use 'memo' CLI if AppleScript fails
        std::string cmd = "echo '" + body + "' > ~/Notes/" + title + ".txt";
        system(cmd.c_str());
        return {true, "Created text file: " + title};
    }
}

Managing Actions

Enable/Disable Actions

You can control which actions are available to the LLM:

Interactive TUI
CLI
C API

Press A in the TUI to open the Actions panel:

Arrow Keys: Navigate actions
SPACE: Toggle enable/disable
ENTER: Execute action directly
ESC: Close panel

Changes are persisted to ~/Library/RCLI/config/actions.json.

# List all actions
rcli actions

# Show action details
rcli actions create_note

# Execute action directly with JSON args
rcli action create_note '{"title":"Test","body":"Hello"}'

// Enable/disable programmatically
rcli_set_action_enabled(handle, "send_message", 0);

// Check if enabled
int enabled = rcli_is_action_enabled(handle, "send_message");

// Persist preferences
rcli_save_action_preferences(handle);

Tool Definition Filtering

For small LLMs (< 2B params), RCLI uses top-k relevance scoring to filter tool definitions:

// From src/tools/tool_engine.cpp:145-200
std::string ToolEngine::get_filtered_tools(const std::string& query, int k) {
    // Score each tool by keyword match
    std::vector<std::pair<int, std::string>> scored_tools;
    for (const auto& tool : all_tools_) {
        int score = compute_relevance(query, tool.keywords);
        scored_tools.push_back({score, tool.name});
    }
    
    // Sort and take top-k
    std::sort(scored_tools.rbegin(), scored_tools.rend());
    return build_tool_json(scored_tools, k);
}

This reduces context overhead from ~12K tokens (all 43 tools) to ~2K tokens (top 7 tools).

Tool Call Trace

Press T in the TUI to enable tool call tracing. Every tool call and result will be displayed inline:

> open Safari
  ~ [TRACE] Tool call: open_app({"app_name": "Safari"})
  ~ [TRACE] open_app -> OK: {"success": true, "output": "Opened Safari"}
  RCLI: Done! Safari is now open.

Use rcli bench --suite tools to benchmark tool-calling accuracy:

rcli bench --suite tools
rcli bench --all-llm --suite tools  # Compare across models

Safety Considerations

Communication Actions: Actions like send_message and facetime_call have no confirmation prompt. The LLM will execute them immediately. To prevent accidental messages, disable these actions when not needed.

Recommended Practice: Keep sensitive actions (messages, shortcuts) disabled by default. Enable them temporarily when needed, then disable again.

Next Steps

Action Details

See complete action reference with parameters

Adding Actions

Learn how to implement custom actions

Voice Pipeline

Understand the STT → LLM → TTS flow

Commands

Explore all RCLI commands

Get Started

Core Features

Commands

Models

Actions

Advanced

Development

macOS Actions

Overview

Voice-Activated

Text Commands

Tool Calling

Enable/Disable

Action Categories

Productivity

Communication

Media

System

Window Management

Web & Navigation

Clipboard

Tool Calling Architecture

AppleScript Executor

Example: create_note Action

Managing Actions

Enable/Disable Actions

Tool Definition Filtering

Tool Call Trace

Safety Considerations

Next Steps

Action Details

Adding Actions

Voice Pipeline

Commands

Build docs developers (and LLMs) love

Get Started

Core Features

Commands

Models

Actions

Advanced

Development

​Overview

Voice-Activated

Text Commands

Tool Calling

Enable/Disable

​Action Categories

​Productivity

​Communication

​Media

​System

​Window Management

​Web & Navigation

​Clipboard

​Tool Calling Architecture

​AppleScript Executor

​Example: create_note Action

​Managing Actions

​Enable/Disable Actions

​Tool Definition Filtering

​Tool Call Trace

​Safety Considerations

​Next Steps

Action Details

Adding Actions

Voice Pipeline

Commands

Build docs developers (and LLMs) love

Overview

Action Categories

Productivity

Communication

Media

System

Window Management

Web & Navigation

Clipboard

Tool Calling Architecture

AppleScript Executor

Example: create_note Action

Managing Actions

Enable/Disable Actions

Tool Definition Filtering

Tool Call Trace

Safety Considerations

Next Steps