psh — Personal Shell

A Node.js/TypeScript interactive shell with a multi-panel TUI.

Features

• Multi-panel TUI: tab bar + toggleable file browser sidebar
• Pipes and I/O redirection (|, >, >>, <)
• Built-in commands: cd, pwd, ls, cp, mv, rm, mkdir, rmdir, echo, cat, which, env, export, history, clear, exit, serve, view
  • view <file> — syntax-highlighted pager that stays inside the TUI (no PTY handoff). Supports less-style navigation: arrow keys / j / k to scroll a line, PageUp / PageDown / Space / b to scroll a page, g / G to jump to the top / bottom, /pattern + Enter to search forward, n to repeat the search, q to quit. Binary files open with the system viewer. Highlighted languages: JS/TS, Python, Shell, Rust, Go, JSON, YAML, TOML, HTML, CSS, Markdown
  • serve [--port=N] <path> — static HTTP server; serve --list / serve --stop <port> to manage running servers
• Interactive programs (nano, vim, less, top, etc.) work correctly via PTY
• Command history with two levels:
  • Global history persisted to ~/.psh_history (up to 10,000 entries)
  • Per-directory history persisted to ~/.psh_dir_history/ (up to 5,000 entries per directory)
  • Up arrow shows current-directory commands first, then falls back to global history
  • history --dir / history -d lists only the current directory's history
• Tab completion for files, directories, and commands
  • Single Tab fills the longest common prefix
  • Double Tab opens a vertical completion menu, aligned to the token being completed, overlaid on the output pane
  • Tab / Down / Ctrl+N cycle forward; Up / Ctrl+P cycle backward; selection is applied to the buffer immediately
  • Enter accepts the current selection; any other non-Tab key accepts and continues editing
  • Paths with spaces are automatically escaped (e.g. My\ Documents/)
  • Completing a directory name then pressing Tab lists its contents

Running

npm install
npm run dev

Key Bindings

| Key | Action | |-----|--------| | Enter | Submit command | | Up / Ctrl+P | Previous history entry | | Down / Ctrl+N | Next history entry | | Ctrl+C | Cancel current input | | Ctrl+D | Exit shell (on empty line) | | Ctrl+A / Ctrl+E | Start / end of line | | Ctrl+K | Kill to end of line | | Ctrl+U | Kill entire line | | Ctrl+W | Kill word before cursor (close tab when line is empty) | | Tab | Fill longest common prefix; double-Tab opens completion menu | | Tab / Down / Ctrl+N | (in menu) Cycle forward | | Up / Ctrl+P | (in menu) Cycle backward | | Enter | (in menu) Accept selection without submitting | | Ctrl+T | New tab | | Alt+B / Alt+F | Cycle to previous / next tab | | F2 | Toggle file browser sidebar | | PageUp / PageDown | Scroll output |

Building

npm run build
node dist/psh.cjs

Installing globally

Published as @joshmarinacci/psh on npm. To install on any machine:

npm install -g --allow-scripts=node-pty @joshmarinacci/psh
psh

node-pty requires native compilation, so --allow-scripts=node-pty is needed. To avoid typing it every time:

npm config set allow-scripts=node-pty --location=user
npm install -g @joshmarinacci/psh

Publishing a new version

npm version patch   # or minor/major
npm run build
npm publish --access public

Publishing requires 2FA — npm will print a URL to open in your browser to approve the OTP.

Requirements

• Node.js 20+
• macOS or Linux

Future Features

[x] list completions for a subdir in a vertical list overlay [x] use arrow keys and enter when completion list is open [x] a way to cycle between my tabs — Alt+Left / Alt+Right [x] Please add a built-in 'help' command that lists the keyboard shortcuts available. [x] enable running interactive visual programs like nano from within the shell. [x] view command should do paging. [ ] view command should not delegate to the system open command unless it's an approved mimetype. currently only include some standard image mimetypes. [x] add the dir command is an alias for the same behavior as ls -la [x] show the current branch when user is inside of a git repo in a bottom footer [x] always show the cwd and branch if inside main, and time [x] per directory history [ ] Add a built in fetch command for http similar to curl [ ] Fetch then pipe into more or jq [ ] Built in ability to see results as different things

Bugs

[x] opening a file with _ or ( causes the shell to think it is multiple files [x] version number is wrong [x] can't select text in iterm [ ] can't switch tabs in iterm