Overview of agentic-navigation-guide

Coding assistants often have trouble navigating large repositories (...and often burn a lot of time and tokens trying to locate files). One way to mitigate this difficulty is to include (partial) file listings inside the assistant's memory files, but these listings can be challenging to maintain over time. Worse, once they become outdated, their presence is more harmful than helpful.

This crate provides a CLI tool to assist with both:

• hand-authoring helpful navigation guides
• validating them against the current state of the filesystem

The validation can be done in a stand-alone way, and also has special support for being used as a "post-tool-use-hook" by Claude Code.

Navigation Guide Format

A "navigation guide" looks like this:

<agentic-navigation-guide ignore=true>
- src/
  - main.rs # Main entry point
  - lib.rs # Core logic goes here
  - types.rs # Core data types
  - errors.rs # errors and error messages
  - parser.rs # Parse guides from markdown
  - cli/
    - init.rs # init subcommand
    - dump.rs # dump subcommand
    - verify.rs # verify subcommand
- Cargo.toml
- README.md
</agentic-navigation-guide>

The main rules are:

• directories must end with a /
• nesting is indicated by indentation
• comments are optional, and must be separated from the path by a # character
• blank lines are not allowed within the guide block
• no special paths (., .., ./, ../)
• no ordering requirement is imposed
• placeholder entries (...) can be used to indicate unlisted items (see below)

Note that it's not an error to omit files and directories from the guide, but it is an error to include incorrect entries—the guide must be accurate*.

Placeholder Entries

You can use ... as a placeholder to indicate that there are additional files or directories not explicitly listed:

<agentic-navigation-guide ignore=true>
- src/
  - main.rs # Entry point
  - ... # Other source files
- docs/
  - README.md
  - api.md
  - ... # Additional documentation
</agentic-navigation-guide>

Rules for placeholders:

• Written as ... (three dots)
• May have an optional comment after it
• Cannot have child elements nested under them
• With a comment: Allowed in any directory, even if all items are listed or the directory is empty (useful for indicating future items)
• Without a comment: Must refer to at least one unlisted item in the parent directory (useful for omitting existing items)
• Cannot be adjacent to another ... entry (must have at least one non-placeholder between them)

The distinction between commented and uncommented placeholders enables two important use cases:

<agentic-navigation-guide ignore=true>
- src/
  - main.rs
  - ... # Represents lib.rs, utils.rs, etc. that exist but aren't listed
- plans/
  - phases/
    - phase-01-scaffolding.md # Phase 1 - COMPLETED
    - ... # Plans for future phases will appear here
</agentic-navigation-guide>

In this example:

• The first ... in src/ has a comment and there ARE unmentioned files (lib.rs, utils.rs) - represents omitted existing items
• The second ... in phases/ has a comment but phase-01-scaffolding.md is the ONLY file - represents future items that don't exist yet

Limited Choice Expansions

To keep related paths together while avoiding duplication, a single guide entry may include a choice list written with square brackets. For example:

- FooCoordinator[.h, .cpp] # Coordinates foo interactions

is equivalent to writing:

- FooCoordinator.h # Coordinates foo interactions
- FooCoordinator.cpp # Coordinates foo interactions

Each entry may contain at most one choice list and it expands into one concrete item for every option in the brackets. The same comment is attached to every expanded item.

Choice lists follow these rules:

• Whitespace inside the brackets is ignored unless it appears inside a quoted string.
• An empty string may be included by leaving an empty slot (e.g. [, .local]).
• Use a backslash to escape individual characters (e.g. \, for a literal comma, \ for a literal space, \[ for a literal [ character).
• Surround complex values with double quotes to preserve punctuation or embedded brackets. Within quotes, escape " to include a literal quote character.

Examples:

- FooCoordinator[.h, .cpp]        # expands to FooCoordinator.h and FooCoordinator.cpp
- Config[, .local].json           # expands to Config.json and Config.local.json
- src[/main, /lib].rs             # expands to src/main.rs and src/lib.rs

These expansions are intended for small sets of closely related alternatives—typically filename suffixes or prefixes—so that the guide stays concise without sacrificing clarity.

Ignoring Guides

You can mark a navigation guide to be ignored during verification by adding an ignore attribute to the opening tag:

<agentic-navigation-guide ignore=true>
- example/
  - file.rs
</agentic-navigation-guide>

This is particularly useful for:

• Documentation examples: Example guides in README files that should not be validated
• Invalid examples: Intentionally incorrect guides used to demonstrate error cases
• Template files: Guide templates that may not match the current filesystem

The tool accepts both ignore=true and ignore="true" formats. When a guide is ignored, the tool will:

• Skip all syntax and semantic validation
• Emit a warning that the guide was skipped
• Provide an additional note if the ignored guide is in a standalone AGENTIC_NAVIGATION_GUIDE.md file

Suggested Usage

To use this tool, I would suggest you do this:

• put your navigation guide in a file named AGENTIC_NAVIGATION_GUIDE.md in the root of your project
• use the @ syntax to include it in your CLAUDE.md file (etc.)

For a fuller example, you can review the CLAUDE.md file within this repository.

The advantage of this workflow is it keeps your navigation guide content physically-isolated from your CLAUDE.md (etc.)—helpful for editing and reviewing!—while still bringing the guide into context for each session.

Tool Overview

The tool provides the following commands:

• init: initialize a new navigation guide file with the current directory structure
• check: check that the contents of a hand-written navigation guide are syntactically correct (i.e. adhere to the format specified above)
• verify: verify that the contents of a hand-written navigation guide accurately reflect the current state of the file system
• dump: dump the current directory contents in the intended markdown format

If you're adding a navigation guide to your repository, I'd suggest:

• run agentic-navigation-guide init to generate a starting point
• hand-edit the file to add comments and omit extraneous details
• run agentic-navigation-guide verify to check for errors
• commit the file to your repository
• update your CLAUDE.md (etc.) to include the guide using the @ syntax

Post-Tool-Use Hook

To set it up as a post-tool-use-hook, you can update your ~/.claude/settings.json file to include the following:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "agentic-navigation-guide verify --post-tool-use-hook"
          }
        ]
      }
    ]
  }
}

GitHub Actions Integration

To use the tool as a CI check in GitHub Actions, add a job to your workflow:

verify-navigation-guide:
  name: Verify Navigation Guide
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions-rust-lang/setup-rust-toolchain@v1
    - name: Install agentic-navigation-guide
      run: cargo install agentic-navigation-guide
    - name: Verify installation
      run: agentic-navigation-guide --version
    - name: Verify navigation guide
      run: agentic-navigation-guide verify --github-actions-check

The --github-actions-check flag provides:

• Concise output on success ("✓ Navigation guide verified")
• Detailed error messages with file:line references
• Exit code 1 on failure (standard for CI checks)
• Visual indicators (emoji) for quick scanning

You can also set the execution mode via environment variable:

- name: Verify navigation guide
  run: agentic-navigation-guide verify
  env:
    AGENTIC_NAVIGATION_GUIDE_EXECUTION_MODE: github-actions

Recursive Verification for Monorepos

For monorepos or projects with nested navigation guides, you can use the --recursive flag to automatically discover and verify all guide files:

# Recursively verify all AGENTIC_NAVIGATION_GUIDE.md files
agentic-navigation-guide verify --recursive

# Use a custom guide name (e.g., GUIDE.md)
agentic-navigation-guide verify --recursive --guide-name GUIDE.md

# Exclude directories from the search
agentic-navigation-guide verify --recursive --exclude target --exclude node_modules

Example Monorepo Structure

AGENTIC_NAVIGATION_GUIDE.md         # Root-level guide
CLAUDE.md
/backend/
  AGENTIC_NAVIGATION_GUIDE.md       # Backend guide (verified relative to /backend/)
  CLAUDE.md
  /services/
    /sso/
      AGENTIC_NAVIGATION_GUIDE.md   # SSO service guide (verified relative to /backend/services/sso/)
      CLAUDE.md
    /taskrunner/
      AGENTIC_NAVIGATION_GUIDE.md   # Taskrunner guide (verified relative to /backend/services/taskrunner/)
      CLAUDE.md
/frontend/
  AGENTIC_NAVIGATION_GUIDE.md       # Frontend guide (verified relative to /frontend/)
  CLAUDE.md
  /consumer/
    AGENTIC_NAVIGATION_GUIDE.md     # Consumer app guide (verified relative to /frontend/consumer/)
    CLAUDE.md
  /internal/
    AGENTIC_NAVIGATION_GUIDE.md     # Internal app guide (verified relative to /frontend/internal/)
    CLAUDE.md

Each guide is verified relative to its parent directory, allowing you to maintain focused navigation guides for different parts of your codebase.

Recursive Verification Features

• Automatic Discovery: Finds all guide files matching the specified name throughout the directory tree
• Relative Verification: Each guide is verified against its parent directory as the root
• Custom Names: Support for uniform custom guide filenames (e.g., --guide-name GUIDE.md)
• Exclusion Patterns: Skip directories like target, node_modules, .git using glob patterns
• Aggregated Results: Shows summary of all verified guides with pass/fail counts
• Execution Modes: Works with all execution modes (default, post-tool-use, pre-commit-hook, GitHub Actions)

Future Roadmap

This is an early preview of the tool, so there are a few rough edges. Potential future steps:

• support for auto-installing the hook (e.g. auto-editing your settings to include it)
• support for auto-generating the hook (e.g. suggested prompts/commands to have your agent write the guide comments)
• support for nested guides (completed - use --recursive flag)
• inspecting the post-tool-use-hook json and skipping unnecessary work