UCN - Universal Code Navigator

See what code does before you touch it.

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.

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 repo
ucn show handleRequest --lines
ucn source handleRequest --raw
ucn impact --staged --lines
ucn 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 gathers a symbol's signature, source, callers, callees, and related context. Select the sections you need 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 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. 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.

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 September 6, 2026 evaluation recorded these sampled caller results:

That evaluation reported zero missing in-scope oracle edges in both caller and callee answers, and 8,000 cross-command comparisons with zero disagreements. The default dead-code audit found zero false-dead results among 13 scored claims; 13 additional claims could not be pinned by the oracle and were unscored. All ten repositories passed the performance budgets, with steady-state query p95 from 4.5 to 76.2 ms. Those timings exclude process startup and indexing; cold builds and cache loading are measured separately.

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 or identical performance on every machine.

The scheduled board covers 24 pinned repositories: the ten above plus zod, express, hono, zustand, fastify, rich, click, attrs, grpc-go, chi, cursive, itertools, gson, and jsoup. A rotating fresh-repository arm checks codebases outside that pinned board.

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 verify
npm run trust:gate

Commands

deps --cycles groups circular dependencies and distinguishes eager imports from deferred or type-only edges. Enumeration limits are disclosed. repo reports source coverage as well as project structure; its quick HOT ranking has a disclosed refinement budget, and repo --sections=stats --hot requests the exact ranking.