Ucn

UCN - Universal Code Navigator

Auditable answers, with every match counted, unsure ones marked and blind spots named.

[npm] [tests] [license]

If you work with AI Agents, add UCN as a Skill or MCP tool. One tool gives the agent compact, source-linked answers to caller, impact, and test questions, with uncertainty labeled instead of guessed. The answer depends on the indexed source, not on who asks: a person at a terminal and an agent over MCP receive the same records for the same question.

Conceptual overview · Still image

Use the CLI directly, install the agent skill, or connect through MCP. One engine supplies all three:

  Terminal              AI Agents           Agent Skills       │                    │                    │      CLI                  MCP                 Skill       └────────────────────┼────────────────────┘                            │                     ┌──────┴──────┐                     │ UCN Engine  │                     │  commands   │                     │ tree-sitter │                     └─────────────┘

UCN uses tree-sitter abstract syntax trees (ASTs) for static code analysis, without compiling the project or starting a language server. The CLI runs on demand and reuses an incremental index; MCP keeps a process available for repeated queries. No project configuration is required, and the cache lives outside the repository.

Supports JavaScript, TypeScript, JSX/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline scripts.

Install

npm install -g ucn                    # Node.js 20+

In the shell

From a project directory:

ucn repoucn show handleRequest --linesucn source handleRequest --rawucn impact --staged --linesucn check --staged

repo maps the project. show --lines locates callers, source --raw retrieves the implementation, and impact and check inspect a staged change. When a name is ambiguous, find returns a file:line:name handle that subsequent commands accept.

--lines returns path:line:text records; --raw returns source code. Both fit an agent's existing scripts without parsing a human-readable report.

Text search remains useful for comments, configuration, strings, and code outside the supported languages. usages provides the literal-name inventory when the task needs every occurrence, including those that are not calls.

Code navigation and change analysis

show gives a symbol's summary, callers, and callees by default. Select --sections to request source, tests, or related context, or set an output budget to keep the answer focused. trace follows the call graph across files, down into callees or up through callers toward entry points. Unverified relationships remain visible, and the tree's accounting reports where exploration stopped.

impact connects a symbol or Git diff to its callers. tests follows indexed call and reference paths to identify statically linked tests, including links several hops away. plan previews a rename or signature change with source locations and review items; it does not edit files. Together these commands support code exploration, refactoring, and change review from a terminal or an AI agent.

What an answer establishes

For caller answers, UCN checks bindings, imports, receiver types, and ownership to distinguish calls to the selected definition from other uses of its name. Calls without enough evidence stay visible as unverified, with a reason. A matching method name alone does not establish which implementation runs; receiver and ownership evidence determine how the candidate is classified.

In ripgrep at 82313cf9, the selected file_name helper has four confirmed call sites and one unverified candidate. This animation accounts for all 29 matching lines, alongside import relationships and same-name definitions drawn from UCN's output.

[Captured ripgrep findings for file_name: 29 matching lines in six files, partitioned into 4 confirmed calls, 1 unverified candidate, 17 non-call lines, 7 other-target lines, and 0 unaccounted. The graph shows selected import relationships and the distinct definitions; motion is illustrative.]

Captured findings · Still image · Data

The ACCOUNT line reconciles the observed name occurrences: confirmed calls, unverified candidates, non-call occurrences, and matches attributed to another target. Each occurrence is counted in exactly one category, so the totals can be checked line by line rather than taken on trust. CONTRACT describes the scope of that accounting. Warnings identify source the index could not cover. These details survive text truncation for an agent's output budget; a budget too small to hold them withholds the answer and names the budget that would.

An empty result therefore means something specific about the inspected code. It cannot establish that reflection, generated code, runtime registration, or external consumers never reach a symbol. deadcode supplies candidates to investigate; deletion still needs corroboration. A refactor preview still needs the compiler and tests.

Accuracy and validation

Release gates compare UCN's answers with independent compilers and language servers on a ten-repository board of pinned production codebases. The local November 6, 2026 evaluation, using clangd 18.1.8 for C/C++ and .NET 10.0.403 for Roslyn, recorded these sampled caller results:

That evaluation scored 9,677 confirmed caller edges, all correct; 41 further edges were unscored. It reported zero missing in-scope oracle edges in both caller and callee answers. The separate value-reference sample scored 1,241 confirmed sites, all correct, with 4 unscored and zero missing in-scope sites. All 8,000 cross-command comparisons agreed. The default dead-code audit found zero false-dead results among 7 scored claims; 4 additional claims could not be pinned by the oracle and were unscored.

The samples are deterministic and stratified by reference activity. Confirmed precision applies to scored claims; recall counts in-scope oracle edges found in either the confirmed or unverified band. Unverified candidates, oracle abstentions, and unscored findings remain separate. These measurements do not establish complete runtime knowledge.

The scheduled board covers 43 pinned repositories: the ten above plus zod, express, hono, zustand, fastify, dayjs, rich, click, attrs, grpc-go, chi, cursive, itertools, rayon, rand, gson, jsoup, pino, tanstack-form, tqdm, zap, nom, guice, dapper, lz4, pugixml, stateless, luxon, arrow, more-itertools, rust-url, indicatif, and cachetools. A rotating fresh-repository arm checks 13 untuned codebases. Repositories used to repair a finding move to the pinned board and receive untuned replacements. A fresh failure fails the weekly run; independent checks still run and upload their reports.

The repository manifest records the full commits. The Publish workflow gates releases, and the Eval workflow runs the checks on schedule and on demand. Their run pages provide CI results and evaluation artifacts. Reproduce the checks locally with the oracle dependencies installed:

npm run verifynpm run trust:gate

Commands

--staged selects the Git-diff form of impact or check, without a symbol.

deps --cycles groups circular dependencies and, in JS/TS and Python, distinguishes eager imports from deferred or type-only edges. Enumeration limits are disclosed. repo reports source coverage as well as project structure; its HOT ranking counts confirmed production callers exactly (a refinement budget only binds on very large repositories, and is disclosed), and repo --sections=stats --hot ranks by all callers.

endpoints --bridge matches server routes and client requests recognized by its framework extractors. plan handles code relationships such as imports, overrides, and interface or trait methods when ownership is resolved; ambiguous relationships remain review items.

Run ucn --help for flags, or use the command reference.

Shell output

Records and code go to stdout; accounting and notes go to stderr. Unverified records carry a tab-separated reason. An empty --lines listing exits 1, an error exits 2, and a successful listing exits 0. --lines supports find, show, usages, search, and impact; show --lines lists callers by default. Use --json when the script needs structured fields or a tree result.

Listings are deterministic for a given source tree: a fresh build, a cache load, and an incremental rebuild return the same records in the same order. --lines listings have no default row cap. Explicit limits disclose what they omit, and a shell-mode character budget fails before writing partial output. source --raw extracts complete functions and classes unless an explicit line limit is requested; any resulting truncation is reported on stderr.

Ordinary text-mode command errors also exit 2. JSON keeps exit 0 for successful empty results and exit 1 for command errors (meta.ok: false plus error). An exception inside UCN is reported as Internal error: ... (JSON adds meta.internalError: true), never as an answer about the code. Target-less check exits 1 when TRUST is BLOCKED, 0 for other completed checks, and 2 if it could not run. check <symbol> exits 1 for a signature mismatch or an unverified call site.

Outside --lines, find, text search, deadcode, api, and repo --sections=files default to a maximum of 500 results. find text shows the top 5 in detail and counts the rest (JSON returns up to 500); --limit=N raises both. Use --limit=N to request more; usages lists every site, test files included, unless a limit or --exclude-tests is given. Broad find queries select candidates by approximate usage totals before calculating definition-pinned caller activity, and disclose that selection when limited.

Files named *.min.js, *.bundle.js, and *.map are reported as skipped sources and make completeness partial. --include-bundled (MCP include_bundled=true) indexes the JavaScript bundles while respecting user exclusions; it bypasses the shared cache. Source maps remain disclosed but unindexed.

AI setup

One tool, 18 commands, compact source-linked answers that keep their trust metadata even when truncated.

MCP

# Claude Codeclaude mcp add ucn -- npx -y ucn --mcp
# OpenAI Codex CLIcodex mcp add ucn -- npx -y ucn --mcp
# VS Code Copilotcode --add-mcp '{"name":"ucn","command":"npx","args":["-y","ucn","--mcp"]}'

{  "mcpServers": {    "ucn": {      "command": "npx",      "args": ["-y", "ucn", "--mcp"]    }  }}

{  "servers": {    "ucn": {      "type": "stdio",      "command": "npx",      "args": ["-y", "ucn", "--mcp"]    }  }}

Agent Skill (no server needed)

macOS / Linux:

# Claude Codemkdir -p ~/.claude/skillscp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/
# OpenAI Codex CLImkdir -p ~/.agents/skillscp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/

Windows PowerShell:

$npmRoot = npm root -gNew-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills"Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.claude\skills\"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills"Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.agents\skills\"

The skill teaches an agent how to orient, pin symbols, choose the smallest useful command, interpret the evidence tiers, and recover from incomplete answers. It's guidance over the same engine, not a second implementation.

Scope

UCN analyzes indexed source in one project. It does not execute the program or index installed dependencies such as node_modules and site-packages. repo --sections=health --deep reports source coverage and known analysis limits.

C and C++ can use compile_commands.json for include paths and header context, but UCN does not run the preprocessor or reproduce a compiler's build-specific view. C# source generators and external assemblies are also outside the index. HTML has regression coverage but no compiler/LSP repository oracle.

The CLI, MCP, and skill share the same resolution rules and evidence. Changing the transport does not change what the engine knows about the code.

MIT