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
npx skills add organizzolini/codebase --skill codependix-navigate -a claude-codeWhat 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-areachesproject-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
authREADME.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-code2Manually: put the files in place
~/.claude/skills/codependix-navigate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/codependix-navigate/
1Skills CLI (Vercel)
npx skills add organizzolini/codebase --skill codependix-navigate -a codex2Manually: put the files in place
.agents/skills/codependix-navigate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add organizzolini/codebase --skill codependix-navigate -a cursor2Manually: put the files in place
.cursor/skills/codependix-navigate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install organizzolini/codebase projects/ic-suite/codependix/codependix-agents/skills/codependix-navigate2Manually: put the files in place
.github/skills/codependix-navigate/SKILL.md1Skills CLI (Vercel)
npx skills add organizzolini/codebase --skill codependix-navigate -a gemini-cli2Platform CLI
gemini skills install https://github.com/organizzolini/codebase --path projects/ic-suite/codependix/codependix-agents/skills/codependix-navigateManually: put the files in place
.devin/skills/codependix-navigate/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add organizzolini/codebase --skill codependix-navigate -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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