Pouch

Simple GNU Screen session manager with a session-first TUI.

Pouch opens as a focused session board first, then falls back to familiar CLI commands when you need scripting. It keeps managed sessions restartable, leaves external Screen sessions visible, and makes the first attach flow obvious.

Why Pouch

• Open pouch and see every session immediately.
• Create the first managed session with one key: n.
• Filter sessions with / and clone a managed session with c.
• Reattach with Enter, then confirm stop and restart before Pouch changes a live session.
• Keep unmanaged Screen sessions visible without taking them over.
• Run pouch doctor when the environment is wrong instead of guessing.

Install

npm (recommended)

npm install -g @kyungyeol.baek/pouch
pouch --version
pouch doctor

The npm package downloads a prebuilt pouch binary from GitHub Releases during install. Supported prebuilt targets:

• macOS Apple Silicon
• macOS Intel
• Linux x64

If the release download is unavailable or your platform is not listed above, build Pouch from source with Cargo instead.

If doctor reports that Screen is missing, install GNU Screen first and rerun it.

Requirements

• macOS or Linux
• GNU Screen installed and available in PATH
• Node.js 18+ for npm installation

From Source

rustup toolchain install 1.93.0
cargo build --release
./target/release/pouch doctor

Current dependencies need rustc 1.88+. This repository pins stable 1.93.0 through rust-toolchain.toml, so cargo will automatically use it after rustup is installed.

60-Second Quick Start

# 1. Check the environment
pouch doctor

# 2. Start the TUI
pouch

Inside the TUI:

• Press n to create your first managed session
• Leave Command empty to start your default shell
• Press Enter to start it
• Press Enter again on the selected session to attach
• Read the detach reminder, then use default Ctrl-A d to leave screen
• Press / to filter by session name or command
• Press c to clone a managed session into a prefilled form
• Press s or r, then confirm with Enter or y
• Press ? or h at any time to open help

Managed vs Unmanaged

Pouch shows two kinds of sessions:

• Managed sessions: created by Pouch, store the original command and working directory, and can be restarted from the TUI or CLI.
• Unmanaged sessions: existing GNU Screen sessions that Pouch did not create. They stay visible and attachable, but restart is disabled.

CLI Examples

# Start a managed session directly
pouch run demo -- sleep 300

# List all sessions
pouch ls

# Attach by managed name
pouch attach demo

# When attached, leave screen without stopping it
# default: Ctrl-A d

# Restart a managed session
pouch restart demo

# Stop a session
pouch stop demo

TUI Keys

↑/↓   Move selection
Enter Attach selected session
/     Filter by name or command
n     New managed session
c     Clone selected managed session
s     Stop selected session after confirmation
r     Restart selected managed session after confirmation
g     Refresh sessions
? / h Toggle help
q     Quit

Troubleshooting

cargo cannot build the project

This project uses Rust 2024 edition and current dependencies require a newer toolchain than older system cargo installs. Use:

rustup toolchain install 1.93.0
cargo +1.93.0 test

screen is missing or broken

Run:

pouch doctor

Pouch will check platform support, the Screen executable, Screen listing, and session metadata health.

It also reports whether screen-256color terminfo is available and whether any managed sessions were started before Pouch's UTF-8 screen profile was introduced.

I only see external sessions

That means Pouch found existing GNU Screen sessions but does not own them. You can still attach, but restart is available only for sessions created through Pouch.

The HUD or glyphs look broken inside screen

Pouch now starts managed sessions with screen -U and prefers screen-256color when terminfo is installed. If you still see broken separators or icons:

pouch doctor

If doctor warns about legacy managed sessions, recreate them with:

pouch restart <name>

For shells or sessions started outside Pouch, add this to ~/.screenrc:

defutf8 on
term screen-256color

Attaching to an already-running legacy session may still look wrong until it is restarted.

I do not remember how to leave screen

Pouch now shows a detach reminder before every interactive attach. The default GNU Screen detach key is:

Ctrl-A d

If you changed Screen's escape prefix, use your custom prefix followed by d instead.

Stop or restart feels safer now

That is intentional. TUI stop and restart actions now open a confirmation prompt so you do not kill or recycle a live session by accident. Confirm with Enter or y, cancel with Esc or n.

Release

Maintainers publish in two steps:

1. Push a vX.Y.Z tag to build binaries, run checks, and create a draft GitHub Release.
2. Configure npm Trusted Publisher for this GitHub repository, review the draft, then run the publish-release GitHub Actions workflow to publish the release and npm package together.

Trusted Publisher requirements for this repo:

• npm package scope stays @kyungyeol.baek/pouch
• npm package settings must trust zpdldhkdl/pouch
• GitHub Actions publish-release uses GitHub OIDC instead of NPM_TOKEN

Support

• Use the help overlay in the TUI with ?
• Run pouch doctor before filing a bug
• Open an issue with the failing command, doctor output, and your OS/toolchain details

Contributing

Small, focused improvements are preferred. UX polish, clearer onboarding, and better diagnostics are especially useful for this MVP stage.