I built a dead code forensics CLI because "this file is unused" is never enough

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