Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/irskep/automate-terminal

Wrapper for terminal automation in iTerm2, tmux, Kitty, Guake, WezTerm, Terminal.app, Ghostty, and VSCode
https://github.com/irskep/automate-terminal

automation cli terminal terminal-emulator

Last synced: 23 days ago
JSON representation

Wrapper for terminal automation in iTerm2, tmux, Kitty, Guake, WezTerm, Terminal.app, Ghostty, and VSCode

Awesome Lists containing this project

README 

          
# automate-terminal



Automate opening of new tabs and windows in terminal programs. Currently supports iTerm2, Terminal.app, Ghostty, Guake, tmux, WezTerm, Kitty, Cursor, and Visual Studio Code.



automate-terminal is a best-effort project. Some terminals do not support automation at all! It's also intended to be used as a component in other tools, so it errs on the side of strictness over fallbacks. See the command reference for specifics.



`automate-terminal` was originally part of [autowt](https://steveasleep.com/autowt/), the git worktree manager.



## Installation



```bash

# mise (recommended)

mise install ubi:irskep/automate-terminal



# ubi

ubi --project irskep/automate-terminal --in ~/bin



# go install

go install github.com/irskep/automate-terminal/cmd/automate-terminal@latest

```



Pre-built static binaries are also available on the [GitHub Releases](https://github.com/irskep/automate-terminal/releases) page for macOS and Linux.



For Guake terminal support on Linux, make sure the `gdbus` CLI from GLib/GIO is on your `PATH`. On most desktop distributions it already is; if you use a minimal system, install the GLib utilities package (e.g., `apt install libglib2.0-bin`, `dnf install glib2`, `pacman -S glib2`, or `apk add glib`).



## Supported Terminals



| Terminal     | Platform       | New Tabs/Windows | Switch by ID | Switch by Working Dir | List Sessions | Paste Commands | Run in Active Session |

| ------------ | -------------- | ---------------- | ------------ | --------------------- | ------------- | -------------- | --------------------- |

| iTerm2       | macOS          | ✅               | ✅           | ✅                    | ✅            | ✅             | ✅                    |

| Terminal.app | macOS          | ✅               | ❌           | ✅                    | ✅            | ✅             | ✅                    |

| Ghostty      | macOS          | ✅               | ❌           | ❌                    | ❌            | ✅             | ✅                    |

| Guake        | Linux          | ⚠️ (tabs only)   | ✅           | ✅                    | ✅            | ✅             | ✅                    |

| tmux         | Cross-platform | ✅               | ✅           | ✅                    | ✅            | ✅             | ✅                    |

| WezTerm      | Cross-platform | ✅               | ✅           | ✅                    | ✅            | ✅             | ✅                    |

| Kitty        | Cross-platform | ✅\*             | ✅\*         | ✅\*                  | ✅\*          | ✅\*           | ✅\*                  |

| VSCode       | Cross-platform | ⚠️ (no tabs)     | ❌           | ✅                    | ❌            | ❌             | ❌                    |

| Cursor       | Cross-platform | ⚠️ (no tabs)     | ❌           | ✅                    | ❌            | ❌             | ❌                    |



\* **Kitty requires `allow_remote_control yes` in `kitty.conf`** to enable automation features.



**Guake** requires only the `gdbus` command (usually provided by GLib/GIO) for DBus communication.



Other terminals are not supported. `automate-terminal` will exit with an error code in unsupported terminals.



## Quick Start



### Command Line



```bash

# Check if your terminal is supported

automate-terminal check



# Create a new tab

automate-terminal new-tab /path/to/project



# Switch to existing session by directory

automate-terminal switch-to --working-directory=/path/to/project



# Create new window with initialization script

automate-terminal new-window --paste-and-run="source .env && npm run dev" /path/to/project



# Run a command in the currently active session

automate-terminal run-in-active-session "git status"

```



## What is possible with terminal automation?



This is the "manage expectations" section of the README.



The scope of automation covered by `automate-terminal` is "create or navigate to a terminal session in a specific working directory."



### What is a terminal emulator?



A terminal emulator, for the purposes of this project, is the thing you type your terminal commands into. For the author, it's iTerm2. For many people, it's the built-in terminal in Visual Studio Code. For hipsters, it's Ghostty. Linux users have more options than I know of, including KConsole. And there's WezTerm, and the built-in terminals for macOS and Windows. Every few years, somebody spins up a new one.



Within terminal emulators, a _session_ is, for the purposes of this project, one specific terminal running a shell. Your sessions might be organized in windows, or tabs, or splits within a window or tab.



### How are they controlled?



In **many different ways**, which is why this problem is complex enough to warrant a library! The ability to open a new tab or window, or switch to a specific existing session based on some criteria, is not standardized _at all_ among terminal emulators. The spread of what is possible for a given terminal emulator is incredibly wide, as shown by the table at the top of this README.



macOS terminals are primarily controlled via AppleScript. iTerm2, for example, has a comprehensive AppleScript API, which is why it has the best support. Ghostty has _no_ AppleScript API at all, so `automate-terminal` uses the `SystemEvents` API to "click" its menu items, and we have no way of knowing which Ghostty tab is in a particular working directory. VSCode also has no AppleScript API, but it does have its `code ` command to open or switch to a specific window.



**tmux** uses its native CLI commands (`tmux list-panes`, `tmux select-window`, `tmux send-keys`, etc.) and works identically across all platforms where tmux is available.



**WezTerm** uses its native CLI commands (`wezterm cli list`, `wezterm cli activate-pane`, `wezterm cli send-text`, etc.) and works identically across all platforms where WezTerm is available.



**Kitty** uses its remote control protocol (`kitten @ ls`, `kitten @ focus-window`, `kitten @ send-text`, etc.) and works across all platforms where Kitty is available. **Note: Kitty requires `allow_remote_control yes` in your `kitty.conf` file to enable automation.**



All this is to say, if you are unhappy with the level of automation provided by `automate-terminal` on macOS, switch to another terminal emulator, or lobby the authors of your favorite one to add automation support.



## Commands



### check



Detect terminal capabilities.



```bash

automate-terminal check

automate-terminal check --output=json

```



Example output:



```

Terminal: iTerm2

Terminal Program: iTerm.app

Shell: zsh

Current session ID: w0t5p1:24AF055B-8BD2-4C7F-AB1E-B310FDCBCEA1

Current working directory: /Users/steve/dev/libraries/automate-terminal



Capabilities:

  can_create_tabs: True

  can_create_windows: True

  can_list_sessions: True

  can_switch_to_session: True

  can_detect_session_id: True

  can_detect_working_directory: True

  can_paste_commands: True

  can_run_in_active_session: True

```



### new-tab



Create new tab in a specific directory, optionally pasting content into the new tab.



The term "paste" here means it will be _as if_ the user pasted text into the new terminal and hit Enter. It doesn't use your system pasteboard.



```bash

automate-terminal new-tab /path/to/dir



automate-terminal new-tab --paste-and-run="echo 'I am in the new directory!'" /path/to/dir

```



There are options to run additional scripts only in specific shells. This is useful if your wrapper tool needs to support multiple shells for workflows that require nontrivial shell commands.



```bash

automate-terminal new-tab --paste-and-run-fish="echo 'I am a fish shell user'" /path/to/dir

```



### new-window



Create new window. Takes the same arguments as `automate-terminal new-tab`.



```bash

automate-terminal new-window /path/to/dir

```



### switch-to



Switch to an existing session, returning an error no matching session can be found or your terminal doesn't provide session information. You can either pass a working directory with `--working-directory`/`--wd`, or a session ID if the session ID is known.



If you pass session ID, working directory is ignored. `--wd` is likely what you want, though.



If you are using an unsupported terminal emulator and want to open a new terminal in a given directory as a fallback, use `new-tab` or `new-window`. `automate-terminal` doesn't do this automatically because it would create unpleasant edge cases for tools that use `automate-terminal`.



```bash

# By working directory (or use --wd alias)

automate-terminal switch-to --working-directory=/path/to/dir



# By session ID (or use --id alias)

automate-terminal switch-to --session-id=w0t0p2:ABC123

```



### list-sessions



List all sessions.



```bash

automate-terminal list-sessions

automate-terminal list-sessions --output=json

```



### run-in-active-session



Run a command in the currently active terminal session.



This command sends the specified command to the active terminal session without switching windows or tabs. It's useful for programmatically executing commands in the terminal session you're currently working in.



```bash

# Run a simple command

automate-terminal run-in-active-session "echo 'Hello World'"



# Run a git command

automate-terminal run-in-active-session "git status"



# Run multiple commands

automate-terminal run-in-active-session "cd /tmp && ls -la"

```



**Note:** This feature requires terminal support. VSCode and Cursor do not support running commands in the active session. Check capabilities with `automate-terminal check` to see if your terminal supports this feature.



## Options



### Output Format



- `--output=text` - Human-readable (default)

- `--output=json` - JSON for programmatic use

- `--output=none` - Silent



On failure, JSON output includes `"success": false` and an `"error"` field with a specific reason. For example, a missing accessibility permission on macOS produces:



```json

{"success": false, "error": "Ghostty failed to create tab (missing accessibility permissions? grant accessibility permissions to the calling application in System Settings -> Privacy & Security -> Accessibility)", "terminal": "Ghostty"}

```



Error messages include actionable remediation hints where possible (e.g. missing CLI tools, missing permissions, missing Kitty remote control config).



### Paste and Run



Execute commands after creating/switching sessions.



```bash

--paste-and-run="echo 'I run unconditionally'"

--paste-and-run-bash="echo 'I only run if the current shell is bash'"

--paste-and-run-zsh="echo 'I only run if the current shell is zsh'"

--paste-and-run-fish="echo 'I only run if the current shell is fish'"

```



Shell-specific flags override generic `--paste-and-run` when detected shell matches.



**Note:** Some terminals (VSCode, Cursor) cannot execute paste scripts programmatically. When using `--output=json`, check the `paste_script_executed` field to determine if you need to run the script manually:



- `true`: The paste script was executed by the terminal

- `false`: The paste script was provided but the terminal cannot execute it (you should run it manually)

- Field omitted: No paste script was provided



### Debug and Dry Run



```bash

--debug     # Enable debug logging to stderr

--dry-run   # Log actions instead of executing them

```



Use `--dry-run` to see what commands would be executed without actually running them (AppleScript for macOS terminals, tmux CLI commands for tmux). Useful for debugging and understanding what the tool will do.



## Go Module



automate-terminal can be imported as a Go library. Module versions follow git tags (`v0.2.0`, etc.), which are the same tags used for binary releases.



```

go get github.com/irskep/automate-terminal@latest

```



Usage:



```go

package main



import (

    "log"



    "github.com/irskep/automate-terminal/detect"

    "github.com/irskep/automate-terminal/exec"

)



func main() {

    runner := &exec.Runner{}

    t := detect.Detect(runner)

    if t == nil {

        log.Fatal("unsupported terminal")

    }



    // Check what the terminal can do.

    caps := t.GetCapabilities()

    if caps.CanCreateTabs {

        if err := t.OpenNewTab("/path/to/dir", nil); err != nil {

            log.Fatal(err)

        }

    }



    // List open sessions.

    for _, s := range t.ListSessions() {

        log.Printf("%s -> %s", s.SessionID, s.WorkingDirectory)

    }



    // Send a command to the active session.

    if err := t.RunInActiveSession("git status"); err != nil {

        log.Fatal(err)

    }

}

```



The three public packages are:



- `terminal` -- the `Terminal` interface, `Capabilities`, `Session`, and all backend implementations

- `detect` -- `Detect(runner)` returns the appropriate backend for the current environment

- `exec` -- `Runner` for subprocess execution (with dry-run support) and `AppleScript` helpers



Full API docs are on [pkg.go.dev](https://pkg.go.dev/github.com/irskep/automate-terminal) once the module is tagged.



## References



- [iTerm2 AppleScript reference](https://iterm2.com/documentation-scripting.html)

- [Kitty automation reference](https://sw.kovidgoyal.net/kitty/remote-control/)

- [WezTerm automation reference](https://wezterm.org/cli/cli/index.html)

- [tmux man page](https://man.openbsd.org/OpenBSD-current/man1/tmux.1)