JustSessions user guide
Resume your AI coding sessions.
Install the app, find your conversation, and continue in the CLI you already use.
Install on your Mac
You need macOS 14 Sonoma or later on Apple Silicon, plus an installed CLI with its usual authentication.
- Download the signed, notarized JustSessions.dmg.
- Open the disk image and drag JustSessions into Applications.
- Launch the app. Existing sessions appear under This Mac, grouped by project.
On first launch, a short tour points out your sessions, New session, and SSH hosts beside the controls themselves. Later tips show the first time you need them, such as Resume when you first read a session and tab groups when you first open a tab. Skip any of them, or see the tour and its tips again from Help → Take the Tour.
App updates arrive through Sparkle; check manually in Settings → General. Read the release notes for what changed. JustSessions is free; your CLI provider's charges still apply.
Find and resume a session
- Search a project name or path, session title, or session ID.
- Select a session to read its conversation preview.
- Double-click a session or choose Resume to continue in its original CLI and project folder.
A session whose CLI is already running opens on that process with one click. The + at the top of the sidebar starts an installed CLI, or Terminal for your login shell; a project's + menu offers the same. Switch between Projects to browse saved sessions and Open tabs to switch terminals. Open tabs are grouped by project, with the remote host when applicable. Both views retain their search and scroll position. Time and CLI filters live beside the switch in Projects, with Running for sessions whose CLI still runs, on this Mac or an SSH host, and Waiting for you for sessions stopped for your answer or done with a turn you haven't seen; filters do not hide open tabs. Search also matches message text and opens a matching session at that message; choose Names only under the field to match only project and session names.
Pin, rename, or export sessions as Markdown. Local Claude Code, Codex, Antigravity, Pi, and OpenCode sessions can notify you when a turn finishes or when they need input.
Read without launching the CLI
The new-window button in the reading toolbar opens the conversation in its own window. Keep it beside your terminal or compare two sessions.
- Press ⌘F to find text in the loaded messages. Use ⌘G and ⇧⌘G to move between matches.
- Press ⌘D to bookmark the message you're reading; its letter, a to z, shows beside it. Use ⌘' and ⇧⌘' to go between bookmarks, and the bookmark button to list them.
- In a tab linked to a session, press ⌘D to bookmark its latest message, and ⌘' or ⇧⌘' to open its reading window at a bookmark.
- Use A− / A+ or ⌘+ / ⌘− to adjust the reading text, the width button to switch between a readable column and the full window width, and the up/down buttons to jump to the first or latest available message.
- Read formatted Markdown, scroll wide tables and code blocks, and copy code with Copy. Tool calls stay collapsed until you expand them.
- See images you attached, and screenshots a tool returned, in place for Claude Code, Codex, and Pi, scaled to the reading column.
- Switch sessions and return to the same reading position while the workspace window stays open. A reading window starts at your current position.
- Long histories load automatically as you scroll near either end, keeping your position within the message. The reader retains three pages, or a few more when short ones are all in view. Automatic loading pauses while Find is open; the page buttons remain available.
Reading is read-only: it does not start a terminal or change the saved conversation. Positions are kept for the window's lifetime. Bookmarks are kept until you remove them or delete the session.
Supported AI coding CLIs
All six support local and SSH sessions, reading, and deletion. In-app branching varies.
| CLI / command | Preview | Branch | SSH | Delete |
|---|---|---|---|---|
Claude Code claude | Yes | Yes | Yes | Yes |
OpenAI Codex CLI codex | Yes | Yes | Yes | Yes |
Google Antigravity CLI agy | Yes | /fork in CLI | Yes | Yes |
Kiro CLI kiro-cli | Yes | Use /rewind in the CLI | Yes | Yes |
OpenCode opencode | Yes | Yes | Yes | Yes |
Pi pi | Yes | Yes | Yes | Yes |
Branching forks a conversation, not a Git branch. Full capability table · Session file locations
Continue on another machine over SSH
Install tmux on the remote host so sessions survive a disconnect or closing a tab. The host runs Linux or macOS and needs rsync and Claude Code, Codex, Antigravity, Kiro CLI, OpenCode, or Pi installed. Windows hosts aren't supported; on a Windows PC, run your CLIs in WSL and connect to WSL over SSH.
Antigravity and OpenCode hosts also need python3; deleting Antigravity sessions needs lsof.
- Choose Add SSH host… in the sidebar.
- Enter a
~/.ssh/configalias oruser@hostname. - Browse the host's projects and resume a session there.
The code and CLI run remotely; supported history is cached on your Mac. JustSessions provides terminal access, not graphical screen sharing.
Upgrading to 1.3.2: some SSH hosts need a fresh connection before their cached history appears again. Remote history is not deleted. Upgrade details.
If the host asks for a password, a key passphrase, or a one-time code, click Connect… on its heading and answer in the app. The host's refreshes and tabs then share that login until it closes, and JustSessions keeps nothing you type.
If the host also needs you to sign in again every so often, as with a credential that expires and asks for a PIN or a code, set its command with Sign-in command… in the host's ⋯ menu. JustSessions runs it when it's due and asks its questions in a dialog.
Detailed SSH setupIf a session opens a shell instead of its CLI
Each CLI on a host starts through your login shell, so it is found wherever your shell's startup files put it. If those files start another program in every interactive shell, such as tmux or zsh, that program's prompt shows instead of the CLI.
JustSessions checks for this when you add a host. If a login shell without your interactive startup still runs the CLIs, the app starts them that way on that host, and the host's ⋯ menu says so. Otherwise a warning shows beside the host's name; point at it to see the line where the startup stopped.
To fix it, make that line run only in interactive shells, and not in the ones JustSessions starts, which have JUSTSESSIONS=1 set: for example if [[ $- == *i* ]] && [ -z "$JUSTSESSIONS" ]; then exec zsh -l; fi. Many hosts' bash also reads ~/.bashrc for commands run over SSH, before JustSessions can set that variable, so checking for a terminal alone isn't enough. Then choose Check this host… from the host's ⋯ menu.
Without your interactive startup, a CLI it puts on your PATH, as nvm's setup does, is missing from New session. Move that setup to ~/.profile, or above the line in ~/.bashrc that stops for non-interactive shells.
If a refresh fails or a session won't resume
A CLI that fails as it starts leaves what it printed in its tab, with its exit status above it; this needs tmux 3.2 or later on the host.
Choose Check this host… from the host's ⋯ menu, or click Check host above a tab that ended; a tab that ended right after it started, or on a host with a warning, shows it as the bar's main button. It checks what JustSessions runs on the host, such as rsync, tmux, and each CLI, and changes nothing there. Problems come first; each shows what the host printed and a command to run in Terminal: if it fails the same way there, the problem is on the host. Copy report copies it all as text.
JustSessions also checks each host on its own: after an app update, once a day, and soon after a tab there ends with an error right after it starts. A problem shows as a warning beside the host's name; click it for the report. Fix with agent… in the report starts a CLI, on the host or on this Mac, whose first message is the report and this guide's advice about it. It is told to ask you before it ends sessions or changes the host's setup.
Use the native terminal.
Agent sessions and plain shells run in an embedded SwiftTerm AppKit terminal, grouped by project. Choose Open tabs to switch terminals. Under Settings → Appearance → Terminal, choose a color scheme or import your iTerm2 colors, or choose Ghostty as the Engine to open new tabs in Ghostty's GPU-drawn terminal instead. Choose View → Show Conversation Map to see each agent tab's whole conversation in a column beside it; click a message to read it. Over SSH it shows the app's copy, which can be a few minutes behind.
Work in split view
Right-click another tab and choose New split view with current tab to show two terminals side by side. Keep an agent next to your shell, or compare two sessions. Click either pane to focus it; drag the divider to resize, or double-click it to reverse the views. Each pane has its own close button. Right-click a split tab to separate the views or replace a pane with another tab. Tabs reopen individually after quitting.
Keep work running with tmux
The app includes tmux for this Mac. Direct swift run builds need tmux 3.3+. SSH hosts need their own tmux. Choose Keep running when closing a local tab, then select its session to reattach.
Quitting the app leaves tmux sessions running. Remote tmux sessions survive SSH disconnections, such as your Mac sleeping, and their tabs reconnect on their own once the host answers again. Keep the machine awake; without tmux, closing the tab ends its process. Plain project terminals do not use tmux.
The app's tmux sessions have no prefix key, so every key reaches the CLI. To use your own tmux prefix on an SSH host, point at the host's heading, click its ⋯, and choose Use this host's tmux prefix.
If a session or CLI is missing
- In Projects, clear the filters, then click the affected host's refresh button.
- Confirm the CLI runs in your usual terminal. New session menus offer only installed tools.
- Start one conversation so the CLI creates history. Kiro sessions need a message; archived OpenCode sessions are excluded. Subagents' sessions are hidden until you turn them on in Settings > General; then expand the session that started them with the chevron before its icon.
- For SSH, check that
sshto the host works in Terminal, and checkrsyncand the remote CLI. A host that asks for a password or a code needs Connect… on its heading. Remote history follows folder settings such asCLAUDE_CONFIG_DIRin the host's login shell; Antigravity always uses its standard folder.
Your history and accounts
No JustSessions account is required. The app reads CLI files and caches supported SSH history locally; it does not upload conversations to a JustSessions service. Your CLIs still communicate with their providers. Sparkle checks for app updates through a JustSessions update server that counts checks per day and app version, without storing IP addresses or identifiers. After a crash, JustSessions offers to report it with a GitHub issue or an email filled in from the crash report macOS saved; nothing is sent unless you send it.
This website counts page views without cookies or visitor identifiers. Only daily totals by page, source category, country, and device type are saved.
Feedback you send from this Guide is stored in a JustSessions database at Cloudflare for up to a year, with the email you add and, when the app opened the form, its app and macOS versions. Only the developer reads it. Cloudflare Turnstile checks that a person sent it; it loads when you start writing feedback, not before.
Storage and privacy detailsFeedback
Tell us what works, what doesn't, and what you'd like next. In the app, Send feedback at the bottom of Settings → General opens this form with your app and macOS versions.