jterm docs

Overview

jterm is a fast, native terminal for macOS and Windows. It is a real terminal first: a true PTY per pane, GPU text rendering, and full mouse reporting, so vim, htop, tmux, and lazygit behave exactly as they should. On top of that sits a VS Code-style workspace, a file tree, editor, search, and Git, which stays out of the way until you open a folder.

It is built as one codebase: a Rust backend (Tauri) that owns the PTYs, filesystem, and Git, and a React/TypeScript frontend driving xterm.js. The whole app is a few thousand lines, MIT licensed, and meant to be forked.

Install

Download the installer for your OS from the Releases page:

• macOS (Universal, Intel and Apple Silicon): the .dmg. Drag jterm into Applications.
• Windows (x64): the .exe installer, or the .msi.
• Linux (x86_64): the .deb (Debian/Ubuntu), the AppImage (mark executable and run), or the .rpm (Fedora). See Linux notes to build it yourself.

On Debian/Ubuntu, download and install the .deb from a terminal:

curl -LO https://github.com/YosefAshenafi/jterm/releases/download/v0.2.0/jterm_0.2.0_amd64.deb
sudo apt install ./jterm_0.2.0_amd64.deb

Prefer to build it yourself? See Build from source.

First run

On launch you get a single terminal tab with your login shell. From there:

1. Run a command (ls, htop, vim) and use the mouse inside full-screen programs.
2. Press ⌘T for a new tab, or ⌘D to split the current pane.
3. Open the file explorer with ⌘B to scope the workspace to a folder.

The workspace (explorer, search, editor, Git) is optional. It stays hidden until you open it, so jterm starts as a plain, fast terminal.

Tabs & panes

Each tab holds a recursive tree of panes, and every pane is its own live shell. Splitting or switching tabs never kills a running shell: terminals live outside React, keyed by pane id, so layout changes only move their DOM around.

• Tabs: + to add, × to close, click to switch, double-click to rename, ⌘1 to 9 to jump.
• Split: ⌘D left/right, ⌘⇧D top/bottom. Nest as deep as you like; drag the dividers to resize.
• Move a pane: drag it onto another pane's edge, onto a tab, or out into a new tab.
• Maximize: ⌘M zooms the active pane to fill the workspace, and again to restore.
• Cycle focus: ⌘] and ⌘[.

Bottom panel

A VS Code-style drawer of extra terminals, with its own tabs, independent of the main grid. Toggle it with ⌘J; add a terminal to it with ⌘⇧J. It is handy for a long-running process (a dev server, a training run) while you work in the panes above.

File explorer

Toggle the explorer with ⌘B. It is a lazy-loaded tree scoped to the active pane's working directory.

• Double-click a folder to cd the active terminal into it.
• Click a file to open it in the editor.
• Files with Git changes are highlighted by status, so what is modified, added, or untracked reads at a glance.

Search

Open full-text search across the folder with ⌘⇧F. It runs off the UI thread across every core and cancels itself the moment you keep typing, so the window never freezes.

It skips build and vendor directories (node_modules, .git, target, dist), hidden directories, binaries, and files over 2 MB. Results group by file and link straight to the matching line in the editor.

Editor

A column between the tree and the terminal for quick edits without leaving the window.

• Tabbed buffers, with each terminal tab keeping its own set of open files.
• Syntax highlighting and file-type-aware auto-indent.
• A line-number gutter, undo and redo, and save with ⌘S.
• A guard before discarding unsaved changes.

Markdown preview

Open a .md file and a Preview toggle appears in the editor status bar. It renders headings, lists, code, blockquotes, and links. Links open in your browser; the source stays one click away via the same toggle.

Source control

Open the Git panel with ⌘⇧G. It shells out to the git on your PATH, so it inherits your config, credentials, and hooks.

• Branch, ahead/behind counts, and staged vs. unstaged changes.
• Stage, unstage, and discard individual files or everything at once.
• Write a commit message and commit with ⌘↵, then push.
• A non-repo offers Initialize Repository.

Publish to GitHub

For a repo with no remote, Publish to GitHub creates a new public or private repository and pushes the current branch in one step. It uses the GitHub CLI (gh), so make sure gh is installed and signed in (gh auth login). If a remote already exists, the same action just pushes with upstream tracking.

Command palette

• Quick Open (⌘P): fuzzy-find any file in the project and open it.
• Go to Line (⌘G): jump to a line in the active file.
• Find in file (⌘F): step through matches in the open file.

Keyboard shortcuts

Everything is also reachable with the mouse. macOS bindings are shown; on Windows/Linux substitute Ctrl+Shift for ⌘.

Tabs & panes

Workspace & panels

Editor

Clipboard

Settings

Open Settings from the gear in the top-right. Changes apply live and persist to localStorage.

• Accent color, which also tints the terminal cursor so it tracks the UI.
• Font family and font size (terminal and editor).
• Line height, cursor style (block, bar, underline), and cursor blink.
• Scrollback: lines kept per terminal.

Build from source

You will need:

• Node.js 20+ and pnpm
• Rust (stable)
• A platform toolchain: Xcode Command Line Tools on macOS, MSVC Build Tools + WebView2 on Windows, or the GTK/WebKit packages on Linux (listed below)

Then build the native installer:

git clone https://github.com/YosefAshenafi/jterm
cd jterm
pnpm install
pnpm tauri build

For development with hot reload, and to run the tests:

pnpm tauri dev                                    # app window + Vite, hot reload
pnpm test:run                                     # frontend unit tests (Vitest)
cargo test --manifest-path src-tauri/Cargo.toml   # Rust unit tests

Tauri does not cross-compile, so build each OS on that OS. See CONTRIBUTING.md for the project layout and the invariants to respect.

Linux (Ubuntu / Debian)

jterm builds on Linux through Tauri. On Ubuntu 22.04+ or Debian, install the GTK and WebKit build dependencies first:

sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf

Then build and install the generated Debian package:

pnpm install
pnpm tauri build
sudo apt install ./src-tauri/target/release/bundle/deb/jterm_*.deb

The build also produces an AppImage in src-tauri/target/release/bundle/appimage/ that runs without installing, plus a .rpm for Fedora-family distros (install their equivalent WebKitGTK packages first).

Architecture

The one decision worth internalizing: terminals live outside React, in a plain manager keyed by pane id. React components only attach and detach the terminal's DOM element. That is why splitting a pane or switching tabs never disturbs a running shell or its scrollback.

The Rust backend exposes a fixed set of commands over Tauri's IPC (PTY, file I/O, search, Git) and nothing else. There is no network listener; both halves run on your machine in one process tree.

For the full data flow, the command surface, and the invariants to keep when extending it, read docs/ARCHITECTURE.md.

Troubleshooting

macOS says the app is damaged or from an unidentified developer

The build is not notarized yet. Right-click the app in Applications and choose Open, then confirm. You only need to do this once.

Windows SmartScreen blocks the installer

Choose More info, then Run anyway. The installer is not signed yet.

Publish to GitHub does nothing or errors

It needs the GitHub CLI installed and authenticated. Run gh auth login in any terminal, then try again.

My layout did not survive a restart

Tab and split layout are not persisted across restarts yet. Session restore is on the roadmap.

Still stuck? Open an issue on GitHub.