sess

dtach sessions with overlay isolation

Linux OverlayFS macOS APFS clones SSH remote sessions 1 file ~1100 LOC bash

$ npx @deepaksilaych/sess

terminal

# create a session — you're in, working
$ sess new feature-auth
Session 'feature-auth' created. Attaching...
feature-auth | none | main | ~/project     14:30

# ...work in session... Ctrl+\ to detach

# reattach later
$ sess feature-auth

# close laptop. open laptop. all sessions still alive on the VM.
$ sess up
Reconnecting to 1 session(s)...

# create an isolated overlay (only deltas stored)
$ sess overlay new feature-auth bugfix-1222 main
Overlay 'bugfix-1222' created and mounted.

# writing to the overlay does NOT touch the original repo
$ sess diff feature-auth
+overlay change

# open Cursor on laptop, connected to VM session
$ sess code feature-auth

🔌

dtach persistence

Single Unix socket per session. No server process. Ctrl+\ to detach, sess <name> to reattach. Survives SSH drops.

🗂️

Overlay isolation

N independent writable views of the same repo. Only deltas stored. Writing to one overlay never touches another or the base.

📡

Remote sessions

Sessions live on the VM. Your laptop is just a terminal. sess ssh connects, sess up reconnects all on wake.

📋

Connection log

Tracks how each session ended: detach (Ctrl+\), exit (typed exit), or drop (SSH timeout/laptop sleep).

🖥️

Editor integration

sess code <name> opens Cursor/VS Code via Remote-SSH. No manual config needed.

📊

Status bar

PROMPT_COMMAND renders session | overlay | branch | path. Plain text, no colors, no multiplexer needed.

Remote workflow

macOS laptop → Linux VM

# one-time: point sess at your VM
$ sess remote add default user@dev-vm

# daily workflow
$ sess new feature-auth       # SSH to VM, create, attach
$ sess feature-auth           # reattach
$ sess code feature-auth      # open Cursor on laptop
$ sess ssh                    # plain SSH to VM

# close laptop. open laptop.
$ sess up                     # reconnects everything

# how did my last session end?
$ sess connections feature-auth
2026-07-09T14:30:00  detach (Ctrl+\)
2026-07-09T15:12:00  drop (exit code 141)
2026-07-09T16:45:00  exit

All commands

sess new <name> [branch] Create session + auto-attach sess <name> Attach to existing session (Ctrl+\ to detach) sess ls List sessions sess rm <name> Remove session (unmounts overlays) sess overlay new <s> <ov> [br] Create overlay from latest default branch sess overlay switch <s> <ov> Switch active overlay sess overlay ls <s> List overlays sess overlay rm <s> <ov> Remove overlay sess diff <name> [path] Git diff in overlay sess log <name> [N] Activity log sess connections <name> [N] Connection log (detach/exit/drop) sess path <name> Print overlay/cwd path (for scripts) sess code <name> Open Cursor/VS Code for session sess ssh [args] SSH to configured remote VM sess up Reconnect to previously active sessions sess remote add [name] <host> Configure a remote VM sess remote ls List remotes sess remote rm [name] Remove a remote sess status [name] Session info or overall status sess doctor Check prerequisites

Platform support

Feature	macOS	Linux
dtach sessions	✓	✓
Status bar	✓	✓
Connection log	✓	✓
Remote (SSH to VM)	✓	✓
Auto-reconnect on wake	✓ SleepWatcher	✓ systemd
sess code	✓ Cursor/VS Code	✓
Overlay isolation	✓ APFS clone	✓ OverlayFS

Why not…

	sess	git worktree	tmux	Docker
Isolation	per-overlay	branch-level	shared FS	full
Creation	~instant	~1s	N/A	~seconds
Disk/session	delta only	full copy	0	full copy
SSH persist	✓ dtach	✗	✓	manual
Extra process	none	none	server	daemon
Path stability	same path	varies	—	mapping

Architecture

~/.sess/sessions/<name>/

~/.sess/sessions/feature-auth/
├── socket              ← dtach Unix socket
├── hook.sh             ← PROMPT_COMMAND status bar
├── state               ← session metadata
├── log                 ← activity log
├── connections         ← detach/exit/drop log
└── overlays/
    └── bugfix-1222/
        ├── upper/      ← writable layer (deltas only)
        ├── work/       ← kernel work dir
        └── merged/     ← unified mount point

Get started

One file. No dependencies beyond dtach and git.

GitHub → npm →