facebookincubator/Glean: Source Code Facts and Angle Queries

What Glean Stores and Who It Serves

Glean addresses a specific data problem: source code contains relationships that are useful to editors, code intelligence tools, and offline analyzers, but those relationships are not always available in a form that tools can query repeatedly. The project collects facts about symbols, including their locations and types, and records relationships such as function calls and method calls. It also represents call hierarchies and type hierarchies.

The intended users are systems that need a reusable code knowledge layer rather than a one-time text search. The README gives examples ranging from online IDE features to offline code analysis. That boundary matters. Glean is not presented as a compiler, editor, or general-purpose static analyzer. It is the collection, storage, and query infrastructure between an indexer and the experiences built on top of it.

The README describes Glean as designed around an efficient storage model for code information at scale. The project uses Angle as its query language. This makes Glean relevant when consumers need structured cross-references or hierarchy queries across a corpus, rather than when a developer only needs to locate a literal string in one file.

Indexers, SCIP, LSIF, and Coverage Boundaries

Glean has different routes for collecting facts depending on the language. The README lists full support for C++, C, Hack, Haskell, JavaScript, and Flow. These indexers are documented under the Glean indexer pages. The distinction between language and implementation matters because a language name in the README does not necessarily mean that every language variant uses the same indexing path.

For Rust, Go, TypeScript, Java, Python, and.NET, the project also supports SCIP or LSIF code indexing formats. The README links documentation for Rust through rust-analyzer, Go, TypeScript, Java, Python, and.NET. This gives Glean a route to consume indexes produced by other indexing systems. The README does not claim that every indexer has the same native depth or feature set.

Custom indexers are listed for Python, Java, Kotlin, Erlang, Thrift, Buck and Bazel, C#, and Swift, but the README says those custom indexers are not included in the open source release. That boundary affects adoption. A team interested in one of these languages must use an available SCIP or LSIF route where documented, build or obtain another indexer, or contribute one. The README does not document a complete matrix of equivalence between native and format-based indexes.

Docker Demo and First Source Code Exploration

The README provides a Docker demo as the shortest documented route to trying Glean. The demo uses the React codebase and exposes a web interface on port 8888. The command below comes from the README. It starts the demo image interactively and maps port 8888 on the host to port 8888 in the container.

docker run -ti -p8888:8888 ghcr.io/facebookincubator/glean/demo

According to the README, the demo provides hyperlinks powered by Glean. It does not give the exact browser URL or a first Angle query for this image, so those details should be taken from the demo interface or linked documentation rather than inferred.

For a local codebase with a `.flowconfig`, the README documents mounting the code directory into the demo. Replace the placeholder with the actual path. The container then has access to that directory under `/glean_demo/code`.

docker run -ti -p8888:8888 -v __YOUR_CODE_DIR__:/glean_demo/code ghcr.io/facebookincubator/glean/demo

The README also provides a shell-oriented demo command. It starts the same image and gives access to the Glean binaries in a shell.

docker run -ti -p8888:8888 ghcr.io/facebookincubator/glean/demo shell

These commands are suitable for a first use of the documented demo, not a production deployment guide.

Building Glean from the Repository

The repository includes a `Makefile`, a Cabal project file, a generated `glean.cabal.in` template, C++ sources, and an `install_deps.sh` script. The README directs developers to the separate Building Glean documentation. The repository confirms that a build is possible, but the README does not give a complete local installation sequence that can be reproduced from the listed text alone.

The Makefile describes three useful build choices. Running `make` builds everything through Cabal using standard Cabal directories. Running `make test` runs the tests. Development builds can use a separate build directory through `MODE=dev`, while optimized builds use `MODE=opt`. The file describes the latter as slower and optimized.

make MODE=dev

The Makefile also explains a design tradeoff behind the build process. Cabal is needed for Hackage support, but Cabal cannot build C++ files in parallel and does not track include dependencies between separate C++ libraries. For development, the Makefile prefers building C++ libraries with make so compilation can run in parallel and include dependencies can be tracked. This is useful context for anyone evaluating build complexity, because Glean is not only a single executable project. It combines Haskell, C++, generated configuration, external dependencies, and a demo image.

The Dockerfile confirms that the image builds with GHC 8.10.2, CMake, Ninja, native libraries, Cabal, and a downloaded Flow binary. The file uses `make`, then copies `glean`, `glean-server`, and `glean-hyperlink` into `~/.cabal/bin/`. Those details describe the image build, not a universal requirement list for every installation method.

Angle Queries Over Collected Facts

Angle is the query interface identified by the README. Its presence changes the role of the indexer. An indexer produces structured code information, while Angle provides a way to ask questions over that information. The documented fact categories include symbol identity, location, type, cross-references, call hierarchies, and type hierarchies.

That separation can support repeated analysis without making every consumer understand the internal storage format. An IDE feature could use a cross-reference fact to offer navigation from a definition to uses, while another consumer could inspect a call hierarchy. The README does not publish an Angle query tutorial or a command syntax for querying an indexed repository in the available documentation, so inventing examples would misrepresent the project.

The storage model is also described as intended to work with large amounts of code information. That does not establish a maximum repository size, query latency, or hardware requirement. Engineers should treat scale as a design goal stated by the project, not as a measured capacity claim, and should validate storage behavior with their own corpus before choosing an operational topology.

Maintenance, Licensing, and Upgrade Cost

The repository is not archived, and its last push was on 2026-10-15. GitHub releases are not listed for this repository, so there is no release history to use as an upgrade channel in this assessment. It would therefore be unsafe to infer release cadence, compatibility policy, or migration steps from repository push activity alone.

The README states that Glean is licensed under a `BSD LICENSE` and links the repository's `LICENSE` file. The repository metadata classifies the license as Other with a custom GitHub classification, so the actual license file should be reviewed before redistribution or integration decisions. This is a licensing fact, not legal advice. Contributors are also told to sign the Contributor license agreement before a pull request can be accepted.

Operational cost is not quantified. The Dockerfile shows a substantial build environment and the presence of C++ and Haskell components, which can increase build and upgrade effort compared with a small standalone query script. The repository offers a Docker demo and a documented build route, but it does not specify production storage configuration, backup procedures, or a formal compatibility matrix for upgrades.

When Glean Is the Wrong Choice

Glean is the wrong choice when the requirement is only to search text in a repository and no structured facts are needed. It is also a poor fit for a language whose required indexer is absent from the open source release, unless the team is prepared to provide that indexer or use a documented SCIP or LSIF path. The README is explicit that custom indexers for several languages are not yet in the open source release.

A team that cannot operate a multi-language indexing and storage system may prefer a simpler analysis tool for its immediate need. The README does not compare Glean with a particular alternative, so the relevant alternative is architectural: a direct indexer plus an application-specific database or query layer. The actual difference is control and cost. Such a setup can be simpler for one language and one consumer, but it does not provide Glean's documented model for storing and querying cross-references, call hierarchies, and type hierarchies. Conversely, Glean introduces a larger system with its own build, indexer, storage, and query concerns.

Editorial conclusion

Adopt Glean when a tool needs a structured query layer over source code facts and the required indexer is available. Do not adopt it expecting uniform native coverage for every language or a fully documented production deployment without checking the build documentation. Verify indexer support, storage requirements, and the documented build process first.

Frequently asked questions

Official sources

1. facebookincubator/Glean on GitHub
2. Issues
3. Project website
4. README