Local-first · metadata-only · open MCP

Make your AI agent
understand your codebase.

Zunex scans your project and extracts its real architecture, entity relationships and business rules — so Claude Code, Codex and Copilot code with facts, not guesses from individual files.

Get started GitHub
~/your-project
$ zunex sync
Synced 1,524 artifacts  ·  Entities 96 · Services 140 · Rules 612
$ zunex ask "how many pending orders can a user have at once?"
— grounded in MentorApplication, OrderService, and a Behavior rule from the tests —
A user may have at most one PENDING order: enforced by the guard clause
in OrderService.placeOrder and asserted by OrderServiceTest. Order has-many
OrderItem (1..N); status moves PENDING → PAID → SHIPPED.
$ claude  # the agent now calls zunex_impact / zunex_rules before editing
Sample project

Try the dashboard — interactive, right here

Your codebase, as a knowledge graph

This is the real dashboard running on a sample project — drag nodes, hover, switch to the ER view. When you run zunex serve locally it shows your code, fully offline.

localhost:5173

Kinds

—
artifacts
—
dependencies
—
rules extracted
—
modules
Get started

Questions & terms

New here? Start with this

The common questions, and plain-English meanings for the jargon below.

Frequently asked

Is my source code sent anywhere?
No, not by default. Zunex works on metadata only — names, shapes, relationships and rules, never your method bodies. Run the AI on a local model (Ollama) and nothing leaves your machine at all. Source is sent to a cloud model only if you explicitly turn on Read source with a cloud provider, and only after a red warning.
Do I have to change my code or add annotations?
No. Zunex reads your existing code as-is. Point it at a folder and run zunex sync — no build, no special comments, no setup in your project.
Which languages does it support?
C#, Java/Spring, Node.js/Express, NestJS and Laravel out of the box — and they work together in one polyglot repo. New languages can be added as plugins without recompiling Zunex.
Do I need a database or to build the project?
No. Everything — including the ER/database diagram — is built by reading the source statically. No DB connection, no compilation, no running app.
Is it free? Do I need an API key?
The tool itself is free and runs locally. Ask AI on Ollama needs no key and no account. Gemini or GPT are optional — you bring your own key, stored only in your browser.
Can't the AI just read the code itself?
For a small project, largely yes — Zunex isn't magic the model lacks. The point is what happens as your codebase grows and the agent works in it repeatedly: it only reads a subset of files within its context window, infers the rest, and re-derives that each session. Zunex gives it a complete map instead of a sample, deterministic impact ("what breaks if I change this?" is a graph traversal, so it can't miss a dependent), and one cached source of truth — instead of re-reading dozens of files (tokens, time) and reaching different conclusions each time.
But why won't it grasp the business logic on its own?
Because business logic isn't in one place — it's scattered across validation rules, guard-clause exceptions, status-transition code, entity relationships and even test assertions. An agent only catches all of it if it happens to read all of it. Zunex extracts and aggregates it into one explicit list up front, across the whole project, read from the code itself — so it's complete and doesn't drift the way written docs do. Your requirements/ docs are folded in too.

Glossary

MCPModel Context Protocol — a standard way for AI agents (Claude Code, Codex…) to call external tools. Zunex exposes your codebase to the agent through it.
ArtifactOne unit Zunex tracks — a controller, service, entity, DTO, enum, etc.
Knowledge graphAll artifacts plus the relationships between them, as a graph you can navigate.
Impact / blast radiusEverything that depends on the thing you're about to change — what could break.
ER diagramEntity-Relationship diagram: your entities as tables with columns, linked by their relationships.
MetadataThe shape of your code — names, fields, relationships, rules — not the actual implementation.
Semantic search / embeddingsFinding the right code by meaning, so a question matches even when it shares no keywords.
SyncScanning the project to (re)build its metadata — run it once, or let a git hook keep it fresh.

Why Zunex

A knowledge layer over your code

Static analysis turns your project into a queryable knowledge graph — structure, relationships and rules — that any AI agent can consult on demand.

Knowledge graph

Every class, service, entity and dependency mapped — coloured by kind, navigable, with blast-radius impact analysis.

Database / ER view

Entities become tables with full columns and types; foreign-key relationships drawn with cardinality (1..1 / 1..N). No DB connection needed — and one click exports to Mermaid for your README or PR.

Ask the project

Natural-language Q&A grounded in metadata. Optional read source for deep questions, plus a feature-slice retriever and a search that matches rules and column names — not just type names.

MCP server

Exposes the graph as 9 tools to Claude Code, Codex and Copilot — including a git-diff blast-radius check. Generate a CLAUDE.md / AGENTS.md so the agent consults Zunex before editing.

Semantic search

Optional local embedding index (Ollama) so ask finds the right context by meaning, even when the question shares no keywords.

Your docs, folded in

Drop business docs in requirements/ — or anywhere as .md/.pdf/.docx/.xlsx/.pptx — and answers cite them alongside the code.

Tested behaviour

Test names and assertions become Behavior rules — the edge cases your suite guarantees, surfaced as business knowledge.

Impact analysis

Before any change, see exactly which artifacts depend on what you're about to touch — the blast radius, ranked by depth.

Private by design

Metadata-only and local-first. Run entirely on Ollama and nothing leaves your machine — or pick a cloud model, with clear warnings before any source is sent.

What it knows

Business meaning, extracted from code

Beyond structure, Zunex lifts the rules that usually live only in developers' heads — across C#, Java/Spring, Node, NestJS and Laravel.

Relationships has-many / has-one cardinality Enums & states valid domain values State machines Pending → Paid → Shipped Invariants guard-clause exceptions Authorization who may call what DB constraints unique / required / length Domain events publish / subscribe Tested behaviour edge cases from tests Entity columns name : type Your docs requirements/, .md/.pdf/.docx

How it works

Four steps to a grounded agent

Scan

zunex sync parses your code and builds .zunex/metadata.json — no build, no DB.

Explore

zunex serve opens a dashboard: graph, ER diagram, rules and chat.

Connect

Register the MCP server & write the instruction file so your agent uses Zunex.

Code

The agent checks impact, rules and relationships before changing anything.

Get started

Up and running in a minute

.NET 10 · cross-platform · packaged as a dotnet tool. Hover any block to copy it.

1

Clone & install once per machine

git clone https://github.com/iamdwn/zunex
cd zunex
./install.ps1

Installs zunex (CLI) and zunex-mcp (MCP server) as global dotnet tools. Re-run after pulling updates.

2

Scan your project & explore

zunex sync  --path ./my-app
zunex serve --path ./my-app   # http://localhost:5173

Builds .zunex/metadata.json — no build step, no DB connection — and opens the dashboard: graph, ER diagram, rules and Ask AI.

3

Connect your agent

claude mcp add zunex -- zunex-mcp --root ./my-app
zunex agent claude            # writes CLAUDE.md

Using Codex or Copilot instead? Full per-agent steps are in Agent setup below.

4

Optional — semantic retrieval, fully local

ollama pull nomic-embed-text
zunex embed --path ./my-app

ask then finds the right context by meaning, even when your question shares no keywords with the code.

Uninstall — if you stop using Zunex 
claude mcp remove zunex                  # if registered with Claude Code
zunex hook uninstall --path ./my-app     # if auto-sync git hooks were installed
dotnet tool uninstall --global Zunex.Cli
dotnet tool uninstall --global Zunex.Mcp

Close any running agent first — it holds zunex-mcp open. For Codex/Copilot, also remove the zunex entry from ~/.codex/config.toml or .vscode/mcp.json. Optionally delete the instructions file (CLAUDE.md / AGENTS.md) and the .zunex/ folder from your projects.

View on GitHub

Agent setup

Plug Zunex into your coding agent

Zunex ships an MCP server. Register it once per project, generate an instructions file, and the agent consults the knowledge graph before every edit. Replace ./my-app with your project path.

1

Register the MCP server

claude mcp add zunex -- zunex-mcp --root ./my-app

Scoped to this project — Claude Code launches zunex-mcp automatically.

2

Write the instructions file

zunex agent claude

Creates CLAUDE.md telling the agent to consult Zunex (architecture, rules, impact, relationships) before editing.

3

Verify

/mcp

Inside a session, zunex appears with its 9 tools. Try: "use zunex to show the impact of changing OrderService".

1

Add to ~/.codex/config.toml

[mcp_servers.zunex]
command = "zunex-mcp"
args = ["--root", "./my-app"]

Codex loads MCP servers from this file — restart Codex after editing.

2

Write the instructions file

zunex agent codex

Creates AGENTS.md so Codex knows when to call the zunex tools.

3

Verify

Ask Codex to list its available tools — the zunex tools should appear. Then prompt e.g. "use zunex to explain the orders module".

1

Create .vscode/mcp.json in the project

{
  "servers": {
    "zunex": {
      "command": "zunex-mcp",
      "args": ["--root", "./my-app"]
    }
  }
}

VS Code / Copilot agent mode reads MCP servers from this file.

2

Write the instructions file

zunex agent copilot

Creates .github/copilot-instructions.md.

3

Verify

Reload the window, open Copilot agent mode and confirm the zunex tools load — then prompt against the project.

1

Generic MCP config Cursor · Windsurf · Cline · Antigravity

{
  "mcpServers": {
    "zunex": {
      "command": "zunex-mcp",
      "args": ["--root", "./my-app"]
    }
  }
}

Most MCP-compatible agents accept this shape — paste it into the agent's MCP config.

2

Or run the server directly (stdio)

zunex-mcp --root ./my-app

Any MCP client can launch this command.

↻

Keep metadata fresh optional · works with any agent

zunex hook install

Installs git hooks so zunex sync runs automatically on every commit / merge / checkout — your agent always sees up-to-date architecture without you re-syncing by hand. Remove any time with zunex hook uninstall.

zunex_overview zunex_search zunex_feature zunex_impact zunex_impact_diff zunex_rules zunex_dependencies zunex_ask zunex_sync

Ask AI setup

Pick your model — local or cloud

Ask AI answers questions about your project, grounded in the knowledge graph. Ollama runs fully local and is the default; Gemini and GPT plug in with an API key.

Ollama

Local · default
  1. Install from ollama.com or with the commands below.
  2. Pull a chat model — done, no account, no key, no cost.
  3. Nothing leaves your machine.
# Windows  winget install Ollama.Ollama
# macOS    brew install ollama
# Linux    curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2

Gemini

Cloud · free tier
  1. Get a free key at aistudio.google.com/app/apikey
  2. In the dashboard open Ask AI and pick Gemini — a popup asks for the key.
  3. Change it any time via the gear button next to the provider.
  4. The key lives only in your browser — never on disk, never in git.

GPT (OpenAI)

Cloud · paid
  1. Create a key at platform.openai.com/api-keys
  2. In the dashboard open Ask AI and pick GPT — paste the key in the popup.
  3. Change it any time via the gear button next to the provider.
  4. The key lives only in your browser — never on disk, never in git.
Danger zone — read source. By default every provider sees metadata only. Enabling read source lets the model read method bodies for deeper answers; with a cloud provider that means your code is sent to Google or OpenAI. The dashboard shows an explicit red warning before you turn it on — with Ollama it stays on your machine.

Privacy

Your source never leaves —
unless you say so

Zunex sends metadata only by default: names, shapes, relationships and rules — never method bodies. Run on a local model and nothing leaves the machine at all.

Metadata-only context — no implementation bodies
Local-first with Ollama — zero exfiltration
Explicit warnings before any source goes to a cloud provider
API keys stay in your browser, never committed to git

Works with

Coding agents — consume Zunex via MCP

Claude Code Codex GitHub Copilot Cursor Windsurf Cline

Ask AI models — answer questions over the metadata

Ollama Gemini GPT