A GNOME Shell extension that makes GNOME feel more natural on touchscreen devices.

Touchshell adds the gestures, affordances, and chrome that GNOME assumes you have a trackpad and keyboard for — single-finger workspace switching, edge swipes for the system surfaces, a touch text-action bar, a Fullscreen Apps mode that opens windows maximized, an auto-hiding top panel, and a thin bottom action bar that stays reachable even over fullscreen apps.

• Supported GNOME versions: 49, 50
• Session: Wayland (Xorg is not supported)
• UUID: touchshell@touchshell.com
• License: GPL-2.0-or-later

• Installation
• Activation modes
• Features
  • Edges
  • Workspaces
  • Overview
  • Windows
  • Touch helpers
• Development
• Contributing
• Acknowledgements
• License

Touchshell uses gestures that only work on a Wayland session. If you're on Xorg, switch sessions from the login screen first.

git clone https://github.com/keithvassallomt/touchshell.git
cd touchshell

# Build the extension zip
./scripts/pack.sh

# Install it for the current user
gnome-extensions install --force dist/touchshell@touchshell.com.shell-extension.zip

# Log out and back in (X11 users: log out; Wayland: log out — see "Reloading" below)
gnome-extensions enable touchshell@touchshell.com

If you're hacking on Touchshell, point GNOME at the repo directly:

ln -s "$(pwd)" ~/.local/share/gnome-shell/extensions/touchshell@touchshell.com

Then compile the gsettings schema in place:

glib-compile-schemas schemas/

Touchshell is an ESM extension, and GNOME's disable → enable cycle does not re-evaluate ESM module bodies. To pick up a code change on Wayland you must log out and log back in (or restart the shell with Alt+F2 → r on Xorg, which Touchshell doesn't support but the principle is the same).

Almost every feature in Touchshell has a three-way activation toggle:

Some features default to Auto (panel auto-hide, fullscreen apps, text-action FAB) and some to Always (most gestures). You can change every default from the preferences window.

Gestures that start at the very edge of the screen and reveal a system surface — Activities, Quick Settings, or Notifications.

Swipe up from the very bottom edge of the screen to open the Activities overview. The animation is 1:1 finger-tracked — pull part-way and let go to cancel.

Options

• Activation — Off / Auto / Always (default: Always).
• Swipe distance — percentage of screen height needed to commit one overview state change. Lower = snappier. This setting is shared with the vertical swipes inside the overview and with the desktop swipe-up. Range 30–100, default 60.

Swipe down from the top-right corner of the screen to open Quick Settings. Works over fullscreen apps too — the panel is unhidden for the duration of the menu so the popover anchors under the indicator instead of the top-left.

Options

• Activation — Off / Auto / Always (default: Always).
• Trigger zone width — percentage of screen width, measured from the right edge, that counts as the trigger zone. Range 5–50, default 33.

Swipe down from the top-center to open the date menu (notifications and calendar).

Options

• Activation — Off / Auto / Always (default: Always).
• Trigger zone width — percentage of screen width, centered horizontally. Range 10–60, default 30.

Single-finger ways to move between workspaces — on the desktop, in the overview, and over fullscreen apps.

Single-finger horizontal swipe on any visible patch of the desktop background switches workspaces with 1:1 tracking. RTL locales flip direction automatically.

Options

• Activation — Off / Auto / Always (default: Always).

Single-finger horizontal swipe over the overview background switches workspaces, tracking the finger 1:1 like the native four-finger touchpad swipe.

Options

• Activation — Off / Auto / Always (default: Always).

A thin horizontal strip pinned to the bottom of the primary monitor. A horizontal swipe inside the strip switches workspaces, even over fullscreen apps where no other workspace-switch path is reachable. Taps pass through to the app underneath.

Options

• Activation — Off / Auto / Always (default: Auto).
• Swipe distance — percentage of screen width needed to commit one workspace switch. Lower = snappier. Range 30–100, default 62.
• Hide the bar for — a per-app exception list. Add desktop file IDs (e.g. org.gnome.Calculator.desktop) or raw WM_CLASS strings. Useful for games, presentations, or anything where an accidental edge swipe would be costly.

Gestures for opening the Activities overview and moving between its states (Windows view ↔ App Grid).

Single-finger upward swipe on the desktop background opens the overview, with the same 1:1 finger-tracked animation as the bottom-edge swipe. Sensitivity follows the Edges-page Swipe distance.

Options

• Activation — Off / Auto / Always (default: Always).

Swipe up over the overview to reveal the app grid; swipe down to return to the windows view (or to the desktop).

Options

• Activation — Off / Auto / Always (default: Always).

Flick a window thumbnail upward in the overview to close that window.

Options

• Activation — Off / Auto / Always (default: Always).

How windows open and how the top panel behaves around them.

Open new windows maximized by default (dialogs, popups, and child windows are excluded). A two-finger downward swipe inside a maximized window restores it — that's the escape hatch. The Quick Settings tile flips between Off and Always; Auto can only be set here.

Options

• Activation — Off / Auto / Always (default: Auto).
• Excluded apps — apps that should open at their default size instead of maximized. Add desktop file IDs or WM_CLASS strings.

Hides the top panel when a window is maximized. Reveals on top-edge proximity, during panel menu interactions, and stays visible while you use the menu.

Options

• Activation — Off / Auto / Always (default: Auto).

Touch-specific affordances that make GNOME usable without a pointer or keyboard.

Two gestures, one toggle:

• Swipe up on a visible notification banner to dismiss it.
• Swipe left on a notification in the date-menu list to dismiss it.

Options

• Activation — Off / Auto / Always (default: Always).

A floating action button that expands into a Cut / Copy / Paste / Select All / Keyboard bar. The action buttons synthesise Ctrl+X, Ctrl+C, Ctrl+V, Ctrl+A to the focused app, so it works wherever those shortcuts work — including GTK4 apps where touch text selection is otherwise unusable. The Keyboard item force-summons the on-screen keyboard.

You can drag the FAB anywhere on the primary monitor; its position is persisted. If you turn off Always show the FAB, you can summon the action bar with a three-finger tap anywhere on the screen instead.

Options

• Activation — Off / Auto / Always (default: Auto).
• Always show the FAB — when on (default), a translucent FAB lives in the corner; when off, only the three-finger tap summons the bar.

extension.js         # entry point — wires the modules under lib/
prefs.js             # AdwPreferencesWindow shell; per-page builders under lib/prefs/
lib/                 # feature modules (one file per gesture / chrome / helper)
lib/prefs/           # per-page UI builders + shared widgets / demo media
schemas/             # gsettings schema XML
assets/icons/        # hicolor symbolic icons
demos/               # webm clips embedded in the README and prefs window
scripts/pack.sh      # build the EGO-ready zip
scripts/lint.sh      # run shexli against the zip

Every change must pass the GNOME extensions static analyser. One-time setup:

python3 -m venv venv
. venv/bin/activate
pip install -U shexli

To lint the exact ZIP that would be submitted to EGO:

./scripts/lint.sh

That script builds dist/touchshell@touchshell.com.shell-extension.zip via gnome-extensions pack and runs shexli against it. Output should end with shexli: clean before you push or open a PR.

After changing schemas/org.gnome.shell.extensions.touchshell.gschema.xml:

glib-compile-schemas schemas/

ESM module bodies are not re-evaluated by gnome-extensions disable && enable. After a code change, log out and log back in to pick it up. (Xorg sessions can do Alt+F2 → r, but Touchshell targets Wayland.)

Contributions are welcome. A few ground rules:

1. Lint clean. ./scripts/lint.sh must report shexli: clean before opening a PR.
2. One feature per PR. Easier to review, easier to revert if something regresses.
3. No new top-level deps. Touchshell stays as a vanilla ESM GNOME extension — no npm, no bundlers, no transpilation.
4. Touch-test it. If you're adding or changing a gesture, test on an actual touchscreen (or a touchscreen-emulator). Trackpad-only testing has historically missed bugs that only surface under real touch event routing.
5. Activation modes for new features. If you add a feature, give it an activation gsetting (off / auto / always) and a Tablet-mode-aware default. Consistency matters.
6. Open an issue first for anything bigger than a small fix — happy to talk through the approach before you spend time on it.

Bug reports should include:

• GNOME Shell version (gnome-shell --version)
• Session type (Wayland — Touchshell does not support Xorg)
• Hardware (touchscreen model / convertible chassis if relevant)
• Steps to reproduce, and what you expected vs. what happened

Like any open-source project, Touchshell stands on the shoulders of giants. Mainly:

• TouchUp — main source of inspiration and the O.G. touch extension for GNOME.
• Disable Unredirect — disables some questionable defaults for how GNOME handles full-screen apps. Simple, but a gem.
• Hide Top Bar — hides the GNOME top bar, done right.

GPL-2.0-or-later. See LICENSE.