Overview

DebtDrone is a Technical Debt Analyzer for engineering teams that need both human insight and machine enforcement — in a single binary.

The Dual-Mode Philosophy

Modern software teams operate in two contexts simultaneously: a developer sitting at a terminal exploring an unfamiliar codebase, and a CI/CD pipeline enforcing quality standards on every pull request. Most tools serve one context well and fail the other. DebtDrone serves both without compromise.

debtdrone                        # Launch the interactive TUI — for humans
debtdrone scan ./src --fail-on=high  # Headless quality gate — for machines

The same analysis engine powers interactive and headless scans. Supporting commands differ between the two interfaces; the guides below call out those differences explicitly.

Interactive Mode — for Humans

Launch debtdrone with no arguments and you enter a full-screen Terminal UI built with Bubble Tea and styled with Lipgloss. A command bar lets you run /scan, /history, /config, and /update against any local repository. Results are presented in a navigable master-detail layout where you can drill into every flagged function, read its debt estimate, and follow concrete refactoring suggestions — all without leaving the terminal.

Headless Mode — for Machines

The headless Cobra interface exposes scan, init, config, and history. The scan command emits a JSON array, integrates with GitHub Actions, and supports a Quality Gate (--fail-on) that exits non-zero when debt reaches a chosen severity threshold. Configure current scans with flags; the generated YAML file is not loaded yet.

What DebtDrone Analyzes

DebtDrone’s analysis engine parses syntax trees and computes multiple metrics per function across 14 languages: Go, JavaScript, TypeScript, Python, Java, C#, PHP, Ruby, Rust, Kotlin, Swift, C, C++, and JSX/TSX.

Metric	What It Measures
Cyclomatic Complexity	Number of independent execution paths through a function
Cognitive Complexity	How difficult the code is for a human to reason about
Nesting Depth	Maximum depth of nested control structures
Parameter Count	Arity of a function — a proxy for coupling
Lines of Code	Raw function size, correlating with maintainability burden
Halstead Metrics	Volume, effort, and estimated defect density (bugs/LOC)
Security Vulnerabilities	CVEs in dependencies and secrets in code, via Trivy

Every finding is assigned a severity of critical, high, medium, or low, and a debt estimate in minutes — a concrete number your team can use in sprint planning.

Key Features at a Glance

14-language support via tree-sitter syntax analysis
Security scanning powered by Trivy (CVEs + secrets detection)
Quality Gates — block merges when debt exceeds your threshold
Session scan history — revisit runs completed before the TUI exits
Interactive TUI with Vim keybindings and a master-detail layout
Structured JSON output for pipeline integration and reporting
debtdrone init generates a preview .debtdrone.yaml template
Built-in auto-updater — the binary keeps itself current

Quick Start

# Install via go install
go install github.com/endrilickollari/debtdrone-cli/v2/cmd/debtdrone@latest

# Explore your codebase interactively
debtdrone

# Run a headless scan and fail if any HIGH severity debt is found
debtdrone scan ./src --fail-on=high

Section	Description
Installation	Binary downloads, `go install`, and Homebrew
Interactive TUI Explorer	Full guide to the terminal UI and its commands
CI/CD & Headless CLI	`scan`, `history`, and Quality Gates for pipelines
Coverage execution for Go consumers	Artifact parsing and optional isolated test execution
Scanner ownership	Contribution boundary between the public scanner and SaaS
Configuration	Current flags and the status of `.debtdrone.yaml` support
System Architecture	Hexagonal design and the Bubble Tea router pattern