shellxDownload

How to use ShellX: the complete user guide

Published · ShellPro Team

ShellX is a free terminal app for macOS and Windows with companion apps for iPhone and Android. You run your shells, dev servers and AI coding agents (Claude Code, Codex, OpenCode, Gemini CLI, Pi) in workspaces on your computer, then open those same sessions on your phone to follow them, answer questions and approve requests. Terminal content is end-to-end encrypted between your devices.

This guide walks through the whole app in the order you will need it. Prefer to watch? The 3-minute video tutorial covers the same steps.

On this page: Requirements · Install · Sign in · Workspaces · Split panes · Browser · Command palette · AI agents · Pair your phone · Answer from your phone · Notifications · SSH · Command line · Settings · Shortcuts · FAQ

What do you need to use ShellX?

Device Requirement What it does
Mac macOS 14 or later The full desktop app: terminals, workspaces, built-in browser, AI agent tracking, phone pairing
Windows PC Windows 10 version 1809 or later Desktop terminal with workspaces, tabs and split panes (it does not have every Mac feature yet)
iPhone iOS 15 or later Opens the sessions running on your Mac, push notifications, Needs You
Android phone Android 8.0 or later The same as on iPhone

ShellX is currently free. You need one ShellX account, used on every device, and an Internet connection. You do not need a static IP, an open router port or a VPN: both the computer and the phone dial out to the ShellX relay.

How do I install ShellX?

  1. Open the download section on shellx.pro. It picks the installer for your system.
  2. On a Mac, open the .dmg and drag ShellX into Applications, then start it from Applications.
  3. On Windows, run ShellX-Setup-<version>.exe. The installer is not code-signed yet, so Windows SmartScreen may show “Windows protected your PC”: choose More info, then Run anyway. On Windows 11 with Smart App Control turned on, the unsigned installer is blocked; the download section explains your options and shows the installer’s SHA-256 so you can check the file first.
  4. On your phone, install the ShellX app for iPhone or Android.

ShellX checks for updates itself and tells you when a newer version is available.

How do I create an account and sign in?

Sign in with your email address: ShellX sends you a one-time code, and you type it into the app. Your first sign-in creates the account, so there is no separate sign-up form or password to remember. The phone apps also offer Continue with Google.

Use the same account on your computer and your phone. Pairing (below) then links the two devices.

How do workspaces and the sidebar work?

A workspace is one project: a set of terminals, panes and browser tabs that belong together. Workspaces are listed in the sidebar on the left, under your machine.

  • Create one with the + button or Cmd+N. Give it a name with Cmd+Shift+R.
  • Switch by clicking it, with Cmd+1 to Cmd+9, or with Ctrl+Cmd+] and Ctrl+Cmd+[ for the next and previous one. Cmd+P opens “Go to Workspace” and lets you type a name.
  • Read the sidebar at a glance. Each workspace shows its Git branch, its working folder and the ports a dev server is listening on, so you know what runs where without switching to it.
  • Hide or show the sidebar with Cmd+B.
  • Pick up where you left off. When you quit and reopen ShellX, workspaces, their layout and panes, working folders and terminal scrollback come back, and supported AI agent sessions can be resumed.

How do I split a workspace into panes?

Split a workspace to run several things side by side, for example a dev server, a test watcher and an AI agent.

Action macOS Windows
Split to the right Cmd+D Alt+Shift+=
Split downward Cmd+Shift+D Alt+Shift+-
Move focus between panes Option+Cmd+Arrow keys Alt+Arrow keys
New tab in the current pane Cmd+T Ctrl+Shift+T
Zoom one pane to full size and back Cmd+Shift+Enter —
Close the current tab Cmd+W Ctrl+Shift+W

On Windows the same actions are also buttons in each pane’s tab bar (New terminal, Split right, Split down). On a Mac, drag the divider between panes to resize them.

How do I use the built-in browser?

ShellX for Mac has a browser pane that sits next to your terminal, so you can preview localhost while the dev server runs.

  • Cmd+Shift+L opens a browser.
  • Option+Cmd+D opens a browser in a new pane to the right.

AI agents can drive this browser through the shellx command-line tool: go to a URL, click elements, fill in forms, run JavaScript, and read the page’s DOM, console logs and network requests. An agent can therefore open the page it just built and check that it works.

How do I find any action quickly?

Press Cmd+Shift+P to open the command palette and type what you want: “split”, “rename”, “theme”, “browser”. The app’s actions are listed there, with their shortcuts, so the palette is the fastest way to learn the app.

How do I run Claude Code, Codex or another AI agent?

Start the agent in a ShellX pane exactly as you would in any terminal:

cd ~/projects/my-app
claude        # or: codex, opencode, gemini, pi

ShellX recognizes Claude Code, Codex, OpenCode, Gemini CLI and Pi and follows what each one is doing. Run several side by side, in split panes or separate workspaces, and ShellX shows which agent is working, which is waiting for you and which has finished:

  • a badge on the workspace in the sidebar,
  • a ring around the pane that needs you,
  • a macOS notification when an agent needs input or completes its task,
  • the notification list (Cmd+I); Cmd+Shift+U jumps to the latest unread one.

When an agent asks for permission, the workspace is flagged in the sidebar and your paired phone gets a notification. Approve it on the computer or on the phone, and the agent carries on.

To let an agent use ShellX itself (open a pane for a dev server, wait for a log line, send a notification), install the ready-made skill:

shellx skills install --claude   # or --codex

How do I pair my phone?

Pairing links your phone to your Mac with keys exchanged through a QR code. Only devices you allow can reach your sessions.

On your Mac:

  1. Open Settings (Cmd+,), choose Mobile, and click Show QR Code…. You can also right-click your Mac’s name in the sidebar and choose Pair Phone….

On your phone:

  1. Sign in with the same account as on the Mac.
  2. Open Settings, then Your Macs, and tap +.
  3. Tap Scan QR Code and point the camera at the code on the Mac, or tap Paste pairing code if you copied it.
  4. Check that the Mac’s name is right and tap Pair.

Back on your Mac:

  1. Click Allow for the phone. It now appears under Paired phones.

You can pair several phones, and one phone can follow several Macs.

How do I follow and answer agents from my phone?

Every workspace from every paired Mac shows up on your phone, grouped by Mac, with its Git branch and status.

  • Follow live. Tap a workspace to see the session as it happens. Scroll back to read what happened while you were away.
  • Type into it. A message you type goes straight to the session on your Mac, as if you typed it at the keyboard.
  • Use Needs You. The Needs You page collects every request from your agents in one place:
    • allow a command with one tap,
    • answer a question by picking an option, or by voice,
    • review a plan before any code is written, then approve it, ask for a revision or deny it.

The agent keeps running on your computer, with your repository, credentials and tools. The phone is only the screen and keyboard. If the phone loses its connection, the computer keeps the latest 256 KiB of each session’s output and replays it when the phone reconnects.

How do I get notified when a command finishes?

ShellX turns terminal notifications into desktop notifications and into push notifications on your paired phone. Any program that prints an OSC 9, OSC 777 or OSC 99 notification is covered, and so are the AI agents ShellX recognizes.

From your own scripts, hooks or long builds, call the CLI:

npm test && shellx notify --title "Tests done" --body "All tests passed"

Choose which notifications you get in Settings → Notifications.

How do I work on a remote server over SSH?

You can run ssh in any pane as usual. ShellX also has SSH workspaces, terminals that run on the remote host and reconnect by themselves:

shellx ssh dev@my-host                 # new workspace with an SSH session
shellx ssh-tmux dev@my-host            # attach to the tmux sessions running there

ShellX uses your system ssh command and your SSH agent, so your keys stay on your computer. Nothing has to be installed on the server. SSH panes appear on your phone like any other session. See SSH from your phone for the details.

How do I control ShellX from scripts?

The shellx command-line tool, available in every ShellX terminal, talks to the app through a local socket. A few useful commands:

Command What it does
shellx new-workspace --cwd . --command "npm test" Create a workspace in a folder and run a command in it
shellx list-workspaces List the open workspaces
shellx send "echo hello" Type text into a terminal
shellx read-screen Print what a terminal shows
shellx browser open https://example.com Open a URL in the built-in browser
shellx notify --title "Build done" Send a notification to the desktop and your phone
shellx ssh dev@my-host Open an SSH workspace

Add --help to any command to see its options.

How do I change themes, fonts and shortcuts?

Open Settings with Cmd+, on a Mac or Ctrl+, on Windows.

  • Appearance and Themes: switch between light and dark, and pick a theme, colors and fonts.
  • Keyboard Shortcuts: see every shortcut and rebind any of them.
  • Notifications: choose what notifies you.
  • Mobile: pair a phone and see the phones already paired.
  • Account: see who is signed in, and sign out.

Keyboard shortcuts

These are the defaults. On a Mac you can change any of them in Settings → Keyboard Shortcuts.

Action macOS Windows
New workspace Cmd+N Ctrl+Shift+N
Go to workspace by name Cmd+P —
Workspace 1 to 9 Cmd+1 … Cmd+9 —
Next / previous workspace Ctrl+Cmd+] / Ctrl+Cmd+[ Ctrl+Tab / Ctrl+Shift+Tab
Rename workspace Cmd+Shift+R —
Close workspace Cmd+Shift+W —
New tab Cmd+T Ctrl+Shift+T
Close tab Cmd+W Ctrl+Shift+W
Split right / down Cmd+D / Cmd+Shift+D Alt+Shift+= / Alt+Shift+-
Move focus between panes Option+Cmd+Arrows Alt+Arrows
Command palette Cmd+Shift+P —
Open browser Cmd+Shift+L —
Find Cmd+F —
Notifications / latest unread Cmd+I / Cmd+Shift+U —
Toggle sidebar Cmd+B Ctrl+Shift+B
Settings Cmd+, Ctrl+,
Copy / paste Cmd+C / Cmd+V Ctrl+Shift+C / Ctrl+Shift+V

On Windows, plain Ctrl+C copies only while text is selected; otherwise it interrupts the program, as in Windows Terminal. Right-click pastes, or copies when there is a selection.

FAQ

Is ShellX free? Yes, ShellX is currently free on every platform.

Does my computer have to stay on? Yes. Your sessions run on your computer, so it must be on, awake and running ShellX for your phone to reach them.

Can the ShellX relay read my terminal? No. Terminal content is end-to-end encrypted with the Noise protocol between your paired devices. The relay only forwards encrypted bytes and never stores them. What the server does keep is listed in the privacy policy.

My phone does not show my Mac. What should I check? Make sure both devices are signed in to the same account, that ShellX is running on the Mac, and that the phone appears under Paired phones in Settings → Mobile on the Mac. If it does not, pair again.

Which AI agents work with ShellX? Any command-line agent runs in a ShellX terminal. Claude Code, Codex, OpenCode, Gemini CLI and Pi are also recognized, so ShellX can show their status and collect their requests in Needs You. See AI coding agents on your phone and Claude Code on your phone.

How do I remove ShellX’s shell integration from a Mac? Deleting ShellX.app leaves a small, harmless block in ~/.zshrc, ~/.bashrc and ~/.bash_profile. To remove it, run ~/Library/Application\ Support/ShellX/bin/shellx-term uninstall in Terminal.

Where can I get help? Ask in the community Discord or write to the support address in the site footer.