---
name: panama-desktop
description: Use when interacting with the desktop on a Panama machine (Hyprland + the Panama Quickshell shell) during any task — opening settings, checking system health, taking screenshots, toggling Do Not Disturb, launching or focusing applications, or diagnosing audio, network, or display questions.
---

# panama-desktop

This machine runs Panama: Hyprland with a shell that replaces GNOME's bar, dock, notifications,
settings, and lock screen. The desktop has a command surface built for exactly what you are about
to do — use it instead of poking at processes and config files.

## Reading the machine

`panama doctor` prints a JSON health snapshot (`schemaVersion` 1): a `summary` with an overall
status and per-check counts, and `checks[]` with `{id, group, title, status, detail, action}`.
Groups: `desktop-foundation`, `input-media`, `integrations`, `panama-tools`. Check ids follow
`group.name` (`desktop.quickshell`, `input.pipewire`, `integration.kdeconnect`,
`panama.updates` — the full list is in any snapshot). Useful forms:

- `panama doctor --summary` — one human line
- `panama doctor check <id>` — a single check, same envelope
- `panama doctor --repair <id>` — run a check's repair; exit code is the verdict

It reports what is actually running, not what was installed — trust it over `ps` archaeology.

## Driving the desktop

`panama-action <verb>` (on PATH via `~/.config/quickshell/scripts/panama-action`) is the stable
boundary for desktop actions. Verbs: `control-center`, `notifications`, `calendar`, `clipboard`,
`overview`, `settings`, `settings-page <id>`, `dock-pin`, `health`, `dnd`, `caffeine`,
`night-light`, `focus-start`, `focus-end`, `capture`, `intelligence`, `screenshot`, `microphone`,
`gallery`, `restart-shell`.

Beneath it sits `qs ipc call <target> <function>` — the shell's full IPC surface, one
`IpcHandler` per target in `config/dot/quickshell/shell.qml` (status verbs are free to call;
anything else changes live state). Prefer `panama-action` when a verb exists.

Other tools that beat raw commands:

- `panama-launch --class '<regex>' -- cmd…` — focus the window if it exists, launch otherwise
- `panama-sudo --reason "why" -- cmd…` — root work; load the `panama-sudo` skill first
- `panama update` — bring the machine current (pull, repairs, unattended stages); asks nothing
- `panama test --safe` — run only contracts classified as hermetic in
  `tests/contracts.manifest`

A plain `panama test` prompts in a terminal before it starts non-hermetic contracts. Automation
must grant each required capability with a repeatable `--allow`, such as
`panama test --allow live-host updates`. Each contract has a 180-second outer timeout by default,
and failures print captured stdout and stderr.

## Settings

Open a page for the user with `panama-action settings-page <id>` (leaf ids like `displays`,
`sound`, `connectivity`; `docs/settings.md` in the repo documents every key and page).

Change values through the Settings window or the shell's IPC — do NOT hand-edit
`~/.config/panama/settings.json` while the shell runs: the shell's writes merge-and-win for any
key it has touched, so your edit silently loses. The file is the user's to read and back up, not
an API.

## Where state lives (read, don't write)

- `~/.config/panama/settings.json` — every setting; also read by the Hyprland Lua config
- `$XDG_STATE_HOME/panama/` — generated idle/lock configs, settings backups, migration markers
- The repo itself is at `~/.local/share/Panama` (or `$PANAMA_PATH`), and `~/.config` entries are
  symlinks into it — a change to either is a change to both

If you find yourself editing files under `~/.config/quickshell` or `~/.config/hypr`, you are
editing the Panama repository on a live desktop — stop and load the `panama` skill first.