AppleScript (macOS)

macOS 上的 Ghostty 暴露了原生 AppleScript 字典，因此脚本可以查询并控制终端窗口、标签页和分屏窗格。 这让 Ghostty 很容易与 osascript 等工具、 launcher 工作流、编辑器插件以及自定义自动化 脚本集成。

AppleScript 支持从 Ghostty 1.3.0 开始引入。

AppleScript API 的权威来源是 Ghostty 脚本定义文件： Ghostty.sdef。查看 它的最佳方式是将其加载到 Script Editor 中， 然后使用 macOS GUI 浏览 API。

若要从已安装的应用包中查看字典：

sdef /Applications/Ghostty.app | less

要验证脚本是否能运行：

osascript -e 'tell application "Ghostty" to get version'

Ghostty 的 AppleScript 模型是按 层次组织的：

application -> windows -> tabs -> terminals

对象	关键属性	关键元素
application	name, frontmost, front window, version	windows, terminals
window	id, name, selected tab	tabs, terminals
tab	id, name, index, selected, focused terminal	terminals
terminal	id, name, working directory	None

front window 返回最前端的 Ghostty 窗口。focused terminal 返回标签页中处于活动状态的终端，对 操纵当前具有焦点的任何终端的脚本很 有用。

tell application "Ghostty"
    set win to front window
    set tab1 to selected tab of win
    set term1 to focused terminal of tab1
    set allTermsInWin to terminals of win

    set cwdMatches to every terminal whose working directory contains "ghostty"
end tell

这两个属性让当前活动上下文的脚本更加简练：

tell application "Ghostty"
    set term to focused terminal of selected tab of front window
    input text "pwd\n" to term
end tell

tell application "Ghostty"
    set currentTerm to focused terminal of selected tab of front window
    set newTerm to split currentTerm direction right
    input text "echo split-ready\n" to newTerm
end tell

命令	用途	语法示例
new surface configuration	创建可重复使用的 surface 配置记录。	set cfg to new surface configuration
new window	创建新窗口。	set win to new window with configuration cfg
new tab	在可选的目标窗口中创建新标签页。	set t to new tab in win with configuration cfg
split	分割一个终端，并返回新终端。	set t2 to split t1 direction right with configuration cfg

split direction 的值有：right、left、down、up。

命令	用途	语法示例
focus	让终端取得焦点并将其窗口提到最前面。	focus t1
activate window	将窗口置于最前面。	activate window (window 1)
select tab	选择标签页。	select tab (tab 2 of window 1)
close	关闭终端。	close (terminal 2 of selected tab of window 1)
close tab	关闭标签页。	close tab (tab 2 of window 1)
close window	关闭窗口。	close window (window 1)

命令	用途	语法示例
input text	发送粘贴样式的文本输入到终端。	input text "echo hello" to t1
send key	发送带可选修饰键的按下/松开按键事件。	send key "enter" to t1
send mouse button	发送鼠标按键事件。	send mouse button left button to t1
send mouse position	发送指针位置更新。	send mouse position x 240 y 120 to t1
send mouse scroll	发送带精度/动量选项的滚动事件。	send mouse scroll x 0 y -8 precision true to t1
perform action	对终端执行 Ghostty 动作字符串。	perform action "toggle_fullscreen" on t1

对于 send key 和 send mouse button，action 可以是 press 或 release。modifiers 是一个以逗号分隔的字符串，可包含以下任意 项： shift、control、option、command。

对于 perform action，动作字符串与 keybind 配置中 使用的动作名称相匹配。参见 键位动作参考。

new surface configuration 会创建可重复使用的值记录，并能传给 new window、new tab 与 split。

支持的字段包括：

• font size
• initial working directory
• command
• initial input
• wait after command
• environment variables（KEY=VALUE 字符串组成的列表）

示例：

tell application "Ghostty"
    set cfg to new surface configuration
    set initial working directory of cfg to POSIX path of (path to home folder) & "src/ghostty"
    set font size of cfg to 13
    set environment variables of cfg to {"EDITOR=nvim", "FZF_DEFAULT_OPTS=--height 40%"}

    set win to new window with configuration cfg
end tell

macOS 上默认启用了 AppleScript 支持。 macOS 采用自动化权限（TCC）来保护应用与应用之间的 自动化，因此当其他应用试图控制 Ghostty 时， 系统会先弹出提示。

如果你想完全停用 AppleScript 支持，可以这样设置：

macos-applescript = false

set projectDir to POSIX path of (path to home folder) & "src/ghostty"

tell application "Ghostty"
    activate

    set cfg to new surface configuration
    set initial working directory of cfg to projectDir

    set win to new window with configuration cfg
    set paneEditor to terminal 1 of selected tab of win
    set paneBuild to split paneEditor direction right with configuration cfg
    set paneGit to split paneEditor direction down with configuration cfg
    set paneLogs to split paneBuild direction down with configuration cfg

    input text "nvim ." to paneEditor
    send key "enter" to paneEditor

    input text "zig build -Demit-macos-app=false" to paneBuild
    send key "enter" to paneBuild

    input text "git status -sb" to paneGit
    send key "enter" to paneGit

    input text "tail -f /tmp/dev.log" to paneLogs
    send key "enter" to paneLogs

    focus paneEditor
end tell

set cmd to "date"

tell application "Ghostty"
    set allTerms to terminals

    repeat with t in allTerms
        input text cmd to t
        send key "enter" to t
    end repeat

    display dialog ("Broadcasted to " & (count of allTerms) & " terminal(s).")
end tell

请使用 perform action 与 set_tab_title 来在脚本中 为标签页命名。

创建新标签页并设置标题的示例：

tell application "Ghostty"
    set win to front window
    set cfg to new surface configuration

    set t1 to new tab in win with configuration cfg
    perform action "set_tab_title:Editor" on focused terminal of t1
    input text "nvim .\n" to focused terminal of t1

end tell

set needle to "ghostty"

tell application "Ghostty"
    set matches to every terminal whose working directory contains needle

    if (count of matches) = 0 then
        set matches to every terminal whose name contains needle
    end if

    if (count of matches) > 0 then
        set t to item 1 of matches
        focus t
        input text "echo '[focused by AppleScript]'" to t
        send key "enter" to t
    end if
end tell