VEShell

VEShell (Very Easy Shell) is a reliable PowerShell terminal with rock-solid mouse and keyboard cut / copy / paste, plus built-in learning tools: the ClaudeWhat explainer and a Verbose run mode that carries out a task and walks you through its critical steps.

It opens a window and spawns a real PowerShell session inside it (via Windows ConPTY). Selection and clipboard are handled by a full terminal emulator (xterm.js), the same engine VS Code's integrated terminal uses, so copy/paste does not depend on conhost's flaky "Quick Edit" mark mode. Copying out to other apps uses the normal OS clipboard.

Launch chain: VEShell window → powershell.exe (-NoExit). You get a live PowerShell prompt in the window and stay there.

Project status

VEShell is an ongoing project, and it's aim is to keep adding quality-of-life utility around the shell without losing CLI efficiency: conveniences that stay out of the way, never a heavier workflow.

As of now there are no plans to broaden VEShell beyond its current setup in the near future. That's a problem for Future Me... and when was the last time Future Me ever did anything for Now Me?

Cut / Copy / Paste

Action	Keyboard	Mouse
Copy	Ctrl+C (when text is selected) or Ctrl+Shift+C	Right-click → Copy
Paste	Ctrl+V or Ctrl+Shift+V	Middle-click, or right-click → Paste
Cut	Ctrl+Shift+X	Right-click → Cut
Select all	Ctrl+Shift+A	Right-click → Select All
Interrupt the running program (^C)	Ctrl+C (when nothing is selected)	n/a

Notes:

• Ctrl+C is smart: if you have a selection it copies; if not, it sends the interrupt signal to the running program. This matches Windows Terminal's behavior.
• Select with the mouse by click-dragging. If the running program's TUI has mouse mode active (so a drag would scroll/interact instead), hold Shift while dragging to force a text selection.
• Cut on terminal output can only copy: scrollback text cannot be removed from the screen, so Cut behaves as Copy there.
• Multiline pastes use bracketed-paste mode, so they land in the prompt as one block instead of executing line-by-line.

ClaudeWhat: explain a selection in context

Highlight any part of what's on screen (a keyword, a command, a line of code) and press Ctrl+Shift+W (or right-click → ClaudeWhat). VEShell pivots to a full-window panel and shows a short, learner-friendly explanation of that selection in the context of your terminal, not a generic definition.

It works by reading the selection plus the surrounding scrollback, so the line that produced a result is included, which is what lets it answer why something is there. Everything stays inside VEShell and the terminal is left alone.

Action	Key
Explain the current selection	Ctrl+Shift+W (or right-click → ClaudeWhat)
Scroll the explanation	Page Up / Page Down (or the buttons)
Go deeper on the same selection	Explain More button
Return to your terminal	Esc (or Return to project)

The explanation is generated fresh from what's on screen each time you ask. The terminal underneath stays untouched while the panel is open, and closing it puts you back exactly where you left off.

Verbose run: watch a task happen, step by step

Press Ctrl+Shift+R (or right-click → Run a task (Verbose)) and describe a task in plain language. VEShell carries it out and surfaces the critical steps one at a time, each with a short explanation, paced by a timer so you can read along instead of watching everything fly past. Use Next to move ahead early, or pause on any step and send it to ClaudeWhat to dig deeper. Steps you have explored are marked and remembered across restarts, so you can see what you have already looked at.

Action	Key
Start a verbose run	Ctrl+Shift+R (or right-click → Run a task (Verbose))
Move to the next step	Next button (or wait for the timer)
Explore the current step	ClaudeWhat this button
Return to your terminal	Esc (or Return to project)

Finding the learning tools

Both learning tools are one keystroke away, and the bar along the bottom of the window rotates a reminder of each shortcut:

• Ctrl+Shift+W explains whatever text you have selected (ClaudeWhat).
• Ctrl+Shift+R starts a Verbose run.

They are also both in the right-click menu, so there is nothing to memorize.

Install

Option A: Installer (recommended; installs to Program Files)

1. Run dist\VEShell-Setup-1.8.0.exe.
2. Accept the UAC prompt (needed to write to C:\Program Files\VEShell).
3. It creates a Desktop shortcut and Start Menu entry, and can launch on finish. Uninstall via Settings → Apps like any program.

Option B: Portable (no admin, run from anywhere)

• Use dist\VEShell-Portable-1.8.0.exe, a single self-contained executable. Put it wherever you like (Desktop, a USB stick, a tools folder) and double-click. To setup a shortcut, right-click it → Send to → Desktop.
• Or use the unpacked folder dist\win-unpacked\ and run VEShell.exe inside it. Copy the whole folder to keep it portable.

Configuration

Drop a config.json next to VEShell.exe to override defaults. Lookup order:

1. The folder you launched the portable exe from (PORTABLE_EXECUTABLE_DIR)
2. The directory of the running exe (installer / win-unpacked builds)
3. %APPDATA%\VEShell\config.json (works for every build, including the single-file portable exe, which otherwise runs from a temp dir)

Example:

{
  "shell": "powershell.exe",
  "shellArgs": ["-NoLogo", "-NoExit", "-Command", "claude"],
  "cwd": "",
  "fontSize": 14
}

• cwd: starting directory (empty = your user profile folder).
• For a plain PowerShell prompt only, set "shellArgs": ["-NoLogo"].
• Appearance (font, theme, copy-on-select) also lives in src/renderer/renderer.js for source builds.

Build from source

cd VEShell
npm install            # also rebuilds node-pty for Electron (postinstall)
npm start              # run in dev
npm run dist           # build installer + portable into dist\

Requires Node.js and the Visual Studio C++ build tools (node-pty is native).

Testing

Four automated suites (all passing, 29 checks):

npm test            # runs all four in sequence
npm run test:chain  # headless: node-pty -> powershell launch chain
npm run test:e2e    # real Electron GUI: copy/paste, keyboard, mouse, edge cases
npm run test:stress # headless: resize storm, output flood, spawn/kill churn, unicode
npm run test:verbose # headless: the Verbose-run callout parser

• test:e2e drives the real renderer and verifies clipboard data actually moves: Ctrl+Shift+C / smart Ctrl+C (copy vs. interrupt) / Ctrl+V / multiline bracketed paste / cut / select-all / unicode copy+paste / 20 KB paste / session restart / window-resize → pty resize.
• test:stress confirms stability: a 200-resize storm, a 30k-line output flood, 25 spawn/kill cycles, a 100k-char line, and unicode round-trips.

Note: node-pty prints a harmless AttachConsole failed line to stderr at session teardown (its console-list helper). It runs in a child process, is bounded by a 5 s timeout, and cannot hang or crash VEShell. You will only ever see it when launching from a terminal, never from the shortcut.

Project layout

VEShell/
├─ src/
│  ├─ main.js              Electron main: app/window/pty lifecycle, wires in
│  │                       the feature modules below
│  ├─ claudewhat.js        ClaudeWhat subsystem (claude -p explain handler)
│  ├─ verbose.js           Verbose-run subsystem (task run + callout stream)
│  ├─ verbose-parse.js     Pure parser for the verbose callout stream
│  ├─ claude-proc.js       Shared claude -p helpers (resolve, sanitize, spawn)
│  ├─ config.js            Config load, defaults, env overrides
│  ├─ preload.js           Secure IPC bridge (clipboard, ClaudeWhat, Verbose, session)
│  ├─ assets/icon.ico      App/window icon
│  └─ renderer/            xterm.js UI + clipboard/keyboard/mouse + ClaudeWhat + Verbose + status bar
├─ build/
│  ├─ icon.ico             Multi-size icon for packaging
│  └─ make-icon.ps1        Regenerates icon.ico from the source .ico
├─ config.json            Runtime defaults (shell / cwd / font)
├─ package.json           Deps + electron-builder config
└─ dist/                  Build output (installer, portable), not source

Changelog

1.8.0

• Added Verbose run: press Ctrl+Shift+R (or right-click → Run a task (Verbose)) to describe a task and watch its critical steps appear one at a time, each with a short explanation, paced by a timer with a Next control. Pause on any step to send it to ClaudeWhat; explored steps are remembered across restarts.
• Added a bottom status bar that rotates reminders of the ClaudeWhat and Verbose run shortcuts.
• Split the main process into focused modules (config, shared claude-proc helpers, claudewhat, verbose) so new features drop in cleanly.
• Added a headless test for the Verbose-run callout parser.

1.5.0

• Added ClaudeWhat: select any text on screen and press Ctrl+Shift+W (or right-click → ClaudeWhat) to get a contextual, learner-friendly explanation of the selection in a full-window panel, with Page Up/Page Down, Explain More, and Return to project. It reads the selection plus the surrounding scrollback and runs entirely inside VEShell.
• Light explanatory comments added throughout the source.

1.0.1

• Fixed double-paste. A real Ctrl+V inserted the clipboard twice: VEShell's own paste handler and the browser's native paste action both fired (xterm has its own paste DOM handler). Returning false from the key handler told xterm to skip the key but did not cancel the native default action. Handled shortcuts (Ctrl+V, Ctrl+Shift+V/C/X/A, smart Ctrl+C copy) now call preventDefault(), so copy/paste fire exactly once. Added e2e regression test 5b asserting the shortcuts are default-prevented (synthetic key events don't trigger the OS-level native paste, so the original suite missed it).

1.0.0

• Initial release: PowerShell terminal wrapper with reliable mouse/keyboard cut/copy/paste, NSIS installer + portable build.

License

VEShell is free software under the GNU General Public License v3.0, see LICENSE. You may use, study, share, and modify it under those terms; derivative works must remain GPL-licensed.

Developed in partnership with Claude Kodemen.