hce

Hypergraph Code Explorer (HCE)

Turn any codebase into an interactive visual map — for humans and AI agents alike. HCE indexes your project's structure — what calls what, what inherits from what, how everything connects — and makes it queryable in milliseconds. For people, it generates a navigable graph with guided tours that explain the architecture. For AI coding agents (Claude Code, Cursor, Codex, Cowork), it replaces expensive file-by-file exploration with instant structural queries, saving significant time and tokens. You don't need to be a programmer to use it. Just point Claude at a codebase and say "visualize this."

Supports Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, and PHP — including projects that mix several languages.

Why Hypergraphs? Why AST?

Most tools that help AI understand code work by feeding source files into an LLM and asking it to figure out the structure. That burns tokens — lots of them. For a codebase like Django (1,163 files, 23,000+ symbols), an agent reading files one by one to trace how things connect could easily consume an entire context window and still miss the big picture.

HCE takes a fundamentally different approach. Instead of asking an LLM to read the code, it parses the code directly using tree-sitter, a fast multi-language AST (Abstract Syntax Tree) parser. Think of an AST as a precise structural blueprint of the code — it knows exactly where every function, class, call, and import is, without guessing. This parsing step is deterministic, costs zero LLM tokens, and finishes in seconds even for large codebases.

The parsed relationships get stored as a hypergraph — a graph where a single edge can connect more than two things at once. In a regular graph, you can only say "A calls B." In a hypergraph, one edge can capture "function A calls method B on class C with arguments D and E." This richer representation preserves context that pairwise graphs lose, and it's what makes queries like "what does this class call, two levels deep?" possible in milliseconds.

This project was inspired by HyperGraphReasoning, which demonstrated the power of hypergraphs for AI reasoning over scientific literature. The key difference: HyperGraphReasoning uses LLM calls to build its graphs from documents. HCE doesn't — it uses AST parsing, which means the graph construction itself is free. The LLM tokens you save on indexing are then available for the work that actually matters: understanding the architecture, writing code, and answering questions. The hypergraph becomes a tool the AI agent uses rather than a thing it builds.

Installation

HCE is distributed as a plugin — a bundle containing an MCP server (the engine that powers the graph queries) and a skill (instructions that teach Claude the index-and-query workflow). You install it once, and then Claude can use HCE in any project. On first run, the plugin auto-installs HCE's Python dependencies from GitHub — no manual setup.

Prerequisites

• Python 3.10+
• Git (for initial install from GitHub)
• If the repo is private: GitHub credentials configured (SSH key, gh auth login, or git credential helper)

Option A: Cowork (desktop app)

Someone with access to the plugin shares an hce.plugin file with you. To install it:

1. Open Cowork in the Claude desktop app
2. Go to Customize (left sidebar) → Personal plugins → click the + button
3. Select the hce.plugin file

The plugin appears under Personal plugins and is available in all future Cowork sessions. To use it, open any folder and tell Claude: "use HCE to explore this codebase."

To uninstall, go back to Customize → Personal plugins and remove it.

Option B: Claude Code (terminal)

HCE is distributed through this repo's built-in plugin marketplace.

Step 1: Add the marketplace (one-time)

Open Claude Code and run:

/plugin marketplace add denson/hypergraph_code_explorer

This registers the repo as a plugin source. You only need to do this once.

Step 2: Install the plugin

/plugin install hce@hce-tools

Claude Code will ask you to choose an installation scope:

• User scope — Installs globally for your user account. The plugin is available in every project you open. Best for personal use.
• Project scope — Installs for all collaborators on the current repository. Adds the plugin to the project's .claude/plugins.json, so anyone who clones the repo and trusts the project gets it automatically. Best for team projects where everyone should have HCE.
• Local scope — Installs only for you, only in the current repository. Doesn't affect other collaborators or other projects. Best for trying it out before committing.