Fedora Integration

This guide covers the supported Fedora desktop integration path for the Terminal Agent popup GUI.

What this does

Running task integration:fedora installs the popup GUI for the current user and configures the desktop launcher path around ~/.local/bin/agent-gui.

The integration script performs these steps automatically:

checks that the host is Fedora
installs missing Fyne desktop build dependencies with dnf
builds agent-gui
installs agent-gui to ~/.local/bin/agent-gui
installs a desktop entry in ~/.local/share/applications/terminal-agent-gui.desktop
installs the popup icon in the user icon directory
refreshes the desktop application database when available
validates the desktop entry
detects GNOME or KDE Plasma and prepares the supported shortcut path for that desktop
supports --uninstall to remove the installed user-scoped integration files and shortcut configuration

Run the integration

task integration:fedora

To uninstall the Fedora integration:

bash scripts/integ_fedora.sh --uninstall

The script is user-scoped. It installs the launcher and binary in your home directory.

Resulting behavior

After setup:

agent-gui starts the popup app normally
agent-gui --show reopens the hidden popup in the existing instance
agent-gui --new starts a separate isolated popup instance for local testing
pressing Escape hides the popup
the desktop shortcut is configured to run agent-gui --show
the popup Settings button updates the shared default provider/model used by GUI asks

Fedora GNOME

On GNOME, the integration script configures a custom shortcut for ~/.local/bin/agent-gui --show using gsettings.

Default shortcut:

Ctrl+Shift+Space

If that binding conflicts with your current setup, change it in the GNOME keyboard shortcut settings after the script finishes.

Fedora KDE Plasma

On KDE Plasma, the current verified working path is desktop-entry discovery through Plasma Shortcuts.

After running task integration:fedora, Plasma discovers the installed Terminal Agent Popup launcher in the Shortcuts settings. You can then assign a shortcut to that discovered application entry, and Plasma will launch the popup even when agent-gui is not already running.

Verified setup steps:

Run task integration:fedora.
Open System Settings -> Keyboard -> Shortcuts.
Find Terminal Agent Popup in the applications list.
Select it and add a shortcut such as Ctrl+Shift+Space.
Save the shortcut.

Default shortcut:

Ctrl+Shift+Space

Observed behavior on Fedora Plasma Wayland:

the shortcut can launch the popup even if agent-gui is not already running
the first launch may briefly show a loading cursor while Plasma starts the app
after the app is running, using the same shortcut again reactivates the existing popup instance

Fallback if Plasma does not expose the application entry correctly:

Open System Settings -> Keyboard -> Shortcuts.
Create a custom command shortcut.
Set the command to ~/.local/bin/agent-gui --show.
Bind Ctrl+Shift+Space or another available shortcut.

Files installed

~/.local/bin/agent-gui
~/.local/share/applications/terminal-agent-gui.desktop
~/.local/share/icons/hicolor/256x256/apps/terminal-agent.png

These files are removed again by scripts/integ_fedora.sh --uninstall.

Verification

The script validates the desktop entry and checks that the installed binary is runnable.

You can also verify manually:

~/.local/bin/agent-gui
~/.local/bin/agent-gui --show
~/.local/bin/agent-gui --new
desktop-file-validate ~/.local/share/applications/terminal-agent-gui.desktop

Troubleshooting

If shortcut automation does not complete:

confirm whether you are running GNOME or KDE Plasma
verify that ~/.local/bin is present and readable
run ~/.local/bin/agent-gui --show directly to confirm the popup path works
on KDE Plasma, first try the discovered Terminal Agent Popup application entry in Shortcuts
if that does not work, fall back to a custom command shortcut for ~/.local/bin/agent-gui --show
re-run task integration:fedora after fixing any missing desktop tooling