{"slug": "show-hn-snafu-agentic-flow-to-help-you-with-naming-things-in-source-code", "title": "Show HN: Snafu: Agentic flow to help you with \"naming things\" in source code", "summary": "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.", "body_md": "Is \"naming things\" hard? And if so, can one detect and measure name quality? Rhetorical question. The answer is yes.\n\n`snafu`\n\nis an agentic LLM flow to help you with \"naming things\" in source\ncode.\n\n`snafu`\n\ncomputes the **Name Ambiguity Number (NAN)** for symbols in your\ncodebase, a quantifiable score for how ambiguous the name is. Then it walks\nyou through an *agentic pipeline™* to replace it with a clearer name.\n\n## demo.mp4\n\n`snafu`\n\nfirst obtains symbols in your source file, and sends them\nalong the `snafu`\n\npipeline with **no extra context** (no function body, no\ndocstring, no surrounding code).\n\nOur 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.\n\nNote: Currently *not all symbols are extracted*. We currently try to find the\nmost relevant symbols (by kind and hierarchy), while avoiding symbols which\nare often superfluous, like inline variables.\n\nEvery symbol in the file is sent to an LLM with *no other context* and one\nquestion: *given only this name, what are the plausible, mutually-exclusive\nthings it could mean, and how likely is each one?*\n\nThe model returns a short list of interpretations with probabilities that\nsum to 1. For a symbol like `process_request`\n\n, that might look like:\n\n```\n0.55  handle an incoming request end-to-end (parse, validate, respond)\n0.30  transform/normalize a request object before use elsewhere\n0.15  log or record that a request occurred\n```\n\nNaturally, 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.\n\nThat distribution is the raw material to generate the **Name Ambiguity Number\n(NAN)**. Here's how it's built:\n\nIf an interpretation has probability `p`\n\n, we obtain the **Shannon Entropy** of\nthe symbol like this:\n\n```\nshannon_entropy(symbol) = - sum(p[i] * log2(p[i]))\n```\n\nThis 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')\"\n\nYes, it's tricky. It's a bit of statistics and a bit of computer science. In simpler terms:\n\n- If the number is\n`0`\n\n, 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.\n\nNAN is actually a modification, to make it easier to reason about:\n\n```\nNAN(s) = 2 ** shannon_entropy(s)   # aka \"perplexity\"\n```\n\nNow, if a symbol had `k`\n\n*equally likely* interpretations, `NAN = k`\n\n.\n\nA small example:\n\n| interpretation split | NAN |\n|---|---|\n| 50 / 50 | 2.00 |\n| 90 / 10 | 1.38 |\n| 99 / 1 | 1.06 |\n\nAll three rows have \"2 interpretations,\" but NAN correctly reports that a 99/1\nsplit is barely ambiguous (`NAN = 1`\n\nis the ideal).\n\n`snafu`\n\nshows you each symbol's interpretations (and their probabilities) and\nasks which one is actually correct, or type your own description if none of\nthem fit.\n\nThis **human-in-the-loop** step provides the ground truth the rest of the\npipeline builds on.\n\nFor every symbol you confirmed, the LLM is given the original name and your\nconfirmed meaning, and asked to propose a new name that expresses *only* that\nmeaning, better than the previous name.\n\nThe proposed name goes through the exact same first step: getting fresh\ninterpretations, and calculating a new NAN. This produces a **NAN delta**:\n\n```\ndelta = NAN(original) - NAN(proposed)\n```\n\nA positive delta means the new name is less ambiguous than the old one. Any\ncandidate that doesn't improve (`delta ≤ 0`\n\n) is **dropped** here.\n\nA model reviews each surviving rename with full context: both names, the confirmed meaning, and each name's top alternative interpretation.\n\nIt checks two things: does the new name make sense on its own, and is its top interpretation matching the confirmed meaning.\n\nThis catches renames that scored well numerically but are wrong or misleading.\n\nFinally, the information for all proposed renames are presented to the user.\n\n- Python >= 3.14\n`uv`\n\nInstall with `uv`\n\n, from inside this repo:\n\n```\nuv tool install .              # installs the `snafu` command on PATH\n```\n\nOr straight from the git repository:\n\n```\nuv tool install git+https://github.com/sebastiancarlos/snafu\nexport OPENAI_API_KEY=sk-...\nexport OPENAI_BASE_URL=https://my-custom-host/v1 # optional override\n\nsnafu path/to/file.py\n```\n\n`snafu`\n\nuses the ** any-llm** library (a lightweight version of\n\n**LiteLLM**) to support connecting to any LLM provider.\n\nPass `--model`\n\nas `<provider>:<model-name>`\n\nto use any supported provider. A\nbare name with no prefix (e.g. `gpt-4o-mini`\n\n) is treated as OpenAI.\n\n```\nsnafu file.py --model anthropic:claude-haiku-4-5-20251001\nsnafu file.py --model gemini:gemini-2.5-flash\n```\n\nEach provider reads configuration from their own env var (`OPENAI_API_KEY`\n\n,\n`OPENAI_BASE_URL`\n\n, `ANTHROPIC_API_KEY`\n\n, ...). For the full list of supported\nproviders, model names, and env vars, see the [any-llm provider\ndocs](https://docs.mozilla.ai/any-llm/providers/).\n\nBy default `snafu`\n\nunderstands Python natively and uses **Tree-sitter** for\nsymbol extraction in other languages: Ruby, C#, Java, JavaScript, TypeScript,\nPHP, Rust, and Go.\n\nTree-sitter grammars download on first use per language.\n\n```\nusage: snafu [-h] [--symbols-file SYMBOLS_FILE] [--dry-run] \n             [--min-words MIN_WORDS] [--model MODEL] [--limit LIMIT] [file]\n\nCompute and improve \"Name Ambiguity Numbers (NAN)\" for symbols in source code.\n\npositional arguments:\n  file                  source file to analyze\n\noptions:\n  -h, --help            show this help message and exit\n  --symbols-file SYMBOLS_FILE\n                        read symbols from this file, one per line, instead of\n                        extracting them from a source file (used as-is,\n                        --min-words not applied)\n  --dry-run             only extract and list symbols, then exit (no LLM\n                        calls)\n  --min-words MIN_WORDS\n                        only score symbols with >= N words (default 2)\n  --model MODEL         model to use (default gpt-4o-mini)\n  --limit LIMIT         cap number of symbols to process\n\nEnv vars:\n    OPENAI_API_KEY      OpenAI key (required for OpenAI models)\n    OPENAI_BASE_URL     optional; base URL, e.g. https://my-host/v1\n\n    Other providers read their own env vars (ANTHROPIC_API_KEY, ...).\n    See https://docs.mozilla.ai/any-llm/providers/ for the full list.\n```\n\nMIT", "url": "https://wpnews.pro/news/show-hn-snafu-agentic-flow-to-help-you-with-naming-things-in-source-code", "canonical_source": "https://github.com/sebastiancarlos/snafu", "published_at": "2026-08-15 23:30:54+00:00", "updated_at": "2026-08-15 23:40:30.945109+00:00", "lang": "en", "topics": ["artificial-intelligence", "large-language-models", "developer-tools", "ai-tools"], "entities": ["Snafu", "Hacker News"], "alternates": {"html": "https://wpnews.pro/news/show-hn-snafu-agentic-flow-to-help-you-with-naming-things-in-source-code", "markdown": "https://wpnews.pro/news/show-hn-snafu-agentic-flow-to-help-you-with-naming-things-in-source-code.md", "text": "https://wpnews.pro/news/show-hn-snafu-agentic-flow-to-help-you-with-naming-things-in-source-code.txt", "jsonld": "https://wpnews.pro/news/show-hn-snafu-agentic-flow-to-help-you-with-naming-things-in-source-code.jsonld"}}