{"slug": "show-hn-neat-static-code-and-otel-fused-into-one-graph-for-agents-oss", "title": "Show HN: Neat, Static code and OTel fused into one graph for agents (OSS)", "summary": "NEAT Technologies released NEAT, an open-source tool that fuses static code analysis and OpenTelemetry runtime telemetry into a single live graph to reduce AI agent hallucinations and improve debugging accuracy. The tool, installable via `npx neat.is`, discovers services, extracts static graphs, wires OpenTelemetry, and exposes sixteen MCP tools for querying root cause, blast radius, dependencies, and policy violations.", "body_md": "NEAT solves the AI coding context problem. It constructs a live deterministic model of your codebase — static code and live runtime behavior fused into one graph — and hands your AI agents the grounded, full-stack context they need to query, code, debug, and write rules against it. This achieves the following:\n\n- Coding LLMs hallucinate less & are more accurate.\n- Rather than endlessly grepping files and guessing problems, NEAT provides time-travelling error logs along the model's nodes and edges so the LLM can infer exactly what's wrong.\n- Rules & Policies allow agents to write new features while adhering to rules set by previous features, other LLMs, or engineers. For example, only use postgres for services x and y, and mongoDB for services p and q (the possibilities are endless).\n\nTL;DR The deterministic grounded truth of code for your agents.\n\nNEAT is in active development. Capability ships as patch releases on the `npx neat.is`\n\nsurface; see [open issues](https://github.com/NEAT-Technologies/Neat/issues) for what's on deck.\n\n```\nnpx neat.is\n```\n\nRun it from inside your project (or `npx neat.is <path>`\n\n). It discovers your services, extracts the static graph, wires in OpenTelemetry, starts the daemon, and opens the dashboard — no config. Then run your app and watch the live edges populate.\n\nOn Windows, use thenpm generates a shim literally named`neat`\n\ncommand, not`npx neat.is`\n\n.`neat.is`\n\n, and Windows won't execute a`.is`\n\nfile — it hands it to a file association instead. Install once and run the dotless binary:`npm i -g neat.is`\n\n, then`neat`\n\n(or`neat <path>`\n\n). Without a global install:`npx -p neat.is neat`\n\n. Every`npx neat.is <verb>`\n\nbelow becomes`neat <verb>`\n\nthis way.\n\nAt the center of NEAT is **one live graph** of your system, fused from two streams into a single model you can query many ways:\n\n**Static analysis**— tree-sitter over your source (JavaScript, TypeScript, Python),`package.json`\n\n, and yaml / env config. Every source file becomes a node; imports between them become edges; the calls each file makes to databases, queues, and external hosts are extracted from the code.**Runtime telemetry**— OpenTelemetry spans, attributed back to the exact file and line that made the call. NEAT wires the instrumentation for you, so the runtime edge lands on the same file node the static edge does.\n\nBoth streams land on the same nodes, so the graph holds what your code *declares* and what your system *does* side by side. From there, the useful questions fall out of one model: what would break if this node dies (blast radius), what broke first (root cause), which architectural rules a change would violate (policies), and where declared intent and observed reality part ways (divergence). Same graph, different traversals.\n\n**The file is the primary unit.** A relationship in the graph runs from a file — `src/services/billing.ts ──CALLS──▶ api.stripe.com`\n\n— not from a vague service blob. Anchoring relationships to files and lines is what keeps every one of those answers sharp: a finding names *this file*, calling *this target*, rather than a service-shaped shrug.\n\nEvery edge carries a `provenance`\n\ntag so a consumer knows exactly how much weight a claim deserves:\n\n`EXTRACTED`\n\nfrom source. No clock decay.`OBSERVED`\n\nfrom a span. Carries`lastObserved`\n\nand`callCount`\n\n.`INFERRED`\n\nby the trace stitcher where OTel coverage has gaps. Confidence is capped.`STALE`\n\nbecause runtime stopped speaking. Preserves the original`lastObserved`\n\n.\n\nThe graph is exposed to AI agents through sixteen MCP tools. Ten read the graph — `get_root_cause`\n\n, `get_blast_radius`\n\n, `get_dependencies`\n\n, `get_observed_dependencies`\n\n, `get_incident_history`\n\n, `get_divergences`\n\n, `get_graph_diff`\n\n, `get_recent_stale_edges`\n\n, `check_policies`\n\n, `semantic_search`\n\n— and six (`neat extend`\n\n) let an agent close instrumentation gaps for libraries the bundled OTel set doesn't cover, driven by a versioned [instrumentation registry](/neat-technologies/neat/blob/main/docs/installer-scope.md).\n\nThe same `neat`\n\nbinary handles every verb. After a global install (`npm i -g neat.is`\n\n) or via `npx neat.is`\n\n:\n\n```\nneat <path>              orchestrator: extract, instrument, spawn daemon, open dashboard\nneat init <path>         extract only; patch-by-default, --apply to write\nneat watch <path>        keep the graph live as files change\nneat deploy              emit deployment artifacts for a hosted target\nneat sync --to <url>     push the local EXTRACTED snapshot to a remote daemon (v0.3.9)\nneat divergences         where your code and your production traffic disagree\nneat root-cause <id>     walk inbound edges to find what broke first\nneat blast-radius <id>   BFS outbound; what would break if this node dies\nneat dependencies <id>   transitive outbound dependencies\nneat incidents           recent error events\nneat policies            current policy violations\nneat search <query>      semantic match on node names and ids\n```\n\nEvery query verb honors `--json`\n\nand `--project <name>`\n\n. Exit codes branch on success (0), server error (1), misuse (2), and daemon unreachable (3).\n\nA divergence is one of the questions the graph answers, and the one that's hardest to get any other way — it needs both streams at once. Once your app has run, `neat divergences`\n\nreports where declared intent and observed behavior part ways:\n\n```\n[missing-extracted] src/services/prices.ts ──CALLS──▶ folio-api.example.com   confidence 0.87\n  Production observed this call, but static analysis never surfaced the edge.\n  → dynamic dispatch or a coverage gap. The code reaches a host it doesn't visibly name.\n\n[missing-observed]  src/db/client.ts ──CONNECTS_TO──▶ postgres:primary        confidence 0.85\n  Code declares this connection, but no production traffic has exercised it.\n  → dead path, feature flag, or an unshipped branch. The declared dependency is idle.\n```\n\nTwo findings, two different bugs. The first is a call your code makes without saying so — worth knowing before it surprises you. The second is a dependency your code carries but never uses — dead weight, or a path you thought was live and isn't. Both come from comparing the same file against itself: what it says, versus what it did.\n\nDivergence reports what *is*. Policies let you assert what *should be*. A `policy.json`\n\nin your project declares architectural rules as assertions over the same graph — for example, \"only `service:billing`\n\nand `service:orders`\n\nmay connect to `postgres:primary`\n\n,\" or \"no file may call `legacy-api.internal`\n\n.\" Because the rules run against the live graph, they evaluate against both what your code declares and what production actually does.\n\nNEAT evaluates every policy continuously as the graph changes. When an edge violates a rule, the violation is surfaced — not buried in a one-off lint run. Two surfaces expose it:\n\nlists what's currently violating, scoped to a node with`neat policies`\n\n`--node`\n\n, or dry-run a change with`--hypothetical-action`\n\n.hands the same answer to an AI agent over MCP, so an agent writing a new feature can see which rules it would cross and the assertions it's working within — the rules previous features, other agents, or your engineers already set.`check_policies`\n\nA `block`\n\naction gates promotion of a `FrontierNode`\n\n(an external host the graph has newly seen) so unsanctioned external dependencies don't quietly settle into the model. The throughline: the graph already knows your architecture, so the rules you care about become assertions over it that stay true as the system moves.\n\nThe container image at `ghcr.io/neat-technologies/neat:latest`\n\nboots `neatd start`\n\nand exposes REST on `:8080`\n\n, OTLP on `:4318`\n\n, and the web UI on `:6328`\n\n. Generate a token, run the image, point your OTel SDKs at it:\n\n```\nNEAT_AUTH_TOKEN=$(openssl rand -hex 32)\ndocker run -d --name neat \\\n  -e NEAT_AUTH_TOKEN=\"$NEAT_AUTH_TOKEN\" \\\n  -p 8080:8080 -p 4318:4318 -p 6328:6328 \\\n  -v /var/lib/neat:/neat-out \\\n  ghcr.io/neat-technologies/neat:latest\n```\n\n`NEAT_AUTH_TOKEN`\n\nis required on every public interface. The daemon refuses to bind on non-loopback addresses without one. REST and SSE callers send the token in `Authorization: Bearer <token>`\n\n; OTel exporters send the same header. Rotate the OTLP token independently with `NEAT_OTEL_TOKEN`\n\n.\n\nEasier path: `neat deploy`\n\ngenerates the token, writes a `docker-compose.neat.yml`\n\n, and prints the env block your application's deploy platform needs:\n\n```\nOTEL_EXPORTER_OTLP_ENDPOINT=https://<your-host>:4318\nOTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <generated-token>\n```\n\nWhen TLS termination and authentication already live in a proxy upstream, set `NEAT_AUTH_PROXY=true`\n\nso the daemon skips the request-side bearer check. The bind-authority gate still refuses public binds without `NEAT_AUTH_TOKEN`\n\n, so set both:\n\n```\nneat.example.com {\n  reverse_proxy localhost:8080 {\n    header_up Authorization \"Bearer {env.NEAT_AUTH_TOKEN}\"\n  }\n  reverse_proxy /events localhost:8080\n  @otlp path /v1/traces\n  reverse_proxy @otlp localhost:4318 {\n    header_up Authorization \"Bearer {env.NEAT_AUTH_TOKEN}\"\n  }\n}\n```\n\nThen `docker run … -e NEAT_AUTH_TOKEN=… -e NEAT_AUTH_PROXY=true …`\n\nand let Caddy gate the public surface.\n\n```\nclaude mcp add neat -- neat-mcp\n```\n\nOr edit `~/.claude/settings.json`\n\nby hand:\n\n```\n{\n  \"mcpServers\": {\n    \"neat\": {\n      \"command\": \"neat-mcp\",\n      \"env\": { \"NEAT_CORE_URL\": \"http://localhost:8080\" }\n    }\n  }\n}\n```\n\nThe `neat-mcp`\n\nbinary above assumes a global install. Without one, run `neat skill --apply`\n\ninstead — it writes the same `mcpServers.neat`\n\nentry using `npx -y @neat.is/mcp`\n\nso the server resolves without a global binary. Either form reads `NEAT_CORE_URL`\n\nfor the daemon URL; set it to point the agent at a non-default daemon.\n\nIn any Claude Code session, ask: *\"Why is checkout-svc failing?\"* NEAT walks the graph and answers with a traversal path, edge provenances, a confidence score, and a recommended fix.\n\n```\nneat hooks --apply\n```\n\nThis installs two nudges so your agent queries the graph before it falls back to raw text search:\n\n**A Claude Code search-nudge hook**— a`PreToolUse`\n\nhook that, when the agent reaches for`Grep`\n\n/`Glob`\n\nor a Bash`grep`\n\n/`rg`\n\n/`find`\n\n, injects a note pointing it at`semantic_search`\n\n,`get_dependencies`\n\n, and`get_divergences`\n\nfirst. It is a gentle, non-blocking nudge: the search still runs. It merges into`~/.claude/settings.json`\n\nwithout touching your other hooks, and re-running is idempotent.**Agent-agnostic graph-first guidance**— a markdown block (`GRAPH_FIRST.md`\n\n, also written to`~/.neat/neat-graph-first.md`\n\n) to paste into`CLAUDE.md`\n\n/`AGENTS.md`\n\n/`.cursorrules`\n\n, so agents on any harness get the same steer.\n\nThe hook is specific to Claude Code; other harnesses (Codex, Gemini, Cursor) rely on the guidance block instead. `neat hooks --print-hook`\n\n, `--print-guide`\n\n, and `--print-settings`\n\nshow each piece without installing.\n\n```\npackages/\n  types/          shared Zod schemas: node, edge, event, result types\n  core/           graph engine, tree-sitter extraction, OTel ingest, REST API, neat CLI\n  mcp/            stdio MCP server exposing the sixteen tools to AI agents\n  web/            Next.js dashboard\n  claude-skill/   Claude Code skill metadata\n  neat.is/        umbrella package\n```\n\n: the user guide — getting started, core concepts, querying, AI agents, and troubleshooting. Start here.`docs/guide/`\n\n: the four edge states and how confidence travels along a path.`PROVENANCE.md`\n\n: guide for agents and contributors working in this repo.`CLAUDE.md`\n\n: package boundaries and data flow.`docs/architecture.md`\n\n: REST endpoints and MCP tool signatures.`docs/api-reference.md`\n\n: day-to-day commands and recovery recipes.`docs/runbook.md`\n\n: the binding rules every PR must hold to.`docs/contracts.md`\n\n: branch convention, PR shape, dev setup.`CONTRIBUTING.md`\n\n: how to report vulnerabilities.`SECURITY.md`\n\nPRs welcome. Read [ CONTRIBUTING.md](/neat-technologies/neat/blob/main/CONTRIBUTING.md) first for the branch convention, PR shape, and the contracts framework that gates every change.\n\nApache 2.0. See [ LICENSE](/neat-technologies/neat/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-neat-static-code-and-otel-fused-into-one-graph-for-agents-oss", "canonical_source": "https://github.com/neat-technologies/neat", "published_at": "2026-07-21 13:23:11+00:00", "updated_at": "2026-07-21 13:43:01.468569+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "artificial-intelligence", "large-language-models"], "entities": ["NEAT Technologies", "NEAT", "OpenTelemetry", "MCP"], "alternates": {"html": "https://wpnews.pro/news/show-hn-neat-static-code-and-otel-fused-into-one-graph-for-agents-oss", "markdown": "https://wpnews.pro/news/show-hn-neat-static-code-and-otel-fused-into-one-graph-for-agents-oss.md", "text": "https://wpnews.pro/news/show-hn-neat-static-code-and-otel-fused-into-one-graph-for-agents-oss.txt", "jsonld": "https://wpnews.pro/news/show-hn-neat-static-code-and-otel-fused-into-one-graph-for-agents-oss.jsonld"}}