shell-session

Manages persistent tmux-backed terminal sessions over local pty and SSH transports.

Updated Jul 24, 2026
One-click install
npx skills add https://github.com/gweone/agent-plugins --skill shell-session-gweone
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: shell-session
Source: https://github.com/gweone/agent-plugins/tree/main/plugin/sharpps-work/skills/shell-session
Command: npx skills add https://github.com/gweone/agent-plugins --skill shell-session-gweone

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? One-shot shell commands lose all state between calls, making interactive wizards, remote SSH work, and long-running terminal tasks impossible to sustain. This Skill governs the shell_session_* tool family so terminal sessions stay alive, resumable, and safe to share across conversations. ## Core Features & Use Cases - Persistent sessions: Start tmux-backed local pty or SSH sessions (including multi-hop jump hosts via via) that survive tool-call boundaries and server restarts. - Safe lifecycle rules: Enforces user confirmation before starting, explicit workspace/host parameters, state checks before resuming, and cleanup with shell_session_stop. - Context handoff notes: Write and read compact per-session notes so any later caller can pick up a task mid-flight. - Use Case: A user asks to resume a remote claude --resume session over SSH. The Skill checks shell_session_list, reads context notes and the current screen, then drives the existing session instead of opening a duplicate. ## Quick Start Start a persistent shell session in my project directory and keep it alive so I can resume it later.

Frequently Asked Questions about shell-session

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep a terminal session alive across multiple tool calls?

Use shell_session_start to create a tmux-backed persistent session, then drive it with shell_session_write and shell_session_read. Unlike shell_execute, the session keeps running until explicitly stopped with shell_session_stop.

How do I resume a shell session from an earlier conversation?

Call shell_session_list to find the session, then check shell_session_read_context and shell_session_screen before writing anything. Sessions are ownerless, so any caller with the session_id can resume them safely after inspecting state.

Can I open an SSH session through jump hosts?

Yes, pass a `via` list of hop objects to shell_session_start, each with its own mode, host, port, and auth method. The hops connect in order and the top-level host is the final target reached through the tunnel.

Does shell_session support password-based SSH authentication?

No, password authentication is not supported. Use auth_method "none" for the default identity or agent, or "private_key" with an identity_path pointing to an existing key file, optionally with a passphrase.

When should I use shell_execute instead of a shell session?

Use shell_execute for one-off, stateless commands that need no continuity. Reserve shell sessions for interactive TUIs, multi-step tasks, or work that must stay alive and resumable, since sessions leave a detached process running on the host.

Why is shell_session_screen preferred over shell_session_read for TUIs?

Full-screen TUIs like vim, htop, or a live claude session emit raw escape codes that make line-oriented output unreadable. shell_session_screen renders the resolved current pane instead, though it is the most expensive call in the family.