neat

NEAT solves the AI coding context problem by constructing a live deterministic model of a codebase — static code and live runtime behavior fused into one graph — and exposing it to AI agents through MCP tools. It aims to reduce LLM hallucination, provide time-travelling error logs along graph nodes and edges for debugging, and enforce architectural rules via policies. ## Core concept At the center is one live graph of the system, fused from two streams: - **Static analysis** — tree-sitter over source (JavaScript, TypeScript, Python), `package.json`, and yaml/env config. Every source file becomes a node; imports become edges; calls to databases, queues, and external hosts are extracted from code. - **Runtime telemetry** — OpenTelemetry spans attributed back to the exact file and line that made the call. NEAT wires the instrumentation automatically. Both streams land on the same nodes, so the graph holds what code *declares* and what the system *does* side by side. The file is the primary unit — relationships run from a file (e.g., `src/services/billing.ts ──CALLS──▶ api.stripe.com`), keeping answers sharp and specific. Every edge carries a `provenance` tag: - `EXTRACTED` from source (no clock decay) - `OBSERVED` from a span (with `lastObserved` and `callCount`) - `INFERRED` by the trace stitcher where OTel coverage has gaps (confidence capped) - `STALE` because runtime stopped speaking (preserves original `lastObserved`) ## Getting started ```bash npx neat.is ``` Run from inside a project (or `npx neat.is <path>`). It discovers services, extracts the static graph, wires in OpenTelemetry, starts the daemon, and opens the dashboard — no config. Then run the app and watch live edges populate. > **Windows note:** use the `neat` command, not `npx neat.is`. npm generates a shim literally named `neat.is`, and Windows won't execute a `.is` file. Install once globally (`npm i -g neat.is`) and run `neat` (or `neat <path>`). Without a global install: `npx -p neat.is neat`. ## CLI verbs ``` 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 local EXTRACTED snapshot to a remote daemon neat divergences where code and 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: 0 success, 1 server error, 2 misuse, 3 daemon unreachable. ## Divergences A divergence is where declared intent and observed behavior part ways — the hardest question to answer any other way because it needs both streams at once. Example: ``` [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. [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. ``` ## Policies A `policy.json` in the project declares architectural rules as assertions over the graph — e.g., "only `service:billing` and `service:orders` may connect to `postgres:primary`," or "no file may call `legacy-api.internal`." NEAT evaluates every policy continuously as the graph changes. Violations surface via `neat policies` (CLI) and `check_policies` (MCP tool for agents). A `block` action gates promotion of newly seen external hosts (`FrontierNode`) so unsanctioned dependencies don't settle into the model. ## MCP tools Twenty-four MCP tools expose the graph to AI agents. 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`) close instrumentation gaps for libraries the bundled OTel set doesn't cover, driven by a versioned instrumentation registry. Four connect a hosted project to a provider. ## Server deployment Container image at `ghcr.io/neat-technologies/neat:latest` boots `neatd start` and exposes REST on `:8080`, OTLP on `:4318`, and web UI on `:6328`. `NEAT_AUTH_TOKEN` is required on every public interface; the daemon refuses non-loopback binds without it. `neat deploy` generates the token, writes `docker-compose.neat.yml`, and prints the env block for the application's deploy platform: ``` OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-host>:4318 OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <generated-token> ``` Reverse proxy support via `NEAT_AUTH_PROXY=true` when TLS termination and auth already live upstream. ## Agent integration NEAT's MCP server is listed in the official MCP Registry as `io.github.neat-technologies/neat`. One-click install buttons exist for Cursor and VS Code. For Claude Code: ```bash claude mcp add neat -- neat-mcp ``` Or edit `~/.claude/settings.json`: ```json { "mcpServers": { "neat": { "command": "neat-mcp", "env": { "NEAT_CORE_URL": "http://localhost:8080" } } } } ``` `neat hooks --apply` installs a Claude Code search-nudge hook (injects a note pointing agents at `semantic_search`, `get_dependencies`, `get_divergences` before raw grep) plus an agent-agnostic `GRAPH_FIRST.md` guidance block. A Claude Code plugin (`claude plugin marketplace add NEAT-Technologies/Neat` then `claude plugin install neat@neat`) bundles MCP tools, the hook, and the skill in one install. ## 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 web/ Next.js dashboard claude-skill/ Claude Code skill metadata neat.is/ umbrella package plugin/ Claude Code plugin (repo-hosted) ``` ## Documentation - `docs/guide/`: user guide — getting started, core concepts, querying, AI agents, troubleshooting - `PROVENANCE.md`: the four edge states and confidence travel - `CLAUDE.md`: guide for agents and contributors - `docs/architecture.md`: package boundaries and data flow - `docs/api-reference.md`: REST endpoints and MCP tool signatures - `docs/runbook.md`: day-to-day commands and recovery recipes - `docs/contracts.md`: binding rules every PR must hold to - `CONTRIBUTING.md`: branch convention, PR shape, dev setup - `SECURITY.md`: vulnerability reporting ## License Apache 2.0.