killpy: Instructions file for Codex

AGENTS.md

Project Overview

killpy is a Python CLI/TUI utility to find and remove Python-related environments and free disk space.

Main capabilities:

• Discover local virtual environments (.venv and folders containing pyvenv.cfg)
• Discover Conda environments
• Discover Poetry virtualenvs
• Discover installed pipx packages and uninstall them
• Remove __pycache__ directories

Primary UX:

• Interactive terminal UI (Textual app) for listing and deleting environments
• CLI command to clean caches (killpy clean)

Goal

Help users reclaim disk space safely by surfacing Python environments with size info and allowing explicit deletion actions.

Tech Stack

• Python >=3.10 (CI/classifiers cover 3.10–3.13; ruff targets py310)
• click for CLI command routing
• textual for interactive terminal UI
• rich as a dependency used by Textual ecosystem and terminal rendering

Reference links:

• Textual docs: https://textual.textualize.io/
• Textual repository: https://github.com/Textualize/textual
• Rich docs: https://rich.readthedocs.io/en/latest/introduction.html
• Rich repository: https://github.com/Textualize/rich

Packaging and tooling:

• pyproject.toml (PEP 621 metadata)
• uv support ([tool.uv] package = true)
• Commit/version workflow via commitizen
• Lint/type/test dev tooling declared under [dependency-groups].dev

Repository Structure

Top-level:

• pyproject.toml — package metadata, dependencies, scripts, tool config
• README.md — user documentation
• CHANGELOG.md — release history
• .github/workflows/ — CI/release automation

Package layout (killpy/):

• __main__.py — CLI entrypoint (killpy script); the cli click group, the --delete-all fast path, and subcommand registration
• cli.py — Textual app (TableApp) and interactive actions
• models.py — shared dataclasses: Environment (core contract), plus GitInfo, ScoredEnvironment, Suggestion, ScanRecord
• scanner.py — Scanner: orchestrates detectors, deduplicates results
• cleaner.py — Cleaner: deletion via shutil.rmtree, conda env remove, pipx uninstall, or uv tool uninstall (routed by Environment.managed_by)
• commands/clean.py — killpy clean subcommand
• commands/delete.py — killpy delete subcommand
• commands/list.py — killpy list subcommand
• commands/stats.py — killpy stats subcommand
• commands/doctor.py — killpy doctor subcommand (health report + scoring)
• commands/find.py — killpy find subcommand (locate a package across envs)
• commands/_utils.py — shared command helpers (filter_envs, partition_in_use)
• intelligence/ — scoring layer: git_analyzer.py, scoring.py, suggestions.py, tracker.py (scan-history persistence)
• cleaners/__init__.py — remove_pycache helper
• files/__init__.py — file-size helpers (get_total_size, format_size)
• detectors/ — one detector class per environment type:
  • base.py — AbstractDetector interface
  • venv.py — .venv dirs and pyvenv.cfg-based envs
  • pyenv.py — pyenv-managed Python versions
  • poetry.py — Poetry global virtualenv cache
  • conda.py — Conda environments
  • pipx.py — pipx packages
  • hatch.py — Hatch environments
  • pipenv.py — Pipenv virtualenvs
  • tox.py — tox .tox directories
  • uv.py — uv tool environments (uv tool install) and uv-managed Python installs
  • artifacts.py — build artifacts (dist/, build/, *.egg-info)
  • cache.py — cache dirs (__pycache__, .mypy_cache, .pytest_cache, …)