Sessions & remote

Sessions

modisa                          # attach the default session (starts it if needed)
modisa new api --cwd ~/code/api  # a named session
modisa -s api                    # attach it
modisa ls                        # running sessions, plus saved ones you can restore
modisa restart                   # load updated modisa into a running session
modisa kill api

Surviving restarts

Layouts, pane names, working directories and agents are saved in ~/.local/state/modisa/modisa.db. After a reboot, attaching restores the session: shells come back in their directories, and agents are relaunched — into the exact conversation they were in when their integration reported it (claude --resume <id>, codex resume <id>, …), otherwise into their latest one. Plain commands are typed back in but not run.

Remote over ssh

modisa --remote ssh://devbox              # host
modisa --remote ssh://me@build-01:2222    # user and port
modisa --remote devbox                    # a Host alias from ~/.ssh/config
modisa -s api --remote ssh://devbox       # a named session on that machine

The TUI runs here with your keybindings, theme, sounds and notifications; the server and every pane run on the far side. No daemon to install and no port to open — modisa shells out to your own ssh, so agent forwarding, jump hosts and ~/.ssh/config all apply.

ssh -T devbox modisa proxy -s default             # what ssh://devbox runs
ssh -T -p 2222 me@build-01 modisa proxy -s api    # …and ssh://me@build-01:2222 with -s api

modisa proxy starts the remote server if it isn't running, then bridges its socket to stdio. -T means no pty: the protocol is JSON, not a terminal.

When the remote can't find modisa

Modisa has to be installed on the remote machine, and on the PATH of a non-interactive ssh shell — which often excludes ~/.local/bin, where the installer puts it. Check with ssh devbox 'command -v modisa'. If it comes back empty, set an absolute path in your local config:

remote_command = "/home/me/.local/bin/modisa"

What runs where

• Panes, agents, integrations and [[plugin]] programs all run on the remote machine. A plugin that raises a desktop notification raises it there.
• Sessions are per machine: modisa ls lists local ones, ssh devbox modisa ls the remote ones.
• Ctrl+B d drops the ssh connection; the remote session and its agents keep running. Reattach from any machine.
• Copying uses OSC 52, so it reaches your local clipboard through ssh in terminals that support it.
• Updates are per machine — modisa update here doesn't touch the remote install.