Add Claude Code session hooks and update developer documentation

Session hooks auto-setup venv, install deps, and activate on start.
Getting started docs updated for uv (replacing pyenv/pip/tox).
AGENTS.md quick start updated.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rtibbles

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "if [ ! -d .venv ]; then uv sync --group dev --python 3.10; else uv sync --group dev; fi && pnpm install && source .venv/bin/activate && prek install"
+      }
+    ]
+  }
+}

AGENTS.md

@@ -9,7 +9,7 @@
 ## Quick Start
 
 ```bash
-pip install -r requirements/dev.txt   # Python deps
+uv sync --group dev                   # Python deps + venv
 pnpm install                          # Node deps
 prek install                          # Required — commits fail without this
 export KOLIBRI_RUN_MODE=dev

docs/getting_started.rst

@@ -66,52 +66,37 @@ Finally, add the Learning Equality repo as a remote called `upstream`. That way
   git checkout -t upstream/develop # Checkout the development branch
 
 
-Python and Pip
-~~~~~~~~~~~~~~
-
-To develop on Kolibri, you'll need:
+Python and uv
+~~~~~~~~~~~~~
 
-* Python 3.9 or higher (Note: Kolibri does not yet support Python 3.15 or above)
-* `pip <https://pypi.python.org/pypi/pip>`__
+Kolibri uses `uv <https://docs.astral.sh/uv/>`__ to manage Python versions and virtual environments. Install uv following the `official installation guide <https://docs.astral.sh/uv/getting-started/installation/>`__.
 
-Managing Python installations can be quite tricky. We *highly* recommend using `pyenv <https://github.com/pyenv/pyenv>`__ or if you are more comfortable using a package manager, then package managers like `Homebrew <http://brew.sh/>`__ on Mac or ``apt`` on Debian for this.
+uv will automatically install the correct Python version when you set up the project — you do not need to install Python separately or use pyenv.
 
-To install pyenv see the detailed instructions here :doc:`/howtos/installing_pyenv`.
-..note::
-  If you are using a package manager, make sure to install a Python version compatible with Kolibri (3.9 or above, but below 3.15). If you're using `pyenv`, you can install it with a command like `pyenv install 3.9.9`.
-
-.. warning::
-  Never modify your system's built-in version of Python
+.. note::
+  Direct development on Windows is not supported. If you're using a Windows machine, please set up your development environment using WSL (Windows Subsystem for Linux).
 
 Python virtual environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You should use a Python virtual environment to isolate the dependencies of your Python projects from each other and to avoid corrupting your system's Python installation.
-
-There are many ways to set up Python virtual environments: You can use `pyenv-virtualenv <https://github.com/pyenv/pyenv-virtualenv>`__ as shown in the instructions below; you can also use `Virtualenv <https://virtualenv.pypa.io/en/latest/>`__, `Virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>`__ `Pipenv <https://pipenv.readthedocs.io/en/latest/>`__, `Python 3 venv <https://docs.python.org/3/library/venv.html>`__, `Poetry <https://poetry.eustace.io>`__ etc.
-
-.. note::
-  Most virtual environments will require special setup for non-Bash shells such as Fish and ZSH.
- Direct development on Windows is not supported. If you're using a Windows machine, please set up your development environment using WSL (Windows Subsystem for Linux).
+uv automatically creates and manages a virtual environment in the ``.venv`` directory. Set up the project:
 
-To setup and start using pyenv-virtualenv, follow the instructions here :doc:`/howtos/pyenv_virtualenv`.
+.. code-block:: bash
 
-Once pyenv-virtualenv is installed, you can use the following commands to set up and use a virtual environment from within the Kolibri repo:
+  uv sync --group dev          # Creates venv, installs Python, installs all dev deps
 
+Your virtual environment is now ready. Use ``uv run`` to execute commands within it:
 
 .. code-block:: bash
 
-  pyenv virtualenv 3.9.9 kolibri-py3.9  # can also make an environment for other Python versions, e.g. 3.10
-  pyenv activate kolibri-py3.9  # activates the virtual environment
-
-Now, any commands you run will target your virtual environment rather than the global Python installation. To deactivate the virtualenv, simply run:
+  uv run kolibri --version     # Run kolibri CLI
+  uv run pytest                # Run tests
 
+To activate the virtual environment in your shell (for interactive use):
 
 .. code-block:: bash
 
-  pyenv deactivate
-
-(Note that you'll want to leave it activated for the remainder of the setup process)
+  source .venv/bin/activate    # Linux/Mac
 
 .. warning::
   Never install project dependencies using ``sudo pip install ...``
@@ -150,20 +135,11 @@ There are two environment variables you should plan to set:
 Install Python dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To install Kolibri project-specific dependencies make sure you're in the ``kolibri`` directory and your Python virtual environment is active. Then run:
+Python dependencies are installed automatically by ``uv sync --group dev`` above. To update dependencies after pulling new changes:
 
 .. code-block:: bash
 
-  # required
-  pip install -r requirements.txt --upgrade
-  pip install -r requirements/dev.txt --upgrade
-  pip install -e .
-
-  # optional
-  pip install -r requirements/test.txt --upgrade
-  pip install -r requirements/docs.txt --upgrade
-
-Note that the ``--upgrade`` flags above can usually be omitted to speed up the process.
+  uv sync --group dev
 
 Install Node.js, pnpm and other dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -430,12 +406,11 @@ We have a large number of reusable patterns, conventions, and components built i
 Updating documentation
 ----------------------
 
-First, install some additional dependencies related to building documentation output:
+First, install the documentation dependencies:
 
 .. code-block:: bash
 
-  pip install -r requirements/docs.txt
-  pip install -r requirements/build.txt
+  uv sync --group docs
 
 To make changes to documentation, edit the ``rst`` files in the ``kolibri/docs`` directory and then run:
 
@@ -487,17 +462,13 @@ For more advanced usage, logical operators can also be used in wrapped strings,
 
   pytest kolibri/auth/test/test_permissions -k "MembershipPermissionsTestCase and test_admin_can_delete_membership"
 
-You can also use ``tox`` to setup a clean and disposable environment:
+You can run tests for a specific Python version using:
 
 .. code-block:: bash
 
-  tox -e py3.4  # Runs tests with Python 3.4
-
-To run Python tests for all environments, use simply ``tox``. This simulates what our CI also does on GitHub PRs.
-
-.. note::
+  uv run --python 3.9 pytest   # Runs tests with Python 3.9
 
-  ``tox`` reuses its environment when it is run again. If you add anything to the requirements, you will want to either delete the `.tox` directory, or run ``tox`` with the ``-r`` argument to recreate the environment
+CI runs tests across all supported Python versions automatically.
 
 
 Manual testing