AgentScript 101: native Swift scripts that run with Agent!'s full permissions

[AgentiLoop]

AgentScript is the part of Agent! that gets the least attention and does the most heavy lifting, so here's a walkthrough.

What it is

An AgentScript is a plain Swift file in ~/Documents/AgentScript/agents/Sources/Scripts/. Agent! compiles it with SwiftPM into a .dylib, then dlopens it inside Agent!'s own process — which means the script inherits every TCC grant Agent! has: Accessibility, Automation, Calendar, Contacts, Mail, Photos, and so on. No separate permission prompts, no shelling out to osascript.

About 35 examples ship in the folder: Hello, TodayEvents, NowPlaying, CheckMail, ListReminders, QuitApps, SendMessage, CreateDmg, ArchiveXcode, and more.

The minimum script

import Foundation

@_cdecl("script_main")
public func scriptMain() -> Int32 {
    print("Hello from AgentScript! 👋")
    return 0
}

Rules: no top-level code, no exit(). Whatever you print goes back to the LLM as the tool result; the return value is the exit status.

Talking to Mac apps: ScriptingBridge

51 typed app bridges are pre-wired. Any import XBridge line is auto-detected — no Package.swift edits:

import Foundation
import ScriptingBridge
import MusicBridge

@_cdecl("script_main")
public func scriptMain() -> Int32 {
    guard let music: MusicApplication = SBApplication(bundleIdentifier: "com.apple.Music") else { return 1 }
    music.playpause?()
    return 0
}

Bridges exist for Music, Mail, Safari, Pages, Keynote, Numbers, Finder, System Events, Calendar, Contacts, Notes, Reminders, Messages, Photos, TextEdit, Preview, Terminal, QuickTime, Shortcuts, Xcode and more. When AppleScript is shorter, NSAppleScript(source:) works in the same file — mix freely.

Passing data in

The LLM never sets environment variables itself. It calls agent_script(action:"run", name:"TodayEvents", arguments:"days=3,json=true") and Agent!'s ScriptService exports two variables into the process:

Variable	When set	Meaning
AGENT_PROJECT_FOLDER	Always	The active tab's project folder (also the cwd)
AGENT_SCRIPT_ARGS	Only when arguments: was passed	The string, verbatim

The shipped scripts use key=value,key=value by convention, but it's just a string — ArchiveXcode takes positional args, CreateDmg takes --flag style.

For structured I/O the scripts read/write plain JSON files under ~/Documents/AgentScript/json/ (SendMessage_input.json, TodayEvents_output.json, …) with JSONSerialization. That's a separate mechanism from the env vars — Agent! doesn't create or parse those files, the script does.

Lifecycle

agent_script supports list / read / create / update / edit / run / delete / combine / restore / pull / list_backups.

• delete never loses work — the script goes to ~/Documents/AgentScript/agents/.Trash/ and restore brings it back.
• pull fetches the upstream original from the AgentScripts repo if you want to reset a script you've modified.

Why not just AppleScript?

You can — Agent! has applescript and javascript (JXA) tools too. AgentScript is for when you want real Swift: typed APIs, Foundation, URLSession, EventKit, Vision, whatever. It's the escape hatch that turns "the agent can run a command" into "the agent can write a native program and run it with full permissions."

If you've written a script worth sharing, post it in Show and tell — or open a PR against the AgentScripts repo.