Codegraph turns source code into a dependency model you can query, draw as a
3D city, browse dependency by dependency, replay through its git history, and
have a language model explain bottom-up. It does this without building the
code: the extractors run on sources alone (no classpath, jars, etc.).
Five questions, five commands:
| Question | Command | What you get |
|---|
| What does this codebase look like? | codegraph serve → City tab | a 3D city: packages are districts, classes are buildings sized by real metrics, dependencies are arcs — click a building to open it in the navigator |
| What exactly depends on what? | codegraph serve → Navigate tab | a browsable tree with every incoming and outgoing dependency, the member that carries it, and the source line that proves it |
| How did it get this way? | codegraph scm / replay | churn, hotspots, ownership, co-change, and a city whose timeline scrubs the years |
| What does it mean? | codegraph explain | one plain-language explanation per method, class and package, written leaves-first so every summary rests on already-explained parts |
| What language does it speak? | codegraph vocabulary / serve → Vocabulary tab | the words of every name, split per language idiom and weighted by what carries them: a word cloud per package or class, drift against your glossary, one word across the city |
Plus the plumbing you need to trust the answers: validate for the model,
analyze for coupling and cycles, export for DOT, CSV, JSON and PlantUML.
Quick start
Codegraph is installed from one Homebrew tap. The app and the codegraph
command are one install; every language extractor is its own, so a user of
one language never downloads the runtimes of the others:
brew install --cask defsquare/tap/codegraph # Codegraph.app + the `codegraph` command (macOS)
brew install defsquare/tap/codegraph-java # then one line per language you extract
brew install defsquare/tap/codegraph-csharp
brew install defsquare/tap/codegraph-typescript
brew install defsquare/tap/codegraph-elixir
brew install defsquare/tap/codegraph-ruby
If a recent Homebrew answers Refusing to load formula … from untrusted tap,
run brew trust defsquare/tap once and retry. Nothing else is needed: the
Java extractor is a GraalVM native image, the C# one carries the .NET runtime
and the base class library, the Elixir one carries Erlang and Elixir, the Ruby
one is a single binary that needs no Ruby, and the TypeScript one is the codegraph-typescript npm package on Homebrew's Node
(npx codegraph-typescript runs it anywhere Node 22 is).
On Linux, Homebrew installs the extractors the same way; the codegraph
command is the codegraph-linux-x64 or -arm64 asset of the
latest release,
made executable and put on PATH. On Windows, the same release carries
codegraph-win-x64.exe, codegraph-java-win-x64.exe and
codegraph-csharp-win-x64.exe. What a release holds and how the tap is
rendered from it is in docs/distribution.md.
To work on codegraph itself, run it from a clone instead — Node 22+, pnpm
(corepack enable pnpm), then the toolchain of each extractor you build:
git clone --recurse-submodules https://github.com/defsquare/codegraph.git && cd codegraph
pnpm install && pnpm -r build # the CLI (bin/codegraph) and the TypeScript extractor
(cd extractors/java && ./mvnw -B package) # Java: a JDK 17+; the wrapper, no local Maven needed
./build.sh --csharp # C#: the .NET 10 SDK
./build.sh --elixir # Elixir: Erlang/OTP 27 + Elixir
./build.sh --ruby # Ruby: Rust 1.94+ and libclang — to build; no Ruby, ever
ln -s "$PWD/bin/codegraph" ~/.local/bin/codegraph # optional, works from a symlink
Already cloned without --recurse-submodules? Run
git submodule update --init --recursive first: the website's theme lives in
website/themes/hextra as a submodule, and with it missing Hugo aborts
pnpm -r build with unknown output format "llms" for kind "home".
Now point it at some Java. Any tree of .java files works; it does not have
to build, and no JDK is needed.
# 1. extract: sources in, one model file out (no compilation)
codegraph-java --src ~/src/gson/gson/src/main/java --out gson.jsonl
# 2. is the model sound?
codegraph validate gson.jsonl
# 3. look at it: one page, the navigator with the 3D city as a tab
codegraph serve gson.jsonl --host 127.0.0.1 # http://localhost:4177
On google/gson (about 3,600 entities) extraction takes seconds and every
report runs well under a second. On apache/fineract (a 127 MB model) each
command completes in about twelve seconds.
--host 127.0.0.1 keeps the page on your machine. Without it the server
binds every interface, which is convenient on a LAN and wrong for a sensitive
codebase.
TypeScript: the extractor is the compiler used as a library, and it reads a
tree that neither builds nor has node_modules. Node 22 is its only
requirement, so npx is enough where Homebrew is not.
codegraph-typescript --src ~/src/some-app/src --out app.jsonl
npx codegraph-typescript --src packages --src extractors/typescript --out codegraph.jsonl # codegraph on itself
Elixir: the extractor is the compiler's parser used as a library, and it
reads a tree that neither compiles nor has its deps/ fetched. The binary
carries Erlang and Elixir (Apple silicon and Linux x64 today).
codegraph-elixir --src ~/src/some-app --out app.jsonl
codegraph-elixir --src ~/src/some-app --deps ~/src/some-app/deps --out app.jsonl # dependency exports
codegraph-elixir --src ~/src/some-app --trace ~/src/some-app/codegraph-trace.jsonl --out app.jsonl
# the trace: what the compiler bound after macro expansion — `mix codegraph.trace` inside the project
This is the beginning of the README. Read the rest at the original. Read the full README ↗
