Every senior developer has stared at a file and thought: should I delete this?

You run vulture. You run deadcode. They both tell you the file has zero import
sites. You hover over the delete key.

And then you don't delete it. Because you don't actually know why it's there.

The real question isn't "is it dead?" — it's "why is it dead?"

Dead code falls into very different categories:

Category A — Accidentally orphaned. A file that got left behind when the
calling code was removed. Safe to delete immediately.

Category B — Intentionally parked. "keeping this around until Q2 rollout
completes." The holdback condition may or may not still apply.

Category C — Dynamically loaded. Appears dead to static analysis but gets
importlib.import_module()'d at runtime. Deleting it breaks production.

Category D — Replaced but not removed. The function was superseded by a better
implementation, the PR was merged, and nobody cleaned up. Safe to delete, but you
need to know what replaced it to be confident.

Existing tools treat all four identically: "unused." That's the gap fossil fills.

How fossil works

pip install fossil-code
fossil explain src/billing/legacy_processor.py

fossil runs five stages in under 3 seconds:

Stage 1: Static Analysis

Python's ast module builds a symbol table of everything the file exports. Then it
scans every other file in the repo for references — imports, calls, attribute access,
dynamic patterns (importlib, getattr, __import__). This is not grep; it's an
actual AST traversal that understands Python's import semantics.

Stage 2: Git History Mining

GitPython traverses git log --follow for the target file. It walks commits
newest-to-oldest, checking at each step whether any other file in the repo was still
referencing the target. The first commit where all references drop to zero is the
death commit.

Stage 3: Commit and PR Parsing

The death commit message is parsed for PR references (#441, PR 441,
pull request 441). If found, the PR title and merge context are extracted from the
commit body or (if a GitHub token is configured) via the GitHub API.

Stage 4: Pattern Detection

The file's current content is scanned for deferred-deletion patterns:

• TODO: remove after X
• keep for now / keep around until X
• DEPRECATED / @deprecated
• will be removed in version X
• temporary / temp fix

For each pattern, fossil attempts to verify the condition: does a PR with that
description exist and is it merged? Has a git tag for that version been created?
Has the referenced date passed?

Stage 5: Confidence Scoring

14 weighted signals are aggregated into a 0–100% score:

The output is a Rich panel with every signal explained, a risk label, and a
suggested action.

What it looks like