Neat

# NEAT [](https://github.com/NEAT-Technologies/Neat/actions/workflows/ci.yml) [](./LICENSE) [](https://github.com/NEAT-Technologies/Neat/releases) [](https://neat.is) Agents are not good at investigation, and they are not good at reasoning. Given the right context, they are very good at writing code. NEAT does the investigation and the reasoning, so your agent can do the coding. The clearest example is the **incident card**. When something in your system fails, NEAT assembles one work order for it: where the failure is (down to the file and line when the runtime recorded one), the chain of what caused it, everything a fix will reach, the architectural rules that govern that code, and where the code and production disagree. Every claim carries how NEAT knows it — read from source, seen at runtime, or inferred — and nothing is guessed: a cause NEAT can't reach is left blank, not filled in. The agent reads the card and writes the fix, instead of grepping files and guessing at the cause. How NEAT does the investigation: it keeps a live graph of your running system. The real things in it are nodes — files and the symbols inside them, services, databases, routes, config, and infrastructure — joined by edges that each record how NEAT learned them: `EXTRACTED` from source, `OBSERVED` from OpenTelemetry, `INFERRED` by the stitcher that bridges gaps, `STALE` when the runtime stopped confirming an edge, and `FRONTIER` for a staged proposal. Fusion joins what the code declares to what production does at the same grain — file and line, symbol, host, database table — and those joins are where the answers are. The graph is deterministic and calls no LLM anywhere in the product: method, not model. Every NEAT capability is a read of that one graph, not a layer on top of it — root cause, blast radius, dependencies, the divergence between code and production, policy checks, incidents, and grades. When you are working a task of your own, ask the graph first — incidents, divergences, root cause, blast radius, dependencies — before you grep. The incident card above is the one NEAT hands you when it finds a failure worth it, not something you fetch. NEAT is in active development. Capability ships as patch releases on the `npx neat.is` surface; see [open issues](https://github.com/NEAT-Technologies/Neat/issues) for what's on deck. ## One command ```bash npx neat.is ``` Run it from inside your project (or `npx neat.is <path>`). It discovers your services, builds the static graph, attaches OpenTelemetry without editing your source, and starts a background daemon for the project — no config. Then start your app with NEAT attached — for Node, load the `.env.neat` it wrote (`set -a; . ./.env.neat; set +a`, then your usual start command); for Python, run your start command under `opentelemetry-instrument` — and the runtime half of the graph fills in as it runs. When a request fails, your agent asks for the work order over MCP: ``` get_incident_card { "nodeId": "service:checkout" } ``` and gets the locus, the cause chain with per-hop provenance, the blast radius, the governing policies and the divergences for that incident in one answer. `neat monitor` prints a line for each new incident as it lands. > **On Windows, use the `neat` command, not `npx neat.is`.** npm generates a shim literally named `neat.is`, and Windows won't execute a `.is` file — it hands it to a file association instead. Install once and run the dotless binary: `npm i -g neat.is`, then `neat` (or `neat <path>`). Without a global install: `npx -p neat.is neat`. Every `npx neat.is <verb>` below becomes `neat <verb>` this way. ## A more in-depth explanation: At the center of NEAT is **one live graph** of your system, fused from two streams into a single model you can query many ways: - **Static analysis** — tree-sitter over your source, `package.json`, and yaml / env config. Eleven languages parse to symbol grain: JavaScript, TypeScript, Python, Go, Ruby, PHP, C#, Java, Kotlin, Rust and C++. Routes and database calls are recognised in most of them; runtime-to-code fusion covers JavaScript, TypeScript and Python; outbound HTTP calls between services are read from JavaScript and TypeScript only, so other languages rely on runtime telemetry for cross-service edges. 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. Both 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. **The file is the primary unit.** A relationship in the graph runs from a file — `src/services/billing.ts ──CALLS──▶ api.stripe.com` — 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. Every edge carries a `provenance` tag so a consumer knows exactly how much weight a claim deserves: - `EXTRACTED` from source. No clock decay. - `OBSERVED` from a span. Carries `lastObserved` and `callCount`. - `INFERRED` by the trace stitcher where OTel coverage has gaps. Confidence is capped. - `STALE` because runtime stopped speaking. Preserves the original `lastObserved`. The graph is exposed to AI agents through twenty-four MCP tools. Fourteen read the graph — `ask`, `get_root_cause`, `get_blast_radius`, `get_dependencies`, `get_observed_dependencies`, `get_incident_history`, `get_incident_card`, `get_divergences`, `get_graph_diff`, `get_recent_stale_edges`, `check_policies`, `semantic_search`, `expand`, `relate` — six (`neat extend`) let an agent close instrumentation gaps for libraries the bundled OTel set doesn't cover, driven by a versioned [instrumentation registry](./docs/installer-scope.md), and four connect a hosted project to a provider. ## CLI The same `neat` binary handles every verb. After a global install (`npm i -g neat.is`) or via `npx neat.is`: ``` neat <path> orchestrator: extract, instrument, spawn daemon, open dashboard neat init <path> extract only; patch-by-default, --apply to write neat watch <path> keep the graph live as files change neat deploy emit deployment artifacts for a hosted target neat sync --to <url> push the local EXTRACTED snapshot to a remote daemon (v0.3.9) neat divergences where your code and your production traffic disagree neat root-cause <id> walk inbound edges to find what broke first neat blast-radius <id> BFS outbound; what would break if this node dies neat dependencies <id> transitive outbound dependencies neat incidents recent error events neat policies current policy violations neat search <query> semantic match on node names and ids ``` Every query verb honors `--json` and `--project <name>`. Exit codes branch on success (0), server error (1), misuse (2), and daemon unreachable (3). ## One example: what a divergence looks like A 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` reports where declared intent and observed behavior part ways: ``` [missing-extracted] src/services/prices.ts ──CALLS──▶ folio-api.example.com confidence 0.87 Production observed this call, but static analysis never surfaced the edge. → dynamic dispatch or a coverage gap. The code reaches a host it doesn't visibly name. [missing-observed] src/db/client.ts ──CONNECTS_TO──▶ postgres:primary confidence 0.85 Code declares this connection, but no production traffic has exercised it. → dead path, feature flag, or an unshipped branch. The declared dependency is idle. ``` Two 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. ## Policies: rules over the graph Divergence reports what *is*. Policies let you assert what *should be*. A `policy.json` in your project declares architectural rules as assertions over the same graph — for example, "only `service:billing` and `service:orders` may connect to `postgres:primary`," or "no file may call `legacy-api.internal`." Because the rules run against the live graph, they evaluate against both what your code declares and what production actually does. NEAT 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: - **`neat policies`** lists what's currently violating, scoped to a node with `--node`, or dry-run a change with `--hypothetical-action`. - **`check_policies`** 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. A `block` action gates promotion of a `FrontierNode` (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. ## Run NEAT on a server The container image at `ghcr.io/neat-technologies/neat:latest` boots `neatd start` and exposes REST on `:8080`, OTLP on `:4318`, and the web UI on `:6328`. Generate a token, run the image, point your OTel SDKs at it: ```bash NEAT_AUTH_TOKEN=$(openssl rand -hex 32) docker run -d --name neat \ -e NEAT_AUTH_TOKEN="$NEAT_AUTH_TOKEN" \ -p 8080:8080 -p 4318:4318 -p 6328:6328 \ -v /var/lib/neat:/neat-out \ ghcr.io/neat-technologies/neat:latest ``` `NEAT_AUTH_TOKEN` is 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>`; OTel exporters send the same header. Rotate the OTLP token independently with `NEAT_OTEL_TOKEN`. Easier path: `neat deploy` generates the token, writes a `docker-compose.neat.yml`, and prints the env block your application's deploy platform needs: ``` OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-host>:4318 OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<generated-token> ``` ## Behind a reverse proxy When TLS termination and authentication already live in a proxy upstream, set `NEAT_AUTH_PROXY=true` so the daemon skips the request-side bearer check. The bind-authority gate still refuses public binds without `NEAT_AUTH_TOKEN`, so set both: ```caddyfile neat.example.com { reverse_proxy localhost:8080 { header_up Authorization "Bearer {env.NEAT_AUTH_TOKEN}" } reverse_proxy /events localhost:8080 @otlp path /v1/traces reverse_proxy @otlp localhost:4318 { header_up Authorization "Bearer {env.NEAT_AUTH_TOKEN}" } } ``` Then `docker run … -e NEAT_AUTH_TOKEN=… -e NEAT_AUTH_PROXY=true …` and let Caddy gate the public surface. ## Wire NEAT into your agent NEAT's MCP server is listed in the official [MCP Registry](https://github.com/modelcontextprotocol/registry) as `io.github.neat-technologies/neat`, so registry-aware editors can install it in one click: [](https://cursor.com/en/install-mcp?name=neat&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBuZWF0LmlzL21jcCJdfQ%3D%3D) [](https://insiders.vscode.dev/redirect/mcp/install?name=neat&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40neat.is%2Fmcp%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=neat&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40neat.is%2Fmcp%22%5D%7D&quality=insiders) Each button wires the `@neat.is/mcp` server via `npx -y @neat.is/mcp` and points it at your local daemon; set `NEAT_CORE_URL` to target a non-default one. For Claude Code: ```bash claude mcp add neat -- neat-mcp ``` Or edit `~/.claude/settings.json` by hand: ```json { "mcpServers": { "neat": { "command": "neat-mcp", "env": { "NEAT_CORE_URL": "http://localhost:8080" } } } } ``` The `neat-mcp` binary above assumes a global install. Without one, run `neat skill --apply` instead — it writes the same `mcpServers.neat` entry using `npx -y @neat.is/mcp` so the server resolves without a global binary. Either form reads `NEAT_CORE_URL` for the daemon URL; set it to point the agent at a non-default daemon. In 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. ### Reach for the graph before grepping ```bash neat hooks --apply ``` This installs two nudges so your agent queries the graph before it falls back to raw text search: - **A Claude Code search-nudge hook** — a `PreToolUse` hook that, when the agent reaches for `Grep`/`Glob` or a Bash `grep`/`rg`/`find`, injects a note pointing it at `semantic_search`, `get_dependencies`, and `get_divergences` first. It is a gentle, non-blocking nudge: the search still runs. It merges into `~/.claude/settings.json` without touching your other hooks, and re-running is idempotent. - **Agent-agnostic graph-first guidance** — a markdown block (`GRAPH_FIRST.md`, also written to `~/.neat/neat-graph-first.md`) to paste into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`, so agents on any harness get the same steer. The hook is specific to Claude Code; other harnesses (Codex, Gemini, Cursor) rely on the guidance block instead. `neat hooks --print-hook`, `--print-guide`, and `--print-settings` show each piece without installing. ### The Claude Code plugin — the one-install path The `neat skill` and `neat hooks` commands above are the à-la-carte way to wire NEAT in. On Claude Code you can get all of it — the MCP graph tools, the graph-first search-nudge hook, and the skill — in one install, as a plugin: ```bash claude plugin marketplace add NEAT-Technologies/Neat claude plugin install neat@neat ``` The plugin lives in this repo under [`plugin/`](./plugin) and is installed straight from GitHub — nothing extra to publish. It bundles exactly the same MCP server config and search-nudge hook the à-la-carte commands write, so both paths behave identically; pick whichever you prefer. Set `NEAT_CORE_URL` (default `http://localhost:8080`) to point the bundled MCP server at a non-default daemon. ## Repository layout ``` packages/ types/ shared Zod schemas: node, edge, event, result types core/ graph engine, tree-sitter extraction, OTel ingest, REST API, neat CLI mcp/ stdio MCP server exposing the twenty-four tools to AI agents web/ Next.js dashboard claude-skill/ Claude Code skill metadata neat.is/ umbrella package plugin/ Claude Code plugin — bundles the MCP server, hook, and skill (repo-hosted) ``` ## Documentation - [`docs/guide/`](./docs/guide/README.md): the user guide — getting started, core concepts, querying, AI agents, and troubleshooting. Start here. - [`PROVENANCE.md`](./PROVENANCE.md): the four edge states and how confidence travels along a path. - [`CLAUDE.md`](./CLAUDE.md): guide for agents and contributors working in this repo. - [`docs/architecture.md`](./docs/architecture.md): package boundaries and data flow. - [`docs/api-reference.md`](./docs/api-reference.md): REST endpoints and MCP tool signatures. - [`docs/runbook.md`](./docs/runbook.md): day-to-day commands and recovery recipes. - [`docs/contracts.md`](./docs/contracts.md): the binding rules every PR must hold to. - [`CONTRIBUTING.md`](./CONTRIBUTING.md): branch convention, PR shape, dev setup. - [`SECURITY.md`](./SECURITY.md): how to report vulnerabilities. ## Contributing PRs welcome. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first for the branch convention, PR shape, and the contracts framework that gates every change. ## License Apache 2.0. See [`LICENSE`](./LICENSE).