Skip to content
Projects

mahdiarfrm/conterm has 76 GitHub stars and 5 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 02:47 UTC. Last push 2026-11-09.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

A modern macOS terminal built on libghostty

Developer Tools

README.md

Original

Conterm — a modern macOS terminal

Latest release CI License: MIT GitHub stars Platform

Download · Website · Report a bug

Conterm is a native macOS terminal built on Ghostty's engine. It adds a ⌘K command palette, vertical tabs and tab groups, widgets, notifications, a command center for AI coding agents like Claude Code, Codex and opencode, and live overviews of your SSH hosts, Kubernetes clusters, and containers.

Conterm is an independent frontend built on libghostty. It is not affiliated with, endorsed by, or sponsored by the Ghostty project. The terminal engine (rendering, parsing, fonts, themes, shell integration) is Ghostty's, MIT-licensed; Conterm adds the macOS app around it. Full third-party notices are in NOTICE.md.

https://github.com/user-attachments/assets/afbe93e9-9741-46d3-9eef-1c7b0d62ab64

At a glance

  • Split panes, top or sidebar tabs, tab groups, and full session restore.
  • ⌘K searches commands, shell and clipboard history, SSH hosts, files, notes and every open pane.
  • Claude Code, Codex and opencode report ready / thinking / needs you per pane, with a command center for all of them and a review of what each changed.
  • Host, Kubernetes, container, Ansible and Terraform overviews built from the commands you already run.
  • Orbit maps your sessions and fleet; routines repeat work across hosts.
  • A Liquid Drop interface, with the flat Classic style one click away.

Contents

Install

Download the latest .dmg from the Releases page, open it, and drag Conterm.app into Applications.

First launch: Conterm is ad-hoc signed (open source, not notarized through a paid Apple Developer account), so the first launch needs one step: right-click Conterm.app → Open → Open. If macOS still refuses:

xattr -dr com.apple.quarantine /Applications/Conterm.app

macOS may then ask for access to folders like Documents or Downloads — that's your shell and its tools (git, kubectl, claude) reading files there, which is what a terminal does. Approve once; the grant survives updates.

Requirements

  • macOS 14 (Sonoma) or later — tested through macOS 26 (Tahoe).
  • Apple Silicon (M1 or later). Intel is untested.
  • Liquid Glass / blur chrome requires macOS 26; on 14–15 the app is fully functional with plain chrome.

Updating

Conterm checks GitHub for new releases at launch and once a day while running, and shows an update pill in the toolbar when one is available — click it to install and relaunch. You can also trigger it from Conterm → Check for Updates or Settings → Config, and turn the automatic check off there.

Features

A Conterm window: Claude Code at work beside a kubectl watch and an SSH session

Panes, tabs & sessions

Sidebar tabs with widgets and three split panes
  • Recursive split panes — ⌘D splits right, ⌘⇧D splits down, to any depth. Drag the dividers to resize; focus any pane by number with ⌥1–⌥9.
  • Tabs, top or sidebar — move the tab bar to a left sidebar; it can auto-hide and slide back in when the cursor reaches the left edge.
  • Tab groups — color-coded groups with inline rename, reordering, and a live list of every tab in each group; in the sidebar they fold into collapsible folders.
  • Session restore — every window, tab, pane, split, and working directory comes back exactly where you left it on relaunch.
  • File drops & image paste — drag a file or image onto a pane to insert its shell-quoted path at the cursor; ⌘V with an image on the clipboard (browser "Copy Image", screenshot tools) pastes the same way, so agents like Claude Code can read it. Drop or paste on an SSH pane and it's uploaded instead — scp to the remote working directory, a badge on the pane while it transfers, and the remote path typed at the prompt.
  • Find in scrollback (⌘F) — the terminal's own search engine highlights every match and centers the one you step to (⌘G / ⌘⇧G; ⌘E searches the selection). Panes running Claude Code add a Conversation scope over the session transcript — the only way to search a fullscreen session, whose conversation never touches scrollback — and can hand the query to Claude Code's own transcript search.

Command palette (⌘K)

The command palette over a split window

One search over everything:

  • A single query reaches app commands, shell history (re-run any zsh/bash command), clipboard history (recent copies from panes — session-only, never written to disk), your ~/.ssh/config hosts (with Include support), the active pane's recently modified files, built-in notes, and every open pane across every window.
  • A live calculator in the search bar — arithmetic, 0x/0b/0o literals, re-basing (255 in hex), and unit conversions across data sizes, time, length, mass, volume, and temperature.
  • A suggestion tray under the search bar: five picks ranked by how often and how recently you use them.
  • Tab-group management, quick "open this directory in Finder / Cursor", and reorder or hide commands from Settings → Palette.

Agent-aware

The agent command center listing a Claude session that needs you

An agent's tool-call history Working-tree review of an agent's changes

  • Status pills — a per-pane pill shows when Claude Code, Codex or opencode is ready, thinking, or needs you, with a notification center for what finished while you were away. Hooks are installed non-destructively (Claude's in ~/.claude/settings.json, Codex's in ~/.codex/hooks.json; both run one script).
  • Tool bubbles — whatever Claude or Codex is doing pops up beside the pill as a monochrome bubble, one per kind in flight, its ring sweeping in that kind's colour: terraform, ansible, kubectl, helm, docker, ssh, git, gh, plain shell, reading and editing files, searching code, web search and fetch, sub-agents, task lists, skills, MCP tools. The cluster stays centred as bubbles come and go; finished calls fold into a glass History capsule at the pane's top-left. Click either for each call's command, duration, verdict and output; an Agent Tools palette command opens the same record for the focused pane.
  • Command center (⌘⇧A) — a docked rail listing every running agent across all windows, needs you first. Each card shows its branch, the task it's working on, live cost / burn rate / tokens / model, and how long since it last acted — with jump-to-pane, search-in-conversation, and an inline reply / accept / interrupt. claude --bg background sessions join the roster with one-click resume, and a Next Blocked Agent palette command cycles through the agents waiting on you. A toolbar pill appears with the running count.
  • Agents layout — a third window layout whose sidebar is the live agent roster; an Add agent button opens Claude Code, Codex or opencode in a directory you pick — or one you have worked in before, listed for you — and a panes dropdown jumps to any open pane. A session started somewhere Claude has never run says it is waiting on the trust prompt rather than reading as idle.
  • Command markers (shell integration) — a ✓ / ✗ chip with the run time when a command fails or takes a while, a notification when a long command finishes while you've stepped away, and ⌘↑ / ⌘↓ to jump between prompts.
  • Working-tree review — the pill says the agent is thinking; this says what it changed. Each agent card carries a live count of the files it has touched since it started, with the insertions and deletions; click through for the full picture — the commits it made, every file still uncommitted, and the diff of whichever one you pick. Reviewed re-baselines, so the next look starts from what you just read. Also on ⌘K → Review Changes.
  • While you were away — come back after a real absence and one card sums up what happened: agents that finished or got blocked, playbooks and rollouts, cluster alerts, failed commands, and any changes left unreviewed. The threshold for "away" is yours to set; ⌘K opens it on demand.

The While you were away briefing

Hosts & clusters

Host Overview of an Ubuntu server Cluster Overview of a Kubernetes context

Ansible run report: hosts by tasks Terraform plan card

  • Host Overview — right-click an SSH pane (or click the ⓘ beside its title pill) for a glass briefing on the machine: load, memory, disks, network, containers, VMs, Kubernetes, crons and timers, failed units, recent journal and kernel errors, logins, and pending updates — gathered in one key-authenticated SSH round trip. A status gem sums the host: green up, amber wants attention, red in trouble.
  • Fleet run — pick hosts in the palette, type one command, and get a tab with a pane per host running it over SSH — or leave the command empty to just connect everywhere.
  • Kubernetes context — a tab-bar pill shows where kubectl points; production contexts turn it red and put a red glow on the focused pane's border. Click to switch context: by default a switch applies to the focused pane only (exported silently into that shell), so new panes start on your default — or flip one toggle to make switches global. Rollouts (rollout restart, set image, scale, apply) trace a progress rim around the pill as replicas come ready — green on completion, red on a stall, with notifications for both.
  • Cluster Overview — every context row in the Kubernetes popover opens a briefing card on that cluster: nodes with pressure bars, workloads with per-pod health dots and ready bars, services, Helm releases, and recent warning events, across every namespace — a header chip narrows to one. An optional watcher polls pod health in the background, sums it in a status gem on the pill, and notifies when a pod starts crash-looping.
  • Containers — running containers across Docker, Podman, containerd, and Apple's container in one pill, grouped by runtime in its popover; hover a row to shell in, tail its logs, or restart it.
  • Ansible cockpit — running ansible-playbook in a pane mirrors the run (console untouched) into a live hosts × tasks matrix: per-cell results, task durations with a slowest callout, the changed footprint, and a failure feed with messages. A widget tracks runs across all windows and keeps the machine's most recent report across relaunches.
  • Terraform cockpit — terraform plan (or tofu plan) comes back as a card instead of a wall of ~ and ->: what it destroys and replaces first, then what it creates and updates, with the attributes each update actually touches. The saved plan is read back with terraform show -json and deleted immediately — a plan file carries state values, secrets included. Off in Settings → Integrations if you'd rather terraform not save a plan at all.

Orbit — the fleet as a map (beta)

Orbit: sessions, hosts and the cluster context as a graph

Orbit is new and still settling — the shape is there, the edges are not. Treat it as beta.

  • A layout mode, not a panel (⌘⇧M) — entering Orbit collapses the tab bar and gives the window to a live graph of what you are working on: your agent sessions, the hosts they talk to, the clusters and containers under them, and the plan's own running work. A session is the subject and a host is where it runs, so sessions ride the ring closest to your Mac.
  • Everything happens here — Connect docks a real terminal at the foot of the canvas (⇧⌘F gives it the whole thing), overviews and logs open as panels over the map, and a run's output comes back to it. Nothing sends you out to a tab.
  • Find anything (⌘K) — hosts, sessions, clusters, containers, pods and routines by name, including hosts you have never connected to and ones from ~/.ssh/config. Return brings the match to the middle and aims the action bar at it.
  • Drive it from the keyboard — holding ⌥ lights a letter on every card; press it to aim there, and the arrows walk the graph from there. Every verb on the action bar has a key, and ? lists them.
  • Since you looked away — leaving writes a snapshot, entering reports the difference: a session that started waiting on you, one that finished while you were gone, a scheduled run that failed, a host that came or went.
  • Routines — named, parameterised, repeatable work: add a key to twelve servers, deploy, go to maintenance mode. Write the steps once, fill in the details at launch, and run them now, at a time, or after something else finishes. The engine runs app-wide, so they fire whether or not the map is on screen, and failures notify.
  • What each host said — a run's history records every target separately, so a step across twelve machines reports 11/12 ok, names the one that didn't, and opens what any of them actually said.
  • Guard rails on production — anything named like production (the same pattern list the Kubernetes pill uses, applied to hosts too) puts a confirmation in front of scaling, rolling, cordoning, a real Ansible run or a routine — naming what is about to happen and where.
  • Drill in — a host blooms open into its containers, VMs and kubelet; a cluster into nodes, pods and containers, each with its own verbs. An overview map keeps the whole graph in one corner when you have zoomed in.

Conterm for iOS

Conterm for iOS home: a Mac, two live shells, activity and heartbeat Studio Mac's sessions on the phone, one Claude waiting A Mac pane mirrored on the phone Host Overview of web-01, sampled live

  • Your sessions on your phone — every window, tab and pane, which agent is waiting on you, and a reply back to it. Conterm publishes what it's doing to a file the phone reads over the SSH connection you already have: no listening port, no account, no relay, and nothing to authenticate that your own key doesn't already cover. It works from anywhere you can reach the machine, jump hosts included.
  • Nearby — the Mac advertises itself on the local network, so the phone lists it instead of asking you to type a hostname. The advertisement carries the username to prefill and whether Remote Login is actually accepting connections, so a host that would refuse never gets offered.
  • Pairing — the phone makes an SSH key and sends the public half over the local network; Conterm shows a six-digit code computed from that key, the phone shows the same one, and Allow here puts the key in ~/.ssh/authorized_keys. The reply carries this Mac's host key fingerprints so the phone trusts the right host on its first connection. No password is typed anywhere. If Remote Login is off, the key is still installed and System Settings opens on the switch.
  • A pane on the phone — the phone can attach to any pane. Conterm mirrors that pane's screen to a file while the attach is renewed: its text always, and when the phone asks, its pixels too, captured from the window twice a second (Screen Recording permission). The phone's keys and typed text arrive as real key events, so a TUI sees a real Return and a real Escape. The mirror lapses three minutes after the phone stops renewing it.
  • Off until you ask for it, in Settings → Integrations. Nothing is published while it's off.

Updates and backups

  • Automatic updates — checked from GitHub at launch and once a day while running; a Liquid Glass pill appears in the toolbar when a new release is out, or run Check for Updates any time. No external service involved.
  • Backup & restore — save your sessions, app settings, and Conterm + Ghostty config to a single file, and restore them on another machine (Settings → Config).

Appearance

Settings in the Liquid Drop interface
  • Liquid Drop interface — panels open as a drop of glass: the rim bends the live terminal behind it with a soft colour fringe, the body frosts it, and content rolls in once the drop has settled. Settings, the command palette, the briefing pages, Orbit's side panels, the agents sidebar and the close prompt share it; the selected tab is a drop that flows from tab to tab. Classic, the flat-card interface, stays one click away (Settings → Appearance → Interface, or the setup wizard).
  • Liquid Glass chrome (macOS 26) — refractive glass behind every surface with a Clear↔Frosted slider and light/dark tint, plus an opaque Solid mode when you want it. On macOS 14–15 the app runs fully with plain (non-glass) chrome.
  • Widgets — glanceable pills in the tab bar or sidebar: system stats, clock, battery, git status, GitHub PR checks, ping, public IP (VPN-aware), notes, session streaks, Ansible runs, the kubectl context (with a click-to-switch popover), containers across runtimes (Docker, Podman, containerd, Apple's container), and a pixel cat. Enable and reorder them in Settings → Widgets.
  • Interface size — one slider scales the chrome around the terminal — tab bar, sidebar, toolbar, agent rail — without touching the terminal's own font size (Settings → Interface size). Pane corners are tunable on their own axis.
  • A pane that needs you says so — its border pulses amber while its agent waits on input, and so does its tab's dot, so a background tab that has stopped is visible from whichever one you are in.
  • Right-to-left text — Farsi, Arabic and Hebrew render with joined letters, reading right to left inside an otherwise left-to-right line, so a TUI's layout stays put. A ligature such as لا spans the cells of the letters it joins.
  • SSH-host detection in the pane chrome, and synthesized UI sound effects.

Keyboard shortcuts

Shortcut Action
⌘T / ⌘N New tab / new window
⌘W Close active pane (or tab)
⌘D / ⌘⇧D Split right / split down
⌥1–⌥9 Focus pane N in the current tab
⌘1–⌘9 Jump to tab N
⌘↑ / ⌘↓ Jump to previous / next prompt
⌘K Command palette
⌘⇧A Agent command center
⌘⇧M Orbit — the fleet map
⌘F Find in scrollback / Claude conversation
⌘G / ⌘⇧G Next / previous match
⌘E Use selection for find
⌘, Settings
Esc Dismiss palette / settings / search

Configuration

Conterm reads a single file: ~/.config/conterm/config, in Ghostty's config syntax. Settings → Config shows the path and offers Open / Reload / Reset actions.

Already use Ghostty? Add a one-line include so both apps share settings:

config-file = ~/.config/ghostty/config

Edits in either file then apply to both on the next reload; anything written below the include overrides Ghostty's value for Conterm only. Safe mode (Settings → Config) boots on Ghostty's built-in defaults and ignores the file — useful for recovering from a bad edit.

A few common options:

font-family = "JetBrains Mono"
font-size = 14

cursor-style = bar             # bar | block | underline
cursor-style-blink = true

background-opacity = 0.9
background-blur = 20

# command = "/opt/homebrew/bin/fish"   # default is $SHELL

New windows, tabs and splits start in the directory you were in. Each reads its own key, so you can change your mind for one without touching the rest; turn one off and libghostty's working-directory decides instead — home, inherit, or a path of your own.

window-inherit-working-directory = true
tab-inherit-working-directory = false
split-inherit-working-directory = true

working-directory = home       # where the ones turned off start

Backup & restore

From Settings → Config, Back Up writes a single .contermbackup file containing your app settings, sessions, notes, tab groups, and both the Conterm and Ghostty config files. Restore reads it back and relaunches — handy when moving to a new machine.

Privacy

No account, no telemetry, no server of Conterm's own. The requests it makes:

  • Update check — the GitHub releases API, at launch and once a day. Off in Settings → Config.
  • Public IP widget (when enabled) — api.ipify.org, falling back to checkip.amazonaws.com and icanhazip.com.
  • Ping widget (when enabled) — a TCP connect to 8.8.8.8:53.
  • Host Overview — the distribution's logo, fetched by name from the simple-icons CDNs once and cached.

Everything else — agent status, host and cluster overviews, the GitHub widget (through your own gh) — runs on your Mac or over connections you already make. Clipboard history stays in memory. The iOS companion is off until you turn it on; then the Mac advertises itself and pairs on the local network, and everything else goes over your own SSH.

Building from source

Requires the Swift toolchain (Command Line Tools is enough — no full Xcode):

xcode-select --install

git clone https://github.com/mahdiarfrm/conterm.git
cd conterm

bash scripts/setup.sh    # fetch GhosttyKit.xcframework
bash scripts/build.sh    # build + assemble Conterm.app
open ./Conterm.app

scripts/build.sh produces a release, arm64, ad-hoc-codesigned Conterm.app with the bundled config, terminfo, and icon.

Working on Conterm from inside Conterm? scripts/dev.sh builds a second copy named Conterm Dev and launches it against its own state home, so it keeps its own session, settings and log rather than restoring — and then overwriting — the ones belonging to the Conterm you are typing in:

bash scripts/dev.sh          # build + launch
bash scripts/dev.sh stop     # kill it
bash scripts/dev.sh log      # tail its own diagnostic log
bash scripts/dev.sh reset    # throw its state away

Any build does the same when given CONTERM_STATE_HOME. An instance that cannot claim the session file neither restores nor saves it, so two Conterms never trade windows even without the variable.

The screenshots in this README come from scripts/demo/screenshots.sh. It runs Conterm against a staged user home (CONTERM_USER_HOME) with made-up repos, hosts, a cluster and agent sessions, over a backdrop that hides every other window. Only your look comes along (fonts, colours, glass); DEMO_LOOK=plain uses the defaults. It needs Homebrew's openssh, whose sshd plays the remote hosts.

setup.sh fetches the prebuilt GhosttyKit at the pinned commit. Official releases instead ship a GhosttyKit built from source with the local patches in patches/ghostty/: a renderer-teardown fix (reported upstream), right-to-left shaping (ghostty#11079, unmerged), and RTL ligatures stretched across their cells. To build that kit yourself:

bash scripts/build-ghostty.sh install   # clone pin, apply patches, zig build, install

The script fetches the pinned zig toolchain on its own if needed; the pin constants live in scripts/ghostty-pin.sh. The universal build needs more memory than an 8 GB Mac has; the GhosttyKit workflow runs the same script on a GitHub runner whenever the patches or build scripts change, and uploads the kit as an artifact.

How it fits together

Conterm is a SwiftUI + AppKit app that drives libghostty through GhosttyKit.xcframework. Each pane owns a ghostty_surface_t and the NSView it renders into. The split tree is laid out by AppKit (PaneTreeView), which reframes a surviving pane across splits and closes rather than rebuilding it; SwiftUI handles tabs, the palette, per-pane chrome and the glass surfaces. The terminal core — GPU rendering, parsing, fonts and ligatures, themes, and shell integration — is entirely Ghostty's.

Sources/Conterm/
  Main.swift        @main + AppDelegate, window management
  State/            tabs, pane tree, preferences, stores
  Ghostty/          libghostty Swift bridge (surfaces, input)
  UI/               SwiftUI shell: palette, tabs, chrome, effects

Contributions and issue reports are welcome on the issue tracker.

License

MIT — see LICENSE. Built on libghostty; not affiliated with the Ghostty project.