APHOTIC

Documentation / Getting Started

Getting Started

This guide gets you from a fresh clone to a working, themed Hyprland desktop, then points you at what’s worth trying first.

Prerequisites

  1. Arch Linux or a derivative — Aphotic assumes Arch/AUR throughout the installer; no other distro is supported.
  2. sudo access and an internet connection — for package installation.

You don’t need Hyprland or an AUR helper first: the installer installs Hyprland, and builds yay if neither yay nor paru is present.

Installation

1. Clone the Repository

git clone https://github.com/T-Crypt/Aphotic-Hypr && cd Aphotic-Hypr
chmod +x install.sh

2. Run the Installer

./install.sh

On a terminal with no options, this starts the guided setup: four short steps (how much software, optional tool sets, the theme, optional add-ons), then one summary to accept before anything changes. It installs the newest release, not whatever branch you cloned. Without a terminal (CI, a piped install) it installs the daily-driver setup (full profile, no optional layers) with zero prompts. Either way the choice is written to aphotic.toml.

Just the layer picker, without the rest of the guided setup:

./install.sh --opt-in

Or skip straight to a specific setup without any prompts at all:

./install.sh --profile full --with gaming,dev --dry-run   # preview first
./install.sh --profile full --with gaming,dev             # then actually install

Full flag reference is on the Installation page — including how to select an exploit layer non-interactively, which needs an extra disclaimer flag.

3. Configuration

Aphotic writes your resolved choices to aphotic.toml at the repo root. Every future ./install.sh or aphotic update re-resolves against that file instead of re-asking any questions.

Understanding Your Setup

Profiles

Profile What you get
minimal Hyprland, Quickshell, Kitty, awww, wallust, the Aphotic greeter (greetd), plus every program the always-loaded shell runs (grim/slurp/swappy, brightnessctl, pamixer, NetworkManager, Blueman, fonts and icon themes) — the whole desktop with no extra apps.
full Everything in minimal, plus apps and tooling: Firefox, Thunar, VS Code, mpv, btop, ZSH with Oh My Zsh and Powerlevel10k, Starship, Bluetooth tools, Pywalfox, and sddm as the fallback login screen.

Layers

Layer Adds
gaming GameMode, MangoHud, Steam (enables the multilib repo)
dev Neovim, tmux, fzf, ripgrep, fd, lazygit, GitHub CLI
ai Ollama (with the GPU runner for your card), llmfit hardware-aware model recommendations, Claude Code
exploit Offensive-security/CTF tooling, split into sublayers — see Security

Layers are additive and dedupe against the base and each other — combine whatever fits.

Custom Apps

Add your own applications to profiles/custom_apps.lst. They’re folded into the resolved package list automatically, no separate prompt.

Key Features to Explore

The Quickshell Shell

Aphotic replaces Waybar, Mako, and Rofi with one hand-vendored Quickshell shell, which also brings its own lock screen:

  • Bar — five swappable styles: Capsule (a single floating modular pill, the default on a fresh install), Full (dockable, with a Pill, Square or Signal line skin), Dock (floating macOS-style app dock), Taskbar (Windows-style grouped task list), Minimal (thin single-accent icon strip). Switch live via Settings → Bar, aphotic bar style <name>, or cycle with Super+Ctrl+Shift+B.
  • Launcher (Super+A) — one search box, mode switched by a prefix: nothing for apps, > clipboard history, : emoji, / window switching, ~ themes and wallpapers, @ jump to a project, ? settings, ! keybinds, = calculator.
  • Notifications — real popup toasts, top-right; Super+N opens the notification center, Super+Shift+N clears them.
  • Lock screen — a real ext-session-lock-v1 surface with real PAM auth, Super+L.
  • Command Center (Super+D) — clock/calendar/media, Pomodoro, weather, Wi-Fi/Bluetooth/DND toggles, Flow (which workloads hold which resources), live performance cards, an AI Chat tab.
  • Settings (Super+I) — a full-screen control center covering appearance, personalization, bar style, displays, AI, power, plugins, and more.
  • Intelligence (Super+Shift+A) — a fast, always-ready AI quick-chat popout with its own persisted session history.

See Supported Features for the full list.

Theming

Colors are generated from your wallpaper and applied across the whole stack live:

aphotic theme list          # see the 8 built-in themes
aphotic theme set <name>    # apply one
aphotic theme next          # cycle forward (Super+.)
aphotic theme prev          # cycle backward (Super+,)
aphotic wallpaper --next    # advance to the next wallpaper within the active theme
aphotic wallpaper --random  # pick a random one instead

See Theming for how the pipeline actually works.

Keybindings

All keybinds live in Configs/hypr/keybinds.lua. A few to start with:

  • Super+A / Super+Space — launcher
  • Super+T / E / C / F — Kitty / Thunar / VS Code / Firefox
  • Super+D — Command Center, Super+I — Settings
  • Super+Q — close window, Super+V — toggle floating
  • Super+L — lock, Super+Backspace — power menu

Full reference: Keybindings.

Terminal Games

aphotic play snake
aphotic play hangman
aphotic play guess

Snake’s board sizes to your actual terminal window and speeds up as your score climbs; all three track a persisted best score/win record.

Updating

cd Aphotic-Hypr
./install.sh

Re-running the installer moves to the newest release, installs any new packages and redeploys your configs, after snapshotting the current ones. aphotic update is lighter and doesn’t refresh everything; see Installation → Updating for what each command covers.

[!WARNING] Upgrading from 1.x to 2.0.0? Agent tracking and Agent Graph are no longer automatic — they are separate, opt-in plugins. After updating, run:

aphotic plugin install claude-hooks     # or codex-hooks / opencode-hooks
aphotic plugin install agent-graph

Without this, the bar’s agent icon and the Agent Graph tab will be absent.

Uninstalling

./uninstall.sh

Restores your most recent backup. Add --purge-packages to also remove what your profile installed (behind its own confirmation).

Next Steps

  1. Read the docs — Installation, Profiles & Layers, Theming, Architecture.
  2. Try different profile/layer combinations — profiles and layers are just TOML, nothing stops you from forking one.
  3. Learn the keybindings — see Keybindings for the complete reference.
  4. Explore Settings (Super+I) — every category is worth a look, especially Personalization and Bar.
  5. Contribute — see Contributing.

Troubleshooting

If something doesn’t work:

  1. Check Troubleshooting for common issues.
  2. Review install.log in the directory you ran install.sh from (normally the repo root).
  3. Run ./install.sh --dry-run to see the plan without changing anything.
  4. Run aphotic doctor for a live dependency/config-drift check.
  5. Open an issue on GitHub.

View public Wiki source ↗