#Getting Started

coterm is a lightweight, native macOS terminal built on Ghostty for managing multiple AI coding agents. It features vertical tabs, a notification panel, and a socket-based control API.

#Install

#DMG (recommended)

Download for Mac

Open the .dmg and drag coterm to your Applications folder. coterm auto-updates via Sparkle, so you only need to download once.

#Homebrew

brew tap emergent-inc/coterm
brew install --cask coterm

To update later:

brew upgrade --cask coterm

On first launch, macOS may ask you to confirm opening an app from an identified developer. Click Open to proceed.

#Verify installation

Open coterm and you should see:

A terminal window with a vertical tab sidebar on the left
One initial workspace already open
The Ghostty-powered terminal ready for input

#CLI setup

coterm includes a command-line tool for automation. Inside coterm terminals it works automatically. To use the CLI from outside coterm, create a symlink:

sudo ln -sf "/Applications/Coterm.app/Contents/Resources/bin/coterm" /usr/local/bin/coterm

Then you can run commands like:

coterm list-workspaces
coterm notify --title "Build Complete" --body "Your build finished"

#Auto-updates

coterm checks for updates automatically via Sparkle. When an update is available you'll see an update pill in the titlebar. You can also check manually via coterm > Check for Updates in the menu bar.

#Session restore (current behavior)

coterm restores layout and metadata after relaunch. Supported agent sessions can also resume when hooks have captured a native resume token.

coterm does not checkpoint arbitrary live process state. Unsupported terminal apps such as tmux, vim, and ordinary shells reopen as normal terminals.

See the session restore guide for agent hook setup and the supported resume matrix.

#Requirements

macOS 14.0 or later
Apple Silicon or Intel Mac