scrn-mgr

A GNU screen session manager: CLI first, with a Rich/Textual TUI and an MCP server, so sessions can be driven the same way from a terminal, a human-friendly UI, or an AI assistant. Sessions can live on the local machine or on remote nodes reachable over SSH -- scrn-mgr keeps a small registry at ~/.scrn-mgr/registry.json recording which host (hostname + best-effort IP) each session is on. That registry can itself be shared across a cluster (e.g. a networked $HOME): every operation figures out whether a recorded host is actually this machine and runs screen directly when it is, or over SSH (by hostname, falling back to the recorded IP) when it isn't.

Install

pip install scrn-mgr

Related MCP server: mcp-tmux

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Quick start (Python API)

from scrn_mgr import ScreenSessionManager

manager = ScreenSessionManager()
manager.new_session("work")                       # local
manager.new_session("train", host="user@gpu01")    # remote, over SSH
manager.send_command("work", "python script.py")
output = manager.capture("work")

CLI usage

scrn-mgr new work                       # alias: create
scrn-mgr new train --host user@gpu01    # started on a remote node over SSH
scrn-mgr send work "echo hello"
scrn-mgr send-commands work -c "echo 1" -c "echo 2"
scrn-mgr send-file work script.sh
scrn-mgr capture work
scrn-mgr list --all
scrn-mgr attach work                    # interactive; ssh -t under the hood if remote
scrn-mgr new-or-attach work             # alias: create-or-attach
scrn-mgr kill work
scrn-mgr cleanup work                   # or: scrn-mgr cleanup --all
scrn-mgr tui                            # Textual UI (alias: scrn-mgr-tui)
scrn-mgr serve                          # MCP server (stdio)

MCP server

scrn-mgr serve runs an MCP server over stdio exposing every non-interactive operation: list_sessions, new_session, send_command, send_commands, send_file, capture, cleanup_session, kill_session. Interactive attach is intentionally not exposed over MCP -- it needs to take over a real terminal/PTY for the life of the session, which doesn't fit a single tool call/response. Use the CLI (scrn-mgr attach NAME) or the TUI for that.

Because the MCP server always runs locally next to its client and reaches remote sessions the same way the CLI does (one ssh round trip per call, using the host recorded in the registry), no special transport is needed for SSH-remote sessions -- plain stdio is sufficient.

Example client config:

{
  "mcpServers": {
    "scrn-mgr": {
      "command": "scrn-mgr",
      "args": ["serve"]
    }
  }
}

Configuration

Clusters and shared registries

A session's host is recorded automatically: with no --host, scrn-mgr detects this machine's real hostname ($HOST, then $HOSTNAME, then socket.gethostname()) and its resolved IP, rather than a bare "local" placeholder. This matters when ~/.scrn-mgr lives on shared storage (a networked $HOME across a cluster): every command -- from any node -- can tell whether a session's recorded host is the machine it's currently running on, and:

• If it is (including landing back on the exact node that created it), everything runs screen directly, no SSH involved.

• If it isn't, list/send/capture/kill/cleanup transparently go over SSH to that host (by hostname, falling back to the recorded IP). A session whose host can't currently be reached shows status unknown rather than dead -- it just means the check couldn't be done, not that the session is gone.

• attach needs a real terminal, so it isn't attempted blindly over SSH to a host we can't otherwise confirm is reachable in the same way: if the session isn't on this machine, scrn-mgr attach NAME runs ssh -t <host> screen -r NAME, and if that SSH connection itself fails, it suggests connecting manually (ssh <host>, then scrn-mgr attach NAME there) instead of just erroring out.

Requirements

• Python 3.10+

• The screen binary (brew install screen / apt install screen)

• For remote sessions: SSH access to the target host (via your normal ~/.ssh/config) with screen installed there too

Releasing

Pushing a v* tag runs .github/workflows/release.yml, which builds the sdist/wheel, publishes them to PyPI via Trusted Publishing (no stored secrets), and attaches the build artifacts to a GitHub release.

One-time setup (already done for this repo, kept here for reference): on the PyPI project's "Publishing" settings (or, for the very first release, on https://pypi.org/manage/account/publishing/), add a trusted publisher with:

Cutting a release:

# 1. bump the version in pyproject.toml, e.g. 0.1.0 -> 0.1.1, and commit it
git commit -am "Bump version to 0.1.1"

# 2. tag it (must match pyproject.toml's version, with a v prefix) and push both
git push
git tag v0.1.1
git push origin v0.1.1

The workflow refuses to publish if the tag and pyproject.toml's version disagree.