Pmad.CSharpNav
0.1.1
See the version list below for details.
dotnet tool install --global Pmad.CSharpNav --version 0.1.1
dotnet new tool-manifest
dotnet tool install --local Pmad.CSharpNav --version 0.1.1
#tool dotnet:?package=Pmad.CSharpNav&version=0.1.1
nuke :add-package Pmad.CSharpNav --version 0.1.1
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.cshtmlfiles 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/.cshtmlfiles 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
@implementsin 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, cleanmarkdown, or dense token-efficientjson.
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, ortext(configurable viaCSNAV_FORMATorCSNAV_DEFAULT_FORMATenvironment variable).--no-color: Disable ANSI color formatting (colors enabled for markdown and text by default unless output is redirected orNO_COLORis 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:
csnavcomputes a SHA-256 hash of the normalized solution path.- It looks for a discovery file in
%LOCALAPPDATA%/PmadCSharpNav/servers/<hash>.json. - If no healthy daemon is found, the CLI acquires a per-solution lock (
<hash>.lock), spawnsPmad.CSharpNav.Serverin the background, and polls/api/healthuntil ready. - Each daemon generates a cryptographic bearer token saved with restricted permissions in the discovery file.
- Inactivity triggers automatic shutdown after 30 minutes of idle time.
| Product | Versions 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. |
This package has no dependencies.