All jobs

Find Dead Code in a Python Library

Yes. An agent runs vulture and coverage over your Python package, checks each candidate against the public API and tests, and reports what is safe to delete.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the package shape first. In a library like psf/requests the code is src/requests, 19 modules and about 6,400 lines, with models.py, utils.py, sessions.py and adapters.py holding most of it. pyproject.toml says requires-python >= 3.10, builds with setuptools, and configures ruff, pytest with --doctest-modules and pyright in strict mode. The [dependency-groups] test group lists pytest-httpbin, httpbin, pytest-cov, pytest-mock, pytest-xdist and trustme; the Makefile runs python -m pytest tests for test, adds --junitxml for ci, and has a coverage target that runs pytest with --cov=src/requests. .coveragerc omits requests/packages/*.

Two files tell the agent what is deliberately unused. src/requests/compat.py says in its docstring that it previously handled Python 2 and 3 import differences and remains for backwards compatibility until the next major version, and it still defines is_py2, is_py3, has_simplejson and the JSONDecodeError import dance. src/requests/packages.py writes urllib3, idna and the detected chardet module into sys.modules under requests.packages.* so old import paths keep working. The ruff config confirms the intent: per-file-ignores turns off F401 for __init__.py and compat.py, so unused imports there are exports. A dead-code report that listed those as deletable would be wrong, and the agent treats __all__ in __init__.py, those two modules and every name documented under docs/ as public.

With that map it runs the tools. vulture src/requests --min-confidence 60 lists unused functions, classes, variables and imports with a confidence score; make coverage produces line coverage from the test suite, and lines never executed by tests/ are a second signal, not proof. For each candidate the agent asks three questions in order: is the name in __all__, in compat.py or packages.py, or mentioned in docs/; does grep find it anywhere else under src/ or tests/; and if it is deleted, do python -m pytest tests, ruff check and pyright still pass. Only a candidate that clears all three goes in the safe list, and the agent deletes and restores each one in the sandbox to run that check, one at a time, with git keeping the tree clean between them.

The result is dead-code.md with four sections: safe to remove, each with file, line, the vulture confidence and the test command that passed without it; unused internally but public, kept, with where the docs or __all__ name it; compatibility shims, kept, quoting the compat.py docstring and the ruff ignores as the reason; and candidates the agent could not decide, with what it tried. Every line in the first section has been removed once and tested.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Find dead code in this Python package and write a report. Read pyproject.toml, the Makefile, .coveragerc and the package's __init__.py and any compatibility module first, and treat every name in __all__, every name a compatibility module keeps on purpose, and every name mentioned under docs/ as public. Install the test dependency group, run vulture over the source with a moderate confidence threshold, and run the test suite with coverage. For each candidate, check the public-API rule, grep the source and tests for other references, then delete it in the working tree and run the tests, the linter and the type checker; restore it afterwards. Write dead-code.md with four sections: safe to remove with file, line and the passing command for each; unused internally but public, kept; compatibility code kept on purpose with the reason quoted; and undecided candidates with what you tried. Include the exact tool commands and their output. Do not open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is dead-code.md as an artifact on the session, with a download link on GET /o/{org}/sessions/{id} under artifacts, good for an hour and refreshed on every read. No branch, no pull request, no change to the repository: every deletion the agent made to test a candidate was reverted before the report was written.

The report's first section is the deliverable: a table of names with file, line, vulture's confidence, and the pytest, ruff check and pyright commands that passed with the name removed. The other three sections are what stops a maintainer from deleting the wrong thing, in particular the compatibility shims compat.py keeps for the next major version and the requests.packages aliases. The full command output, including the vulture listing and the coverage table, is in the transcript at GET /o/{org}/sessions/{id}/messages.

A maintainer reads the safe list against the changelog and the deprecation policy, since a name can be absent from docs/ and __all__ and still be imported by downstream projects, and then opens the deletion pull request themselves or asks a follow-up on the same session to do it, one commit per name.

Run it on every first Monday of the month

Unused code accumulates slowly, so a monthly report is enough. A cron job on your server sends this request on the first Monday of the month with a request_id that is a UUID v5 of the month and the repository, so a retried request returns the run it already started. Each run starts from a fresh clone of the default branch, so the report describes the package as it is that morning and never a stale checkout.

Give the key a webhook_url and Rush POSTs run.completed when the turn finishes, with data.session_url. A handler reads the session, takes the dead-code.md artifact link and files it as an issue or posts it where the maintainers plan cleanup work.

The use case this job follows, with its automation and trigger: Produce a report or file, no repo.

Why run it on Rush?

Dead-code tools are cheap to run and expensive to trust: vulture on a library with a public API lists exports and compatibility shims as unused, and acting on that list breaks downstream users. The judgement is in the checking, and the checking is slow by hand: delete a name, run the suite, run the type checker, restore, repeat. The agent does that loop in a sandbox for every candidate, with the test group installed and the real test suite, and the laptop stays free.

The report carries the command that passed for each deletion, and the run keeps every command and its output, so a maintainer verifies a line by rerunning one command rather than redoing the audit. Several packages can be audited at once, each in its own sandbox.

Frequently asked questions

Will it delete anything from my repository?

No. Deletions happen in the sandbox's working tree to test each candidate and are reverted before the report is written. The run leaves no branch and opens no pull request; the result is the report.

How does it avoid flagging the public API?

It reads __all__, the compatibility modules the package keeps on purpose, and docs/, and treats anything named there as public before vulture runs. In requests that covers compat.py, packages.py and the names ruff's per-file-ignores already mark as deliberate exports.

Is low test coverage treated as dead code?

No. A line the tests never execute is listed as a signal in the undecided section, not in the safe list. Only a name that no code references and whose removal leaves the tests, linter and type checker passing is called safe.

What about code only used on some Python versions or platforms?

The sandbox runs one interpreter, so a branch for Windows or PyPy can look unused. The agent greps for sys.platform, sys.version_info and TYPE_CHECKING guards around a candidate and moves anything behind one to the kept or undecided sections with that reason.

More Python jobs

The same job on other stacks

Keep reading