docs: add optional system dependencies section (#897)

TimeToBuildBob · web-flow · commit 2718cb369eec · 2025-12-01T13:15:30.000+01:00
* docs: add optional system dependencies section Documents non-Python dependencies that enable specific gptme features: - playwright: browser automation - lynx: text-based web browsing - tmux: long-running commands - gh: GitHub CLI integration - wl-clipboard: Wayland clipboard support - pdftotext: PDF text extraction Fixes #246 * docs: move optional dependencies to separate page Per review feedback, keep getting-started guide short by moving the detailed system dependencies table to a dedicated page and linking to it. - Create docs/system-dependencies.rst with full details - Simplify getting-started.rst with just a tip/link - Add system-dependencies to User Guide toctree
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -26,6 +26,11 @@ If ``uv`` is not installed, you can install it using pip, pipx, or your system p
 
    Windows is not directly supported, but you can run gptme using WSL or Docker.
 
+.. tip::
+
+   Some gptme tools require additional system dependencies (playwright, tmux, gh, etc.).
+   See :doc:`system-dependencies` for details.
+
 Usage
 -----
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -26,6 +26,7 @@ See the `README <https://github.com/gptme/gptme/blob/master/README.md>`_ file fo
    :caption: User Guide
 
    getting-started
+   system-dependencies
    usage
    concepts
    examples
diff --git a/docs/system-dependencies.rst b/docs/system-dependencies.rst
@@ -0,0 +1,66 @@
+System Dependencies
+===================
+
+Some gptme features require additional non-Python dependencies. These are optional and only needed for specific tools.
+
+Optional Dependencies
+---------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Dependency
+     - Purpose
+     - Installation
+   * - ``playwright``
+     - Browser automation for the browser tool
+     - ``pipx inject gptme playwright && playwright install``
+   * - ``lynx``
+     - Text-based web browser (alternative to playwright)
+     - ``apt install lynx`` (Debian/Ubuntu) or ``brew install lynx`` (macOS)
+   * - ``tmux``
+     - Terminal multiplexer for long-running commands
+     - ``apt install tmux`` (Debian/Ubuntu) or ``brew install tmux`` (macOS)
+   * - ``gh``
+     - GitHub CLI for the gh tool
+     - See `GitHub CLI installation <https://cli.github.com/>`_
+   * - ``wl-clipboard``
+     - Wayland clipboard support
+     - ``apt install wl-clipboard`` (Debian/Ubuntu)
+   * - ``pdftotext``
+     - PDF text extraction
+     - ``apt install poppler-utils`` (Debian/Ubuntu) or ``brew install poppler`` (macOS)
+
+Details
+-------
+
+playwright
+~~~~~~~~~~
+
+The ``playwright`` library enables browser automation capabilities. After installing with ``pipx inject gptme playwright``, run ``playwright install`` to download the required browser binaries.
+
+lynx
+~~~~
+
+An alternative to playwright for web browsing. Uses less resources and works in text mode, but has limited JavaScript support.
+
+tmux
+~~~~
+
+Required for the tmux tool which enables running long-running or interactive commands in persistent terminal sessions.
+
+gh (GitHub CLI)
+~~~~~~~~~~~~~~~
+
+The GitHub CLI is needed for the gh tool to interact with GitHub repositories, issues, and pull requests. Installation instructions vary by platform - see the `official documentation <https://cli.github.com/>`_.
+
+wl-clipboard
+~~~~~~~~~~~~
+
+Needed for clipboard operations on Wayland-based Linux systems. Not required on X11 systems or other platforms.
+
+pdftotext
+~~~~~~~~~
+
+Part of the poppler utilities, used for extracting text from PDF files. Install the ``poppler-utils`` package on Debian/Ubuntu or ``poppler`` on macOS.
