Documentation / Supported Features

Supported Features

Everything below is real and shipped — not a roadmap. See Project Status for what’s still open.

Window Management (Hyprland)

• Dynamic tiling with directional focus (Super+arrows), floating (Super+V), pseudo-tiling (Super+P), fullscreen (Super+Shift+F), pinning (Super+Ctrl+F), and grouping (Super+G).
• 10 workspaces, switch/move with Super+0-9 / Super+Shift+0-9, scroll to cycle, jump-to-empty.
• Special (scratchpad) workspace cycling.
• Move/resize via Super+drag.
• Alt+Tab switcher — an overlay that snapshots every window once and commits when you release Alt. Tab/Shift+Tab step through windows, the arrow keys move between workspaces (left/right) and windows (up/down), the home-row keys A S D F G H J K L ; pick workspace 1–10, 1–9 pick a window in it, Enter/Space commit, Esc cancels.

Full reference: Keybindings.

The Quickshell Shell

A single hand-vendored Quickshell shell — not an installed dependency, the QML is checked into the repo — replaces Waybar, Mako, and Rofi, and brings its own lock screen.

Signal line (Settings → Bar, as the Full style’s skin) is a shell-wide look added in 2.0.7: a flat bar with an accent baseline, and glass panels, hairline borders and reworked layouts across every surface below. See Bar Styles.

Bar (five swappable styles)

• Capsule — a single self-sizing floating pill of modular pieces (workspaces, clock, status icons, an optional media chip) instead of an edge-spanning strip. The default on a fresh install.
• Full — the original bar, dockable to any edge, with a Pill, Square or Signal line skin, real hover popouts on every status icon.
• Dock — a floating macOS-inspired app dock with pinned + running apps and hover-scale magnification.
• Taskbar — a Windows-style grouped task list with a start button.
• Minimal — an Omarchy-style single-accent-color icon strip.

Switch live from Settings → Bar (with real live-scaled previews), aphotic bar style <full|dock|taskbar|minimal|capsule>, or cycle with Super+Ctrl+Shift+B. See Bar Styles for the full per-style option reference.

Bar popouts — hover any status icon, the tray, or the active window pill for a real detail panel: volume, Wi-Fi, Bluetooth, VPN, battery/power profile, agent sessions, host info, Pomodoro, window title, keyboard layout, lock state, live resource meter.

The Notch

A collapsed strip that sits against whichever edge the bar is docked to and expands on click. Two tiles ship with the base shell and every install has them:

• Processes — a live, sortable process list (CPU, memory, or per-process GPU VRAM on NVIDIA hardware), fixed-height rows so the notch doesn’t resize as processes come and go.
• Commands — a command palette over your own pinned action slots (Settings → Bar → Command palette), resolved against every action the core shell and your installed plugins currently offer. Empty until you pin something; nothing shows up here that isn’t explicitly added.

Any plugin that declares a [ui.notch_tile] surface — the Agent Notch Tile and Dev Notch Tile plugins, for two — adds its own tile alongside these, with no edit needed here. A switcher strip to move between tiles only appears once there’s more than one.

Workspace host

A plugin-hosted, full-screen plane for workspace-shaped tools — the kind of surface a to-do tracker, a work-graph view, or a run-evidence inspector needs, distinct from a Command Center tab or a notch tile. Super+Shift+W opens it, but the bind only exists at all while an installed plugin actually registers one — with none installed there is nothing to open and no key is bound, so it never shows up in the keybind cheatsheet on a bare install. The Agent Audit plugin (see Agentic Workflows) is the first thing built on this host.

Launcher

One search box (Super+A or Super+Space), mode switched by a prefix character:

Notifications, OSD, Lock, Session

• Notifications — real popup toasts, top-right, with a full history view. Super+N toggles history, Super+Shift+N clears everything.
• OSD — volume/mic/brightness popups on change, configurable enable flags and hide-delay.
• Lock screen — a real ext-session-lock-v1 surface with real PAM auth (Super+L, and idle locking). The session menu’s Lock button still runs swaylock.
• Session/power menu — lock, suspend, log out, hibernate, reboot, shut down (Super+Backspace or Super+M).
• Login screen — the Aphotic greeter, a Quickshell surface running on greetd with your theme’s wallpaper and palette. The installer makes it the login screen (skip with --keep-sddm; Omarchy keeps its own). aphotic greeter resyncs its palette and wallpaper; aphotic displaymanager reports or switches between greetd and sddm.

Command Center (Dashboard)

Super+D opens a tabbed overlay:

• Dashboard — clock, calendar, now-playing media, a Pomodoro card, Wi-Fi/Bluetooth/DND quick toggles, a live weather card.
• Flow — a live map of which workloads (AI, gaming, security, dev, and optionally the shell itself) hold which resources, with contention, workload passports and action receipts. See Resource Engine.
• Performance — live CPU/GPU/memory/storage/network cards.
• Workspaces — a numbered grid, click to jump.
• Wallpapers — cycle/pick within the active theme live, without opening Settings.
• AI Chat — see below.

Plugins can add their own tabs after these.

Settings (Control Center)

Super+I opens a full-screen panel with a searchable category rail, grouped Look / Desktop / Input / Services / System. A plugin’s own settings pane shows up as a collapsed section inside the category it names (or inside Plugins), and the search box finds it by name:

Intelligence

Super+Shift+A opens a right-docked quick-chat popout, distinct from the Command Center’s AI Chat tab — persisted, independently switchable session history that survives a shell restart, its own per-session provider/model.

AI Chat

Both AI Chat (in the Command Center) and Intelligence share the same backend and talk to four built-in providers behind one interface, plus any a chat-provider plugin adds:

• Claude (via the claude CLI), Ollama (local/LAN, no key needed), Gemini, ChatGPT — each shows a clear inline message if unconfigured instead of failing silently.
• Ollama model manager (Settings → AI) — live/idle status, VRAM usage, one-click set-active/delete/pull.
• Inference mode — when a local model host (Ollama, llama-swap, LM Studio) loads a model, the shell turns off Hyprland blur, shadows and animations and pauses the plugins that can be paused, then brings them back 20 seconds after the model unloads. A notification says when it turns on and off. Auto by default; set Off in Settings → AI, or drive it with qs -c aphotic ipc call inference <enter|exit|auto|off|status>.
• Aphotic Assistant (opt-in, NVIDIA only) — a local chatbot with a fixed persona, installed via install.sh --with-assistant. Shows up as a fifth provider once installed.
• Agent module (bar icon) — tracks whichever harnesses (Claude Code, Codex, OpenCode) you’ve installed the matching <harness>-hooks plugin for: left-click for a session/usage panel, right-click launches the harness in a new terminal, middle-click cycles between them. Ollama isn’t a harness and doesn’t appear here.
• Agent Graph tab, Agent Audit, and the Agent Notch Tile — a live, zoomable node graph of a harness session’s tool calls as they happen with a replay transport for finished runs (Agent Graph), a workspace-hosted run inspector over the same run history (Agent Audit), and a notch tile carrying waiting-for-input/phase/token status (Agent Notch Tile). Each needs the ai layer plus its own plugin install — see Agentic Workflows and Plugin System for how the opt-ins work and exactly what’s collected.

Other bar icons

• Host info — click to copy your LAN IP, hover for hostname + IP.
• Pomodoro timer — 25/5 cycle, click to start/pause, auto-engages Do Not Disturb during focus.
• VPN — status for NetworkManager-managed VPN connections. The raw OpenVPN profile in Settings → Network (aphotic vpn) is separate and isn’t shown here.
• Do Not Disturb — Super+Shift+D.

Screen capture

• Super+S — plain grim/slurp/swappy region select.
• Super+Shift+S (and variants) — the real Quickshell picker: drag-select with live client-window snapping and a freeze-mode preview.
• Super+Shift+C — eyedropper, click a pixel to copy its hex color.

Plugin System

Aphotic base is the shell, rice/theming, Settings, and core Quickshell modules — everything else, including all AI capabilities, is an independently installable and removable plugin distributed from a separate aphotic-plugins repo. See Plugin System for the manifest format, the capability model (this release hosts ui-surface, theme-hook, project-hook, workspace-hook, harness-hook, profile, cli, chat-provider, and action), and the current plugin roster.

Theming

Wallpaper-driven color generation via wallust, applied live across Kitty, Quickshell (the entire shell), Cava, Firefox (needs the Pywalfox extension), VS Code (needs the Wal Theme extension), and GTK.

Super+W opens the wallpaper picker over the desktop, in one of three layouts (coverflow, grid, dock) chosen in Settings. Video files work as wallpapers too: Aphotic derives the palette from an extracted frame and shows that still, and the optional Live Wallpapers plugin plays the video over it. See Theming.

aphotic theme list              # 8 built-in themes
aphotic theme set <name>
aphotic theme next / prev       # or Super+./,
aphotic wallpaper --next        # real ordered cycle through the theme's wallpapers
aphotic wallpaper --random      # random pick instead
aphotic wallpaper -f <path>     # a specific file
aphotic theme list --remote     # browse themes available for download
aphotic theme download <name>   # download a community theme

The 8 built-in themes: Gruvbox, Nordic, Rosé Pine, Tokyo Night, Catppuccin Latte, Lofi, HackTheBox, Windows 11. Each ships its own curated wallpaper set, matching Papirus folder-icon accent, and (for Latte) a light-mode variant. See Theming for the full pipeline.

Terminal Games

aphotic play snake    # board sizes to your actual terminal, speeds up with score
aphotic play hangman  # word-guessing, tracks a win/loss record
aphotic play guess    # number guessing, tracks your best (fewest) attempts

All three persist their stats to ~/.local/state/aphotic/game-scores.json.

aphotic CLI

Run aphotic --help for the full, always-current list — commands are auto-discovered, so this list can’t drift silently. Highlights:

• Core: agent, diff, doctor, perf, reload, runtime, shell, status
• Config: bar, config, context, displaymanager, greeter, plugin, scheme, sddm, theme, vpn, wallpaper
• Lifecycle: backup, packages, reconcile, recovery, report, restore, rollback, safemode, sync, update, whatsnew
• AI: ai
• Build: iso
• Fun: play

Profiles & Layers

See Profiles & Layers for the full breakdown. In short: a profile (minimal or full) is the base package set; a layer (gaming, dev, ai, exploit and its sublayers) is an optional add-on merged on top. Custom apps go in profiles/custom_apps.lst.

When two of these layers’ workloads compete for the same GPU (a local model and a game, most commonly), the Resource Engine is what notices and asks which one yields instead of letting one crash.

Installation Safety

• Declarative — package sets are TOML data (profiles/*.toml), not bash arrays.
• Snapshotted — every install.sh run backs up your current configs first (~/.config-backup/, restored automatically by ./uninstall.sh); a separate aphotic backup CLI (~/.local/state/aphotic/backups/) covers manual, on-demand dotfile snapshots — see Installation.
• Dry-run — --dry-run prints the entire plan and touches nothing.
• Reversible — ./uninstall.sh restores your most recent backup.
• No telemetry — nothing here phones home.

Compatibility

• Arch Linux / AUR-based distros only — no other distro is supported or planned.
• Wayland-native throughout; requires Hyprland.
• AUR packages go through yay or paru; the installer builds yay if neither is present.

See Compatibility for the detailed breakdown.

View public Wiki source ↗