Marspot / guide
Organised by what you are trying to do. Everything here is true of the build in this repository; where something is not implemented yet it says so on the front page rather than being left out.
macOS 14 or newer, Apple silicon. There is no signed release yet — the pipeline exists and is rehearsed on every change, but it is waiting on credentials, so for now you build it:
git clone https://github.com/goliajp/marspot cd marspot cargo build --release
Three binaries come out. marspot-shell owns the window, marspot-core draws, and one marspot-session runs per pane and owns that pane's pty. A pane that crashes takes nothing else with it.
A new pane opens in the directory the pane you were in is in — not the one it was launched in, which for anything you have cd'd out of is the wrong answer. A new window starts at your home directory, because it has no pane to inherit from.
Each pane is its own process. That is what makes twenty of them cheap: nothing animates when nothing changes, and an idle pane costs close to nothing.
Everything not listed goes to the program in the pane, unchanged.
| ⌘N | New window |
| ⌘C | Copy the selection |
| ⌘V | Paste |
| ⌘F | Search this pane's scrollback |
| ⌘B | Show or hide the sidebar |
| ⇧⌘C | Agent usage for this account |
| ⌘W | Close the panel that is open |
| Esc | Close the panel that is open; three times in five seconds ends a stuck agent session |
A program that asks for mouse reporting gets it: the wheel, button presses and releases at the cell you clicked, and motion — but only the kind it asked for. A program that wants drag-only is not sent every idle pointer move. Motion is reported once per cell you enter, not once per mouse event.
Holding shift takes the mouse back, so you can always select text over a program that is tracking it.
OSC 52 works, which is the one thing a terminal can do for a remote editor that nothing else can: yank in vim over ssh and it lands on your Mac's clipboard. Reading the clipboard back is refused on purpose — answering that hands any program which can write to the pty whatever you last copied.
The marspot binary talks to a running window, so a script can see and drive panes. A pane is named by its directory's last component, a path tail, or its session id; an ambiguous name is refused and the error lists the candidates.
| --panes | List panes: session id, name, working directory |
| --read | Print what a pane says — its screen, plus scrolled-off lines |
| --send | Type text into a pane and press Enter |
| --autorun | Keep a rotation going by itself |
| --status | Summarise state from the supervisor log and live pids |
| --version | Print version, git and build info |