Pmad.CSharpNav 0.1.3

dotnet tool install --global Pmad.CSharpNav --version 0.1.3
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Pmad.CSharpNav --version 0.1.3
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Pmad.CSharpNav&version=0.1.3
                    
nuke :add-package Pmad.CSharpNav --version 0.1.3
                    

Pmad.CSharpNav (csnav)

A high-performance, machine-oriented C# code navigation engine designed for AI coding agents and developers.

csnav turns complex Roslyn workspace analysis into fast, token-efficient, and structured navigation queries. It operates as a lightweight client-daemon architecture: queries are answered in milliseconds by a warm in-memory Roslyn workspace daemon that automatically updates as files change on disk.


Key Features

  • Blazing Fast Navigation via Daemon Architecture: Auto-spawns a background HTTP daemon per solution on demand with loopback token security and automatic idle shutdown.
  • Incremental Roslyn Workspace Sync: Tracks file system changes via debounced watchers for .cs, .razor, and .cshtml files and provides instant manual synchronization for uncommitted buffer changes.
  • First-Class Razor & CSHTML Support: Full navigation support across Blazor components (.razor) and ASP.NET Core views (.cshtml). Using Roslyn source generators and mapped line spans (#line), definitions, implementations, and references map directly back to original .razor / .cshtml files with real disk code snippet extraction.
  • Go To Definition: Quickly navigate to where any symbol is declared in source code (C# or Razor/CSHTML) or inspect its external metadata assembly and documentation comment ID.
  • Go To Implementation: Find all concrete implementations, overrides, and derived classes/interfaces for any interface, class, or member (including @implements in Blazor components).
  • Reference Finding: Resolves calls, implementations, overrides, reads/writes across C# and Razor files with snippet extraction and test exclusion.
  • Fast Public API Search: Search declarations and external dependencies (NuGet/BCL) with wildcard patterns and MVID-keyed disk caching.
  • Deep Member Exploration: Inspect type signatures, inheritance, interfaces, constructors, methods, properties, and doc comments with partial class support.
  • External Library Decompiler: Built on ICSharpCode.Decompiler (ILSpy) to decompile external types and methods, automatically resolving reference assemblies (Microsoft.NETCore.App.Ref) to runtime implementation assemblies.
  • Agent-Friendly Output Formats: Choose between concise human text, clean markdown, or dense token-efficient json.

Solution Structure & Clean Architecture

The solution uses the XML-based .slnx format (PmadCSharpNav.slnx) and strictly adheres to Clean Architecture:

├── docs/
│   └── ARCHITECTURE.md                  # Comprehensive architectural specification
├── src/
│   ├── Pmad.CSharpNav.Domain/           # Zero dependencies: Core models & domain primitives
│   ├── Pmad.CSharpNav.Contracts/        # Shared DTOs, discovery info, and JSON serializer
│   ├── Pmad.CSharpNav.Application/      # Ports (interfaces) & use case query handlers
│   ├── Pmad.CSharpNav.Infrastructure/   # Roslyn workspace, file watcher, and ILSpy adapters
│   ├── Pmad.CSharpNav.Server/           # Minimal API daemon with bearer security & idle timer
│   └── Pmad.CSharpNav.Cli/              # System.CommandLine client depending ONLY on Contracts
└── tests/
    ├── Pmad.CSharpNav.Domain.Tests/
    ├── Pmad.CSharpNav.Application.Tests/
    ├── Pmad.CSharpNav.Infrastructure.Tests/
    └── Pmad.CSharpNav.IntegrationTests/ # End-to-end tests against real Roslyn solutions

Building and Testing

Prerequisites

Build the Solution

dotnet build

(All projects build with <TreatWarningsAsErrors>true</TreatWarningsAsErrors> under latest-recommended code analysis).

Run All Unit and Integration Tests

dotnet test

Installation

Local Installation (Testing without NuGet.org)

You can build, package, and install csnav locally as a global .NET tool using the PowerShell installation script:

# Build, pack, and install/update globally as 'csnav'
.\install-cli.ps1

# Force reinstall (wiping existing global tool & local package cache)
.\install-cli.ps1 -Force

# Install tool and also install the AI agent skill globally
.\install-cli.ps1 -InstallSkill

AI Agent Skill Integration

csnav includes a built-in skill for AI coding agents (compatible with Antigravity / Gemini / Copilot / Claude agent environments):

# Install skill in current repository (.agents/skills/csharp-nav/SKILL.md)
csnav skills install

# Install skill globally (~/.gemini/config/skills/ and ~/.agents/skills/)
csnav skills install --global

# Inspect the skill instructions directly in the console
csnav skills show

CLI Usage

Global Options

All commands support the following options:

  • -s, --solution <path>: Path to .slnx, .sln, .csproj, or directory (auto-detected by walking up parent directories if omitted).
  • -f, --framework <tfm>: Target framework filter (e.g. net10.0) when multi-targeting.
  • --format <format>: Output format: markdown (default), json, or text (configurable via CSNAV_FORMAT or CSNAV_DEFAULT_FORMAT environment variable).
  • --no-color: Disable ANSI color formatting (colors enabled for markdown and text by default unless output is redirected or NO_COLOR is set).

File paths returned in results (references, candidates) are automatically formatted relative to the current working directory (pwd) for compactness and readability.


Commands

1. definition (alias def, goto-def, find-def) — Go To Definition

Navigate directly to where a symbol or identifier is defined in source or metadata (supports .cs, .razor, and .cshtml files):

# Go to definition by symbol name
csnav definition --symbol "IOrderRepository.GetOrder"
# Or shorthand: csnav def --symbol "IOrderRepository.GetOrder"

# Go to definition at source location (1-indexed line and column, works in .cs, .razor, or .cshtml)
csnav definition --file src/Services/OrderService.cs --line 83 --column 34
csnav definition --file src/Web/Components/OrderCard.razor --line 15 --column 20

# Format as JSON or text
csnav definition --symbol "Order" --format json
2. implementations (alias impl, goto-impl, find-impl) — Go To Implementation

Find all concrete implementations, overrides, or derived types (including Blazor components using @implements):

# Find implementations of an interface (finds C# classes and Blazor .razor components)
csnav implementations --symbol "IOrderRepository"
# Or shorthand: csnav impl --symbol "IOrderRepository"

# Find implementations of an interface method or virtual member
csnav implementations --symbol "IOrderRepository.GetOrder"

# Find implementations by source location where member is called
csnav implementations --file src/Services/OrderService.cs --line 83 --column 34

# Exclude implementations residing in test projects
csnav implementations --symbol "IOrderRepository" --exclude-tests
3. references (alias refs) — Find References

Find all usages, call sites, implementations, or overrides of a symbol or source location (searches across .cs, .razor, and .cshtml files):

# By symbol name
csnav references --symbol "NavConstants"
# Or shorthand: csnav refs --symbol "NavConstants"

# Exclude references in test projects
csnav references --symbol "NavConstants" --exclude-tests

# By file location (1-indexed line and column, works for .cs, .razor, or .cshtml)
csnav references --file src/Pmad.CSharpNav.Contracts/NavConstants.cs --line 5 --column 25
csnav references --file src/Web/Components/OrderCard.razor --line 12 --column 18

# Format as JSON
csnav references --symbol "FindReferencesRequest" --format json
4. search (alias api, find) — Search Public API Signatures

Search public type and member signatures across source code and referenced libraries:

# Search by name pattern
csnav search "*Serializer"
# Or shorthand: csnav api "*Serializer"

# Search in solution scope only
csnav search "Nav*" --scope solution

# Filter search to a specific project
csnav search "*Command" --project Pmad.CSharpNav.Cli

# Search within XML doc comments
csnav search --doc "sha256" --format markdown
5. inspect (alias explore, type) — Type & Member Inspection

Inspect type hierarchy, base classes, interfaces, constructors, methods, and properties:

# Inspect type by fully qualified name
csnav inspect --type "Pmad.CSharpNav.Contracts.FindReferencesRequest"
# Or shorthand: csnav explore --type "Pmad.CSharpNav.Contracts.FindReferencesRequest"

# Exclude inherited members
csnav inspect --type "Pmad.CSharpNav.Contracts.FindReferencesRequest" --no-inherited

# By source file location
csnav inspect --file src/Pmad.CSharpNav.Domain/SymbolKind.cs --line 8 --column 12
6. decompile — Decompile External Assemblies

Decompile BCL or NuGet library types and members to C# source code:

# Decompile standard library type
csnav decompile --type "System.Uri"

# Decompile specific member
csnav decompile --type "System.Uri" --member "IsLoopback"
7. server — Manage Background Daemon

Control and inspect the background daemon for the active solution:

# Check daemon status
csnav server status

# Start daemon in background
csnav server start

# Reload workspace manually
csnav server reload

# Gracefully stop daemon
csnav server stop

Daemon Discovery & Lifecycle

When a query is issued:

  1. csnav computes a SHA-256 hash of the normalized solution path.
  2. It looks for a discovery file in %LOCALAPPDATA%/PmadCSharpNav/servers/<hash>.json.
  3. If no healthy daemon is found, the CLI acquires a per-solution lock (<hash>.lock), spawns Pmad.CSharpNav.Server in the background, and polls /api/health until ready.
  4. Each daemon generates a cryptographic bearer token saved with restricted permissions in the discovery file.
  5. Inactivity triggers automatic shutdown after 30 minutes of idle time.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.1.3 50 11/12/2026
0.1.2 91 11/11/2026
0.1.1 99 11/6/2026
0.1.0 111 10/29/2026
0.0.1 104 10/25/2026