Skip to content
leeoveryPublic

About

Interactive zmx session manager - Go CLI that gives you fast, fuzzy session management from bare shell, with project memory, path aliases, reboot-safe restoration, and a keyboard-driven TUI.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

🌀 Portal

Interactive session picker for zmx

Fast, fuzzy session management from a bare shell, with project memory,
path aliases, reboot-safe restoration, and a keyboard-driven TUI.

License: MIT Go Platform: macOS

Install · Quick start · Screenshots · How it works · Commands · Documentation · Coming from tmux


Portal's first launch after a reboot: the loading page restores twelve sessions, the picker lands on them, and a restored session's scrollback is previewed

Portal runs at a bare shell and gives you an interactive TUI for picking, creating, and managing zmx sessions. It remembers your projects, resolves paths via aliases and zoxide, auto-detects git roots, and restores your saved sessions after a reboot.

After shell setup you drive it through two functions: x (the picker and opener) and xctl (subcommands like list, kill, alias). Both names are configurable with --cmd.

Why Portal?

zmx keeps sessions alive; getting back into the right one is the chore. Finding it means zmx list and a name you half remember. Starting one in the right place means a cd, a zmx attach and a name to invent. A reboot takes the lot, and bringing sessions back by hand brings every command back with them, all at once, whether you still need it or not.

Portal folds that into two shell functions and a picker:

  • One verb to get anywhere. Open a project by path, alias or zoxide (x work), attach a session by name or glob (x api, x 'api-*'), or search your live sessions by name or directory (x /api). New sessions start at the git root, and Portal remembers your projects.
  • Reboot-safe sessions. After a reboot Portal brings your sessions back, each in its last working directory with its ANSI scrollback.
  • Commands come back when you ask. A session with a resume hook comes back holding a panel showing its command, which runs when you answer it, so a reboot doesn't start every dev server you ever left open.
  • A keyboard-driven picker. It paints its own canvas, with a ? keymap on every page. Six themes ship, matched to your terminal's background unless you pin one; drop-in .theme files restyle every screen, and NO_COLOR is honoured.
  • Grouping and tags. One key flips the list between flat, by project and by tag. Tags live on directories, so every session opened there inherits them.
  • Scrollback preview. Space peeks at any session's screen and scrollback, kept live while it's open, without attaching.
  • Multi-window open. x work api db, or sessions marked with m in the picker, open each in its own terminal window, so a post-reboot window layout is back in one command. Ghostty works out of the box; other terminals through a terminals.json recipe.
  • One terminal at a time. Opening a session takes it from any other terminal showing it, so it is drawn for yours from the first frame.

Screenshots

Portal feature tour: grouping, fuzzy filter, scrollback preview, projects

The full tour: grouping, fuzzy filter, scrollback preview, projects. Stills below; each opens the page that covers it.

Sessions grouped by tag
Grouped by tag
Scrollback preview
Peek-mode scrollback preview
Honest loading screen
Concurrent cold-boot loading
Keybindings help modal
Per-page ? keymap
Projects page
Projects
Edit project modal
Edit project: name, aliases, tags
Live filter
Live fuzzy filter
Kill confirmation modal
Destructive confirm
Resume panel on a restored session
Resume panel after a reboot
Theme picker over the sessions
Theme picker
The theme picker previewing each built-in theme over the sessions

The six built-in themes: Tokyo Night, Tokyo Night Day, Nord, Nord Wave, GitLab Dark Grey and Horizon. The same screens render in light mode and under NO_COLOR (see Themes).

Install

You need macOS and zmx 1.0.1 or later. Portal talks to zmx through its socket protocol 1; 1.0.0 was the first release to speak it, but its macOS downloads don't resize a session. What Portal refuses is in zmx. Building from source needs Go 1.26+.

brew install neurosnap/tap/zmx leeovery/tools/portal

zmx lives in its own tap, which Homebrew won't add or trust for a dependency, so the command names it beside Portal. Or, with Go:

go install github.com/leeovery/portal@latest

go install builds Portal alone: install zmx separately, with brew install neurosnap/tap/zmx or from zmx's getting started guide.

To take Portal off again, see Removing Portal.

Quick start

eval "$(portal init zsh)"              # in ~/.zshrc — defines x and xctl (bash and fish below)

x                                      # the picker: ↑/↓ move, / filter, Space preview, Enter attach
x ~/Code/api                           # new session at the repo's git root
x ~/Code/api -e "make dev"             # ...with a command running in it
x /api                                 # later: search live sessions by name or directory
xctl alias set work ~/Code/work        # alias a path...
x work                                 # ...then open it by name
xctl hook set --on-resume "make dev"   # in a session: bring its command back after a reboot
xctl doctor                            # save daemon running? state sane? anything stale?

Your sessions are saved as you work. After a reboot the first x rebuilds them; see How it works.

While attached, Alt+D detaches back to the picker. On macOS the terminal must send Option as Alt for Portal's keys; see Keys in a session.

Shell integration

portal init prints the shell functions. Add one line to your shell profile:

# zsh
eval "$(portal init zsh)"

# bash
eval "$(portal init bash)"

# fish
portal init fish | source

This defines x, which launches Portal (the picker, or opening a target), and xctl, which runs Portal's subcommands (list, kill, alias and the rest). Name them something else with --cmd:

eval "$(portal init zsh --cmd p)"   # creates p() and pctl()

How it works

Portal runs zmx attach itself and stays running while you're attached, watching for its own keys. A daemon in a hidden _portal-saver session saves what changed in your sessions, and after a reboot the first command that needs them brings the saver back and rebuilds every saved session that isn't already live. See How it works for the whole of it.

Commands

The examples use the default x / xctl names; with --cmd p, use p and pctl. You can also call the portal binary directly.

Command What it does
x Opens the picker, or opens a session, a path, an alias or a zoxide match; several at once open several windows
xctl list Lists running sessions
xctl kill Kills a session for good
xctl rename Sets the current session's label
xctl current Prints the current session's label
xctl alias Sets, removes and lists path aliases
xctl hook Registers, removes and lists resume hooks
xctl doctor Reports Portal's health; --fix makes the low-stakes repairs
xctl version Prints Portal's version
xctl theme export Prints a theme's file, to start your own from
portal init Prints the shell integration
portal uninstall Stops Portal's save daemon, leaving your sessions and config

Every command and flag is in Commands.

Documentation

  • The picker: its keys, filtering, the Projects page, grouping and tags, the scrollback preview, and multi-select
  • Sessions: opening a session, the search form, aliases and zoxide, keys in a session, and one terminal at a time
  • Resume hooks: bringing commands back after a reboot, and the resume panel
  • How it works: zmx and its directory, the saver, and restoration after a reboot
  • Commands: every command and flag
  • Configuration: the config files and their paths, prefs.json, the attach keys, logging and privacy
  • Themes: the colour roles, the .theme format, and the light/dark pair
  • Custom terminals: terminals.json recipes for opening windows on terminals other than Ghostty
  • Troubleshooting: doctor, doctor --fix, and the logs

The design is how Portal is built on zmx and why.

Coming from the tmux version

Coming from the tmux version? This version is incompatible with its saved state: ask your agent to migrate it.

Contributing

CLAUDE.md has the house rules: how to build and test, and the invariants the code keeps.

go build -o portal .                                 # build
go test ./...                                        # unit lane
go test -tags integration -p 1 -timeout 30m ./...    # integration lane: real zmx and built binaries
golangci-lint run                                    # lint
  • Tests never touch the real system: not your files outside their temp directories, your zmx sessions, or any process they didn't start. CLAUDE.md says how each boundary is held.
  • The pictures here are recorded from the picker with every seam faked, never the real binary. demo/README.md says how to record them again.

License

MIT

About

Interactive zmx session manager - Go CLI that gives you fast, fuzzy session management from bare shell, with project memory, path aliases, reboot-safe restoration, and a keyboard-driven TUI.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages