GraphyDex

GraphyDex is a solution from AgentiQDex and it is a local codebase mapping tool for understanding software projects without loading every source file at once. It scans the important structure of a project, extracts files, packages, classes, functions, methods, imports, and dependencies, and generates an interactive HTML map.

The generated graph can be used in your prompt first instead of scanning the entire raw files. Helping you to reduce the token usage.

The generated JSON graph can also be used as a lightweight context index for AI coding assistants. An assistant can inspect the graph first, identify the files related to a task, and then read only the necessary source files.

AgentiqDex also includes an optional map-first MCP server. See docs/mcp-server.md for its tools, prompts, setup, and Cursor/Claude/Codex integration examples.

GraphyDex currently supports Java, JavaScript, TypeScript, TSX, HTML, and frontend project assets. For frontend projects it scans the root package.json and app.json, together with src, assets, and public.

Setup

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install AgentiqDex:

pip install -e .

Generate a map for an existing project:

graphydex /path/to/your-project

This creates two files in the current directory:

your-project-code-map.html
your-project-code-map.json

It also creates agent instructions inside the scanned project so AI coding agents use the compact JSON map before opening source files:

.agents/skills/agentiqdex-context/SKILL.md   # Codex
.claude/skills/agentiqdex-context/SKILL.md   # Claude Code
.cursor/rules/agentiqdex-context.mdc         # Cursor
.cursor/mcp.json                             # Cursor MCP connection
AGENTS.md                                    # Codex project instructions
CLAUDE.md                                    # Claude project instructions

These instructions tell the agent to read the map first, follow its file and dependency relationships, and then inspect only the relevant source files. They are updated safely on later runs without duplicating their instruction blocks. The map is a navigation index; agents still read source files when they need implementation details.

Open the visual map locally:

open your-project-code-map.html

To choose a custom HTML filename:

graphydex /path/to/your-project --output custom-map.html

When running directly from this source checkout:

PYTHONPATH=src python -m agentiqdex /path/to/your-project

For releases, the GitHub publishing workflow reads the package version from the Git tag. Push a tag such as v0.1.3 and the workflow builds and publishes version 0.1.3 automatically.