# codex-agent system dependencies
#
# This file lists non-Python/runtime dependencies used by codex-agent features.
# Python package dependencies remain declared in pyproject.toml.
#
# Primary supported Linux desktop automation target: Debian/Ubuntu on X11.
# Wayland support is intentionally limited by compositor security restrictions.

[core]
- python3
  Purpose: run the package when installed outside a virtual environment.
- python3-pip
  Purpose: install Python package dependencies when needed.
- bash
  Purpose: shell used by TUI terminal launch helpers and local shell tools.
- xdg-utils
  Provides: xdg-open
  Purpose: builtin show/open helpers on Linux.

[browser]
- Playwright managed Chromium
  Install command: python -m playwright install chromium
  Recommended Linux command when system libraries are missing: python -m playwright install --with-deps chromium
  Purpose: rendered web extraction, browser tools, screenshots, DOM snapshots, click/fill/select/press navigation.
  Notes: Chromium itself is managed by Playwright, not by apt. The --with-deps flag may install many distribution packages.

[desktop-linux-x11]
- wmctrl
  Provides: wmctrl
  Purpose: window listing, activation, close, move and resize on Linux/X11.
- xdotool
  Provides: xdotool
  Purpose: keyboard, mouse, window activation/minimize/close/move/resize fallback on Linux/X11.
- xclip
  Provides: xclip
  Purpose: clipboard write backend for desktop copy/paste helpers on Linux/X11.
- libx11-6, libxext6, libxinerama1, libxrandr2, libxtst6
  Purpose: common X11 runtime libraries used by desktop automation/screenshot backends.

[screenshots]
- python package mss, already declared in pyproject.toml
  Purpose: full-screen and window screenshots.
  System note: requires an accessible graphical display; X11 is the reliable target.

[tray-linux]
- python3-gi
  Provides: gi Python bindings from the system package path.
  Purpose: GTK tray controller.
- gir1.2-gtk-3.0
  Purpose: GTK 3 introspection bindings.
- gir1.2-ayatanaappindicator3-0.1
  Purpose: preferred AppIndicator introspection bindings for the tray icon.
- gir1.2-appindicator3-0.1
  Purpose: legacy AppIndicator fallback where available.
- libayatana-appindicator3-1
  Purpose: Ayatana AppIndicator runtime library.
- dbus-user-session
  Purpose: session D-Bus used by GTK/AppIndicator/status notifier integration.

[service-linux]
- systemd user session
  Provides: systemctl --user
  Purpose: codex-agent install-service/uninstall-service for server and tray user services.
  Notes: usually already present on modern desktop Linux distributions.

[tui-terminal-linux]
At least one terminal emulator supported by codex_agent.tui.open_tui_terminal:
- $TERMINAL environment variable, or
- x-terminal-emulator, gnome-terminal, konsole, xfce4-terminal, alacritty, or kitty
Purpose: open_tui/tray Open TUI action.
Notes: the installer does not force-install a terminal emulator to avoid pulling a large desktop stack.

[audio-voice]
- ffmpeg
  Provides: ffplay and codec support used by pydub fallback playback/MP3 decoding.
  Purpose: voice/TTS playback fallback.
  Notes: Python backends simpleaudio or pyaudio may also work if installed separately; ffplay is the system fallback referenced by code.

[macos-notes]
- Playwright managed Chromium: python -m playwright install chromium
- launchctl is used for user services and is part of macOS.
- open/osascript/Terminal are part of standard macOS desktop installations.
- GTK tray support is currently Linux-oriented.

[windows-notes]
- Playwright managed Chromium: python -m playwright install chromium
- wt.exe, PowerShell, or cmd are used to open the TUI when available.
- Windows service installation is not currently implemented by codex_agent.service.
