Skip to main content
skill CX Codex

codependix-navigate — Claude Code skill: query dependency graphs

codependix-navigate teaches the agent to answer dependency questions: how project A reaches C, what breaks if a file changes. Uses codependix path or graphs already committed to the repo.

MIT 364 installs updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add organizzolini/codebase --skill codependix-navigate -a claude-code
Open on GitHub

What codependix-navigate does

Ask the agent how two parts of a monorepo connect and this skill tells it which codependix command to run. It covers paths between Nx projects, between files, and between NestJS modules, plus the reverse question of who imports a given package.

Inside is written guidance: which flags to pass, and when reading beats running. Each package commits its own graphs into its README.md between <!-- codependix:start name="..." --> markers, while the root README.md carries the workspace-wide one, so a single-hop question can be settled from disk. A full run parses Nx projects, TypeScript ASTs and container registrations, which is why the skill lists narrowing switches such as --projects, --tags and --no-file-imports.

--config <path> is required on every call, because the tool searches for nothing and has no default. When two nodes are not connected, the command prints that and exits 0.

What it helps with

  • trace how one Nx project reaches another
  • check what breaks when a package's public API changes
  • list files importing a module you are about to move
  • see which NestJS modules the DI container wires together
  • read a committed graph instead of paying for a full CLI run

Example prompts for the agent

  • Show me how project-a reaches project-c, and narrow the run to that workspace.
  • What breaks if I change the public API of project-b?
  • Look at the import graph in the auth README.md — are there cycles before I refactor?

How to install codependix-navigate

1Skills CLI (Vercel)

npx skills add organizzolini/codebase --skill codependix-navigate -a claude-code

2Manually: put the files in place

~/.claude/skills/codependix-navigate/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codependix-navigate/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about codependix-navigate

How to install codependix-navigate in Claude Code?

Run npx skills add organizzolini/codebase --skill codependix-navigate -a claude-code. The skill file lands at ~/.claude/skills/codependix-navigate/SKILL.md.

What does codependix-navigate do?

It gives the agent a procedure for architecture and dependency questions, either by running codependix path or by reading graphs committed into package README.md files. Project, file and NestJS module relationships all fall inside it.

Do I have to run the CLI every time?

No. One-hop questions are answered by the committed diagrams, and codependix path is for multi-hop routes, cross-project reachability or checking unstaged changes.

Source text

SKILL.md · MIT
---
name: codependix-navigate
description: Answer dependency navigation and architecture questions using codependix CLI commands or committed graphs. Use when finding dependency paths between projects, files, or NestJS modules, tracing blast radius, determining what touches or imports a file or package, choosing narrowing flags to minimize run costs, or reading committed README diagrams across packages without running commands.
license: MIT
---

# Navigating a codebase with codependix

Codependix builds and queries dependency graphs across Nx workspaces, NestJS
containers, and file-level TypeScript and Python imports. When asking "how does X
reach Y?", "what breaks if I change Z?", or "what does this package depend
on?", use codependix commands to query relationships directly, or inspect
committed graphs already on disk.

## Command first: querying dependency paths

Reach for `codependix path` to trace directed dependency paths between two
nodes without parsing diagrams or grepping source files by hand. Every
invocation names the configuration with `--config <path>` — in this repository
`configuration/codependix.config.ts` — because nothing is searched for
and there is no default.

```bash
# How does project-a reach project-c?
codependix path project-a project-c --config configuration/codependix.config.ts

# How does one file import another?
codependix path src/modules/auth/auth.service.ts src/modules/users/user.entity.ts --config configuration/codependix.config.ts

# What NestJS modules connect two modules in a container?
codependix path AuthModule DatabaseModule --config configuration/codependix.config.ts
```

### Path query flags and narrowing

Running across a full workspace can be expensive because it parses Nx projects,
TypeScript ASTs, and container registrations across the entire monorepo. Use
narrowing flags to scope the run and minimize execution time:

| Flag | Purpose |
| ---- | ------- |
| `-f, --format <format>` | Output format: `markdown` (default), `json`, or `mermaid` |
| `--nx-projects` / `--no-nx-projects` | Toggle Nx workspace project dependency graph search |
| `--file-imports` / `--no-file-imports` | Toggle internal file-level import graph search |
| `--nestjs-modules` / `--no-nestjs-modules` | Toggle NestJS container module graph search |
| `--projects <names>` | Comma-separated project names or globs to search across |
| `-d, --directory <dir>` | Directory whose Nx workspace to read |
| `--include <globs>` / `--exclude <globs>` | Override configured project inclusion or exclusion globs |
| `--tags <tags>` | Comma-separated Nx project tags to filter by |
| `--config <path>` | **Required.** Path to the codependix configuration file; every example here passes it |

### Path results

- **Path found**: Prints the shortest directed path connecting `<from>` to
  `<to>` (for example `project-a → project-b → project-c`).
- **No path**: Reports `_No path connects "<from>" to "<to>"._` (or an empty
  list in JSON) and exits 0. A missing path is an answer, not an error.

## When to read a committed diagram instead of running the CLI

Running the CLI builds graph representations from source files. Before running
a command, check if the question is already answered by committed artifacts on
disk:

1. **Every package in the monorepo commits its own graphs.** Look in any
   project's `README.md` under the `## 🕸️ Codependix` section or between
   `<!-- codependix:start name="..." -->` markers.
2. **Immediate blast radius (1 hop):** The project's committed **Nx
   Neighborhood** diagram lists all immediate `dependencies` (what it reaches)
   and `dependents` (what breaks if its public API changes).
3. **Internal file structure:** The project's committed **File import graph**
   lists all file-to-file imports and isolated files within that project.
4. **Container structure:** The project's committed **NestJS module graph**
   lists wired container modules.
5. **Whole-workspace structure:** The repository root `README.md` carries the
   committed workspace graph.

**Cost rule of thumb:**

- **Read README diagrams or JSON** for single-hop dependencies, immediate blast
  radius, or local file layout (zero build cost, instant answer on disk).
- **Run `codependix path`** for multi-hop transitive paths, cross-project
  reachability, verifying unstaged changes, or generating machine-readable JSON.

## The four graph types and their questions

| Graph | Scope | Answers |
| ----- | ----- | ------- |
| **Nx Neighborhood** | Project | What one project reaches (dependencies) and who breaks if it changes (dependents) |
| **Workspace graph** | Workspace | High-level architectural layering and cross-package relationships |
| **NestJS module graph** | Container | What modules the DI container wires together at runtime |
| **File import graph** | Project files | File-to-file import relationships, cycles, and local refactoring fan-out |

## Interpreting graph artifacts

### Nx Neighborhood: blast radius

A Neighborhood covers **one hop in each direction** from the focal project
(highlighted in diagrams):

- **`dependents` is the blast radius** of a breaking change: every listed
  project must build against the new shape. For breaking changes spanning
  deeper layers, walk outward neighborhood by neighborhood or run
  `codependix path`.
- **`dependencies` is the allowed surface:** A project may only import what is
  declared here.
- Edges marked `implicit` are Nx workspace configuration dependencies rather
  than code imports.

### File import graph: refactoring and moves

Edges are strictly **between files inside the same project**:

- External packages and cross-project imports are excluded by design (they live
  in the Nx Neighborhood).
- **`isolatedFileNames` is a shortlist to investigate, not dead code.** An
  isolated file may be an entry point, an external export, or a configuration
  file.
- **Cycles are real:** An import cycle within a project produces runtime
  `undefined` bindings or initialization order bugs. Walk the cycle edges to
  locate where to decouple.
- Renaming a file? Edges pointing to the old relative path show the exact blast
  radius.

### NestJS module graph: DI container wiring

Built by evaluating container modules:

- **Global or ambient modules:** Modules imported by nearly all others (for
  example core logging or configuration) have individual edges omitted to
  reduce visual noise; they are listed under `ambientModuleNames` and drawn
  with rounded corners.
- **Dynamic wrapper modules:** Private internal host modules created by
  `forRoot` or dynamic providers are collapsed into the declaring module.
- A missing module was never registered in the container hierarchy, meaning
  its exported providers are unavailable.

## Confirming freshness before trusting committed graphs

A committed graph reflects the repository state at the last
`codependix map --write`. To check whether committed graphs are up to date:

```bash
# Check if any committed reports are stale without modifying files
codependix map --check reports --config configuration/codependix.config.ts

# Update all committed graphs across the workspace
codependix map --write --config configuration/codependix.config.ts
```

If committed graphs are stale with respect to recent local edits, either
re-run `codependix map --write` or use `codependix path` for real-time queries.

© organizzolini · MIT · organizzolini/codebase

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set13

The whole set →
conformetry-configure conformetry-configure configures conformetry generators and writes template folders. Helps when you need to define file generation rules, adjust input schemas, or fix paths in rendered output. CX Codex +1 671installs conformetry-validate conformetry-validate runs conformetry checks against generated files to spot missing declarations or comments. Helps agents fix structural differences without deleting working code. CX Codex +1 670installs codependix-configure codependix-configure guides creating and editing codependix.config.ts to export dependency graphs and enforce architecture boundaries. CX Codex +1 364installs codependix-export codependix-export — a skill for Claude Code that runs codependix dependency graph exports and boundary checks. Handles report verification, boundary violations, and artifact generation. CX Codex +1 364installs codometer-measure codometer-measure — a skill that tells the agent how to run codometer, route its reports and read the JSON back. CX Codex +1 363installs codependix-triage codependix-triage — a Claude Code skill to diagnose codependix build failures and architecture drift. Triggers on failing codependix-bound targets, boundary rule violations, or stale diagram exports. CX Codex +1 363installs codometer-configure The codometer-configure skill edits codometer.config.ts for Codometer, covering inputs, metric limits, exclusions, and report destinations. CX Codex +1 363installs codometer-triage codometer-triage handles a failing codometer --check run: tells a limit breach apart from a stale report or a run that could not finish, and points at what to fix. CX Codex +1 363installs

Project sponsors

Companies that keep this analytics open