launch-gui

Launch Linux GUI apps from inside any AI agent terminal session.

Works with Hermes Agent, Claude Code, Codex, and OpenClaw.

The Problem

AI agent terminal tools block shell backgrounding (&, nohup, disown, setsid). You can't just run kate file.py & — the tool rejects it or hangs.

The Fix

Use Python's subprocess.Popen with start_new_session=True via the agent's code execution tool:

import subprocess, os
env = os.environ.copy()
env.setdefault("DISPLAY", ":0")
p = subprocess.Popen(
    ["kate", "/path/to/file"],
    env=env,
    stdout=subprocess.DEVNULL,
    stderr=subprocess.DEVNULL,
    start_new_session=True,
)
print(f"Launched PID: {p.pid}")

This fully detaches the child process from the agent's session. The GUI app opens, the agent gets its terminal back immediately.

Installation

Hermes Agent

hermes skill install launch-gui
# or clone this repo into ~/.hermes/skills/launch-gui/

Claude Code / Codex / OpenClaw

Copy SKILL.md into your agent's skill/instruction directory, or just bookmark the technique above — it's a one-liner.

Supported Apps

App	Command	Desktop
Kate	kate file1 file2	KDE
Dolphin	dolphin /path	KDE
Konsole	konsole --workdir /path	KDE
Firefox	firefox URL	Any
VS Code	code /path	Any
Okular	okular file.pdf	KDE
Gwenview	gwenview /path	KDE
gedit	gedit file	GNOME
Nautilus	nautilus /path	GNOME

Works with any app that accepts a command-line launch.

Pitfalls

• DISPLAY must be set — defaults to :0. If the app doesn't appear, check echo $DISPLAY.
• Wayland: also set WAYLAND_DISPLAY and XDG_RUNTIME_DIR.
• SSH: requires X forwarding (ssh -X) or a local session.
• Firefox: if already running, opens a new tab and the subprocess exits immediately — that's normal.
• Hermes: the terminal() tool blocks all backgrounding. Always use execute_code with subprocess.Popen.

License

MIT