Skip to content

TechDebtAssassin

TechDebtAssassin is an autonomous AI agent that eliminates the "janitorial" busywork of technical debt.

Code Video Cerebral Valley

Core trick

Scans the AST for missing type hints, generates patches with project-wide context, and reruns mypy until the checks pass.

Tags

dev tools

Description

TechDebtAssassin is an autonomous AI agent that eliminates the "janitorial" busywork of technical debt. Unlike standard coding assistants that wait for prompts, TechDebtAssassin is a proactive specialist that modernizes entire repositories without human intervention. Powered by Claude Opus 4.6 and the Model Context Protocol (MCP), the agent builds a Global Project Context to reason across file boundaries—inferring complex type hints and architectural dependencies that local-context LLMs miss. It features a robust "Self-Healing" pipeline: scanning the AST for debt, generating type-safe patches, applying them physically to the disk, and running a final verification loop (using mypy) to ensure 100% code health. Built for Problem Statement One, TechDebtAssassin transforms hours of manual refactoring into a one-click autonomous process, turning codebase maintenance from a chore into a reliable DevOps stage.
jchiru21/tech-debt-assassin★ 20 forksPythonCreated Feb 11, 2026 · last push Jun 28, 2026

README excerpt

# TechDebtAssassin

[![CI](https://github.com/jchiru21/tech-debt-assassin/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jchiru21/tech-debt-assassin/actions/workflows/ci.yml)

An autonomous AI agent that scans a Python codebase, identifies missing type hints,
patches them with cross-file accuracy, and verifies the results.

Works with multiple AI providers: Anthropic, OpenAI, OpenRouter, Groq, Gemini, or
any OpenAI-compatible endpoint.

---

## How It Works

```
scan ──> fix (with global project context) ──> verify
  │               │                                │
  │       configured AI provider             mypy + pytest
  │       sees entire project
  │                                                │
  └────────────── re-scan to confirm ◄─────────────┘
```

1. **Scan** -- Parses every `.py` file with Python's `ast` module and identifies functions missing type annotations.
2. **Fix** -- Builds a global project context (file tree, class definitions, function signatures) and sends it with each function to the configured AI provider chain for cross-file type inference. Patches are applied directly to source files.
3. **Verify** -- Runs `mypy` and `pytest` to confirm the patches are correct.

The global context means the model knows that `User` in `main.py` refers to the dataclass in `models.py` -- it doesn't guess `Any`.

---

## Quick Start

**Prerequisites:** Python 3.10+ and at least one supported AI API key.

```bash
git clone https://github.com/jch

Team