/push docs

The manual for the terminal that remembers your agent sessions.

Browse the docs
Mac app

The terminal

Tabs that survive quitting, folder and group themes, keep-awake — and how session resume actually works.

Push's terminal is native Mac — rendered by libghostty (Ghostty's engine) with Metal, 5,000 lines of scrollback per tab, and the standard keys where you expect them (full list).

The tab strip

⌘T new tab · ⌘W close · ⌘⇧T reopen closed tab · ⌘R reload · ⌘1–⌘8 jump to a tab, ⌘9 last tab, ⌘⇧[ / ⌘⇧] previous/next.

Tabs title themselves after what's happening inside; Rename Tab… overrides that, Use Automatic Title hands it back. Related tabs can be gathered with New Group… / Add to Group.

The Active filter chip shows only tabs that are running or have new output — the "which agent needs me" view.

Folder chips

Tabs group by working directory. The chip row filters to one folder ("This session's folder") or everything ("Show tabs from every folder"), and a folder's menu offers Open Terminal in Folder and Track This Folder as an Agent — the door into folders-as-agents. There's also a Finder service: right-click a folder in Finder → New Push Terminal Here.

Hover a folder or group chip to manage that scope. Change theme colour selects the scope and opens a live palette with 5%, 10%, 25%, 50%, and 100% tint strengths (10% is the default). The colour belongs to the folder or group, so switching back to All, Active, or Today removes the terminal wash. A group's menu also lists its tabs and can rename or delete the grouping; deleting the group leaves every tab open and asks for confirmation first.

Sessions that survive quitting

The honest sketch of how it works: every tab is pinned to a stable ID that Push injects into the agent's environment. A bundled shell snippet plus the agent's own session-start hook keep a small marker file on disk. When you relaunch Push, the marker says which agent was in the tab and which session to resume — and Push invokes that agent's own resume command, so you land back in the conversation. Marker writes are atomic (crash-safe), survive auto-update, and tolerate a moved working directory. Reopening from history also pins the runtime that created the session — switching a folder from Claude Code to Codex never relabels old sessions.

What that means day to day: ⌘Q is safe. So are updates — the update banner puts it this way: "Your tabs reopen and each session resumes. Scrollback clears, transcripts stay in History."

The per-tab menu

Right-click a tab (or use the tab's hover menu):

  • Go to Issue / Track This Tab / Unlink Session — the session-to-issue loop, covered in Track.
  • Spin Off Session… — bud a follow-up into its own issue.
  • Keep Awake — hold this session while the Mac would otherwise sleep (pairs with Always On).
  • Bypass Permissions — start this runtime unattended; see Agents for exactly what that switch does.
  • Copy Session Information… — the session's identifiers, for support.
  • Show Inspector (⌘I) — files and artifacts for this tab.

Appearance & themes

Push follows the selected app appearance and wires the libghostty palette through to agents — so Claude Code's diffs and status colors look right without you configuring them. A selected folder or group can layer its own theme wash on top; tint is scope-owned, not a per-tab or global strip setting. If a runtime draws its own theme, Push respects appearance changes live rather than leaving half-switched colors behind.

Verified against Push 1.10.197 · Updated 2026-08-24