TerminalFlow

Local terminals, SSH sessions, remote file browsing, and quick editing in one desktop app.

TerminalFlow is an Electron-based terminal and SSH workspace built with React and TypeScript. It is designed for developers and operators who want local shells, saved SSH connections, SFTP browsing, and lightweight file editing in a single interface instead of juggling multiple tools.

Features

• Local terminal tabs powered by xterm.js and node-pty
• Saved SSH servers with password or private-key authentication
• Split the active tab into side-by-side or stacked panes
• Built-in SFTP browser with upload, download, rename, create, delete, and filtering
• Open local or remote text files in the built-in editor with syntax highlighting
• Quick commands, command palette actions, and tab reordering
• Customizable terminal fonts, cursor styles, colors, and startup behavior
• Previous session restore plus settings import/export
• Build targets configured for macOS, Windows, and Linux

Getting Started

Requirements

• Node.js and npm
• OpenSSH client tools available in PATH (ssh and scp)
• macOS, Windows, or Linux

Run in development

npm install
npm run dev

Create a production build

npm run build

Platform-specific packaging commands:

npm run build:mac
npm run build:win
npm run build:linux

Build artifacts are generated in dist/.

macOS install note

If macOS blocks the app when opening it, clear the app's extended attributes before launching:

xattr -cr /Applications/TerminalFlow.app

AppleScript automation

The packaged macOS app registers the terminalflow:// URL scheme. AppleScript can use it to activate TerminalFlow or open a new terminal tab:

-- Bring TerminalFlow to the front.
open location "terminalflow://activate"

-- Open a terminal with the app's default working directory.
open location "terminalflow://new-terminal"

-- URL query values must be percent-encoded.
open location "terminalflow://new-terminal?cwd=%2Ftmp&title=Temporary%20shell"

-- Open a terminal and submit an initial command.
open location "terminalflow://new-terminal?cwd=%2Ftmp&command=pwd%20%26%26%20ls"

Supported new-terminal query parameters are cwd, title, and command. The working directory must already exist. Because command runs in a local shell, only open automation URLs you trust. Build and install the macOS app once before running these scripts so Launch Services can associate the URL scheme with TerminalFlow.

Open TerminalFlow at the current Finder folder

The project includes a Finder helper at scripts/open-terminalflow-here.applescript. It opens a new local tab at the front Finder window's folder, or at the Desktop when Finder has no open windows. In addition to supplying cwd, it submits a safely shell-quoted cd command so shells that change directory during startup still finish in the requested folder.

Build the helper app and its portable ZIP on macOS:

npm run build:finder-helper

The artifacts are written to dist/finder-helper/. The helper uses TerminalFlow's app icon and runs as a background UI element, so it does not appear in the Dock when launched. It uses an ad-hoc signature, so a copy opened on another Mac must be approved once in System Settings → Privacy & Security → Open Anyway. TerminalFlow must already be installed on that Mac. For convenient access, hold Command while dragging the helper app to Finder's toolbar.

Stack

• Electron
• React
• TypeScript
• xterm.js
• ssh2-sftp-client
• CodeMirror

Project Structure

src/main       Electron main process
src/preload    Secure preload bridge
src/renderer   React UI
src/shared     Shared app types and contracts

Contributing

Issues and pull requests are welcome. If you plan to make a larger change, open an issue first so the scope and direction are clear before implementation starts.