Show HN: Snafu: Agentic flow to help you with "naming things" in source code Snafu, an agentic LLM flow introduced on Hacker News, computes a Name Ambiguity Number (NAN) for symbols in source code to measure and improve naming quality. The tool strips context from symbols, asks an LLM for plausible interpretations with probabilities, and uses Shannon entropy to derive NAN, then proposes clearer names through a human-in-the-loop pipeline. Snafu drops any candidate rename that does not reduce ambiguity (delta ≤ 0) and reviews survivors with full context. Is "naming things" hard? And if so, can one detect and measure name quality? Rhetorical question. The answer is yes. snafu is an agentic LLM flow to help you with "naming things" in source code. snafu computes the Name Ambiguity Number NAN for symbols in your codebase, a quantifiable score for how ambiguous the name is. Then it walks you through an agentic pipeline™ to replace it with a clearer name. demo.mp4 snafu first obtains symbols in your source file, and sends them along the snafu pipeline with no extra context no function body, no docstring, no surrounding code . Our heuristic is: reducing the ambiguity of a symbol with no extra context will also reduce it even when the symbol is back in its original context. By stripping the context away, we simulate the cognitive load of a developer reading a function with fresh eyes. Note: Currently not all symbols are extracted . We currently try to find the most relevant symbols by kind and hierarchy , while avoiding symbols which are often superfluous, like inline variables. Every symbol in the file is sent to an LLM with no other context and one question: given only this name, what are the plausible, mutually-exclusive things it could mean, and how likely is each one? The model returns a short list of interpretations with probabilities that sum to 1. For a symbol like process request , that might look like: 0.55 handle an incoming request end-to-end parse, validate, respond 0.30 transform/normalize a request object before use elsewhere 0.15 log or record that a request occurred Naturally, the LLM can generate interpretations and probabilities which are not correct. Yet, we believe that an LLM is a good-enough measure of semantic ambiguity for our needs. That distribution is the raw material to generate the Name Ambiguity Number NAN . Here's how it's built: If an interpretation has probability p , we obtain the Shannon Entropy of the symbol like this: shannon entropy symbol = - sum p i log2 p i This is basically "the weighted average of the number of steps one should take on a binary decision tree which identifies an outcome the 'outcome' being the result of 'picking an interpretation' " Yes, it's tricky. It's a bit of statistics and a bit of computer science. In simpler terms: - If the number is 0 , there is only one possible interpretation this is the ideal - The higher the number, the more variance of reasonable interpretations that someone reading the symbol might choose. NAN is actually a modification, to make it easier to reason about: NAN s = 2 shannon entropy s aka "perplexity" Now, if a symbol had k equally likely interpretations, NAN = k . A small example: | interpretation split | NAN | |---|---| | 50 / 50 | 2.00 | | 90 / 10 | 1.38 | | 99 / 1 | 1.06 | All three rows have "2 interpretations," but NAN correctly reports that a 99/1 split is barely ambiguous NAN = 1 is the ideal . snafu shows you each symbol's interpretations and their probabilities and asks which one is actually correct, or type your own description if none of them fit. This human-in-the-loop step provides the ground truth the rest of the pipeline builds on. For every symbol you confirmed, the LLM is given the original name and your confirmed meaning, and asked to propose a new name that expresses only that meaning, better than the previous name. The proposed name goes through the exact same first step: getting fresh interpretations, and calculating a new NAN. This produces a NAN delta : delta = NAN original - NAN proposed A positive delta means the new name is less ambiguous than the old one. Any candidate that doesn't improve delta ≤ 0 is dropped here. A model reviews each surviving rename with full context: both names, the confirmed meaning, and each name's top alternative interpretation. It checks two things: does the new name make sense on its own, and is its top interpretation matching the confirmed meaning. This catches renames that scored well numerically but are wrong or misleading. Finally, the information for all proposed renames are presented to the user. - Python = 3.14 uv Install with uv , from inside this repo: uv tool install . installs the snafu command on PATH Or straight from the git repository: uv tool install git+https://github.com/sebastiancarlos/snafu export OPENAI API KEY=sk-... export OPENAI BASE URL=https://my-custom-host/v1 optional override snafu path/to/file.py snafu uses the any-llm library a lightweight version of LiteLLM to support connecting to any LLM provider. Pass --model as