terminus-shell

Agent-friendly persistent remote shell. SSH exec, durable tmux sessions, cursor-based output reading, and per-server memory — designed for AI agents, usable by humans.

npm install -g terminus-shell
terminus setup            # install the agent skill into Claude Code / Codex

Why

Most shell tools give agents one-shot command execution. Terminus gives them a durable workspace:

• Persistent sessions — a session maps to a remote tmux session; cwd/env survive across calls, disconnects don't destroy state.
• Cursor reads — read --from-cursor returns only new output since last read; long tasks become fire-then-poll.
• Per-server memory — agents store and recall facts about servers (deploy paths, quirks, task state) across conversations.
• Stable --json everywhere; remote exit codes pass through.
• Connection daemon — repeated calls reuse a pooled SSH connection (~0.6s instead of ~2.3s); the daemon exits itself after 5 idle minutes and never leaves processes behind.

Quick start

terminus key add mykey --kind rsa --private-file ~/.ssh/id_rsa
terminus server add prod --host 1.2.3.4 --user ubuntu --key mykey

terminus exec prod -- uname -a                  # one-shot (no tmux needed)
terminus exec prod --script ./deploy.sh         # local script, normalized explicitly when requested
terminus exec prod --detach --cmd './build.sh'  # durable helper-backed request
terminus request inspect <request-id> --json
terminus request tail <request-id> --follow
terminus request cancel <request-id>
terminus exec prod:work -- cd /srv/app          # persistent session
terminus exec prod:work -- docker compose ps    # same cwd as previous call

terminus write prod:work -- "./deploy.sh 2>&1"  # fire and forget
terminus read prod:work --from-cursor --json    # collect new output later

terminus memory add prod --key deploy_dir -- "app lives in /srv/app"
terminus memory ls prod --json                  # recall before acting

terminus audit prod disk --largest 30           # read-only disk inventory
terminus cleanup prod --manifest cleanup.json --dry-run

A human at the keyboard

terminus shell prod          # real TTY login shell: vim, htop, Ctrl-C, resize all work
terminus attach prod:work    # step into the agent's tmux session; survives detach,
                             # reconnects by itself after a network drop
terminus server tmux prod --allow-tmux-install   # no tmux on the host? install the bundled
                                                 # static one — no root, no network needed

Inside either, Ctrl-] then ? lists local commands: detach, force disconnect, push / pull a file.

Agent integration

terminus setup installs the skill for Claude Code and Codex (user-wide). Project-local targets:

terminus setup cursor windsurf agents   # .cursor/rules, .windsurf/rules, AGENTS.md

Platform

Windows x64, Linux x64/arm64 and macOS x64/arm64 (prebuilt, zero dependencies — SQLite and libssh2 are compiled in).

Currently no known-hosts verification and keys are stored unencrypted locally — treat it as a dev tool, not a production credential store, until those land.

License

MIT