snafu

SNAFU (Symbol Name Ambiguity Fixer-Upper) is a command-line developer tool that uses Large Language Models (LLMs) to help developers choose clearer and less ambiguous names for symbols in their source code. It introduces a metric called the Name Ambiguity Number (NAN), which quantifies how easily a symbol name might be misinterpreted. The tool operates through a multi-step agentic pipeline. First, it extracts symbols from a source file and sends them to an LLM without any surrounding context (such as function bodies or docstrings) to simulate the cognitive load of a developer reading the code with fresh eyes. The LLM provides a list of plausible, mutually exclusive interpretations for the name, along with probabilities. SNAFU uses these probabilities to calculate the Shannon entropy and derives the NAN, where a lower score indicates a clearer name. A human-in-the-loop step follows, where the user confirms the actual intended meaning of the symbol. The LLM then suggests a new name that expresses only that confirmed meaning. This proposed name is re-evaluated to calculate a new NAN. If the new name does not reduce the ambiguity (a positive delta), it is discarded. Surviving suggestions undergo a final sanity check by an LLM with full context to ensure the new name is sensible and aligns with the confirmed meaning. Finally, a report of the proposed renames is presented to the user. SNAFU requires Python 3.14 or later and the `uv` package manager. It supports multiple LLM providers via the `any-llm` library, allowing users to specify different models using the `--model` flag. By default, it natively understands Python and uses Tree-sitter for symbol extraction in other languages, including Ruby, C#, Java, JavaScript, TypeScript, PHP, Rust, and Go.