Agda: the Haskell implementation of a dependently typed language

What forty lines of README do and do not tell you

The Agda README opens with the title Agda 2, a row of badges for Hackage, Stackage, the test workflow, the documentation build and a Zulip chat, and the official logo. After that there are three short sections and one warning. The warning is the most useful line in the file: the README is only about Agda, not its standard library, and the Agda Wiki at wiki.portal.chalmers.se is where library information lives. Everything after that is a link list.

Documentation links out to the user manual on readthedocs, with a note that a per-commit PDF can be pulled from the user_manual.yml GitHub Actions page. That is unusual and useful: the manual is a moving target tied to master, and the Actions artifact is how you read the manual for a specific commit rather than whatever is deployed today. A CHANGELOG link sits next to it.

Getting Started links to an installation page and to a page called a quick guide to editing, type checking and compiling Agda code, which is the closest thing the project offers to a tutorial. Contributing links to CONTRIBUTING.md and to an external Haskell style guide, which tells you something about what the code is expected to look like.

What is absent is as telling as what is present. There is no example program in the README, no build command, no description of the type theory beyond the repository description line, and no comparison with any other system. The README is an index with a scope disclaimer, and you should plan on reading the linked pages rather than expecting to learn Agda from it.

Building through cabal and stack with flags the Makefile names

The build system is in `Makefile`, which is thin itself and delegates to include files: `mk/cabal.mk`, `mk/stack.mk`, `mk/paths.mk` and `mk/pretty.mk`, in that order, with the comment explaining that `paths.mk` needs both `TOP` and `HAS_STACK` already defined. What the top-level Makefile does hold is a dictionary of cabal and stack variants, and that dictionary is where the interesting build options live:

CABAL_OPT_TESTS   = --enable-tests
STACK_OPT_TESTS   = --test --no-run-tests
+
+CABAL_OPT_FAST    = --ghc-options=-O0 -fdebug
+STACK_OPT_FAST    = --fast --flag Agda:debug
+

The pair above is a two-speed build. The fast variants drop optimisation and turn on debug info, which is what you want when you are working inside the compiler rather than shipping it. The slow variants exist too: `-foptimise-heavily` and `-fversion-with-git-hash` are both cabal flags, the latter stamping the git hash into the version number, which is how the nightly builds identify themselves.

Tests run interactively and in parallel by default, with the job count taken from the processor count:

PARALLEL_TESTS ?= $(shell getconf _NPROCESSORS_ONLN)
AGDA_TESTS_OPTIONS ?=-i -j$(PARALLEL_TESTS)
+

+ +Overriding it is a documented make invocation rather than an environment variable: + +

+make PARALLEL_TESTS=123 test
+

+ +One more flag deserves attention because it changes what the compiler accepts rather than how fast it runs: `-fenable-cluster-counting`, paired on the stack side with `--flag Agda:enable-cluster-counting`. Cluster counting is an ICU dependency, which means the non-default build pulls in a C library the default build does not. That is a real cost of turning it on and a fair reason to check before enabling it.

The GHC version matrix is encoded as one file per version

Rather than negotiating GHC compatibility through constraints, the repository ships a config file for each supported compiler. The top-level tree lists `cabal.project.ghc-10.0.0`, `cabal.project.ghc-9.14.1`, `cabal.project.local.mtl23` and `cabal.project.tc`, alongside `hie-stack.yaml` and a family of stack resolver files: `stack-9.2.8.yaml`, `stack-9.4.2.yaml`, `stack-9.4.8.yaml`, `stack-9.6.7.yaml`, `stack-9.8.4.yaml`, `stack-9.10.3.yaml`, `stack-9.12.4.yaml` and `stack-9.14.1.yaml`. There is a Nix `flake.nix` and `flake.lock` too.

Two of those filenames carry information on their own. `cabal.project.local.mtl23` is the kind of override a developer drops in to track a newer mtl, and because `mk/config.mk` is gitignored according to the Makefile comments, local adjustments are expected rather than exceptional. `cabal.project.tc` is the type checker configuration by naming convention, though nothing in the README says so, and it is exactly the sort of file you would need to read before touching termination checking.

The release notes pin the supported range numerically. v2.8.0.1, published on 2026-08-31, added support for GHC 9.14.1 and states that Agda supports GHC versions 8.8.4 to 9.14.1. The nightly stream then took a different direction on 2026-09-23, dropping GHC 9.0 and below and bumping dependencies to LTS 20.26. So there is a gap between the last tagged release and the tip of master: the tagged release accepts GHC 8.8.4, the nightly does not. If you need the older compiler, stay on 2.8.0.2 rather than tracking nightly.

Nightly builds and two point releases in the space of three weeks

The releases page tells a story about a project in mid-transition. On 2026-08-31 came v2.8.0.1, a one-line change adding GHC 9.14.1. On 2026-09-13 came v2.8.0.2, and its notes are the most honest text in the repository: this version fixes two issues with the released binaries, and no non-installation related issues were fixed over 2.8.0 or 2.8.0.1, so if you already have 2.8.0 or 2.8.0.1 there is no need to upgrade. The two fixes are a missing `zlib1.dll` in the released Windows binary, and removing a commit hash that had leaked into the version number of released binaries.

Then on 2026-09-23 the `nightly` tag, named `06177f9@master`, collects work in flight: the GHC drop and LTS 20.26 bump, a Mimer refactor, an improvement to module checkpointing performance, and a new `--ghc-trace` option that instruments generated code with a call trace. The `--ghc-trace` addition is the kind of feature that tells you something about the audience. It exists for people debugging the code Agda emits, not people writing proofs.

The nightly notes are also a decent catalogue of where a dependently typed compiler is delicate. One entry fixes `instance` being silently dropped inside `primitive` and `variable` blocks. Another adds a warning when a REWRITE pragma appears while `--rewriting` is off, and a third warns when `@tactic` attributes are ignored in declarations. One entry removes an unused-argument optimization from the JS backend, undoing earlier work for correctness reasons. A language that treats an accidentally dropped instance as a silent bug is a language you should read the release notes for.

examples/ as a curriculum, from Hello World to termination checking

The `examples/` directory is the most substantial thing in the repository, and it is organised like a course rather than a test fixture. A reader who wants a feel for the language reads it top to bottom: `SimpleTypes.agda`, `DoNotation.agda`, `Monad.agda`, `ISWIM.agda`, `Setoid.agda`, `Binary.agda`, `Lookup.agda`, `Vec.agda` and `ParenDepTac.agda` at the top level, then directories for `arith/`, `order/`, `Termination/`, `cubical/`, `compiler/`, `lib/`, `malformed/` and the paper-derived sets `AIM4/`, `AIM5/`, `AIM6/`, `DTP08/`, `Miller/`, `Introduction/` and `SummerSchool07/`.

Several of those directories tell you what you are getting. `malformed/` holds programs expected to fail, which is how you learn what the errors mean. `Termination/` is the directory to read before you write anything you intend to compile, because termination checking is where dependently typed languages lose people. The top-level `cubical/` directory in the tree is the Cubical Agda work, and `examples/cubical/` shows how it is used in practice. `compiler/` is where the code generation and the `--ghc-trace` option earn their keep.

The paper directories are an unusual and generous choice. `Miller/` and `Introduction/` and `AIM4/` through `AIM6/` are named after the venues and the introductions where dependently typed programming got its canonical examples, so the repository carries the literature alongside the code. There is a `Makefile` inside `examples/` as well, which means the examples are built, not merely stored.

For a newcomer this is the honest answer to how you learn Agda: not from the README, which has no code in it, but by opening `SimpleTypes.agda`, reading until you stop understanding, and then opening `Termination/`. Keep the standard library caveat in mind, because several example directories reference the `std-lib` repository this one does not include.

Where Agda sits, and what the project will not tell you about it

The project description calls Agda a dependently typed programming language and interactive theorem prover, and the repository topics are agda, dependent-types, programming-language, proof-assistant and type-theory. Those five topics plus the license field reading NOASSERTION are the whole of the self-description. The README does not compare Agda to Coq or Idris, and it does not explain when you would choose a proof assistant over writing tests.

The repository itself offers more of an answer than the prose does. A Haskell implementation means the compiler sits on a very large typed codebase, which is the tradition Agda comes from. A separate standard library, reached through a `std-lib` tree entry and a `.gitmodules` file, is consistent with the library living in its own repository, which is why the README disclaims it. A `cubical/` directory means the constructive mathematics work is part of the implementation rather than a downstream experiment. A `benchmark/` directory next to `test/` means someone cared about performance on a codebase where performance is not free. And the `notes/` directory is where design discussion lives, which is often the most honest documentation a compiler project has.

The comparison people search for, Agda against Coq, is decided on axes this repository does not document for you: how each handles termination checking, what each standard library covers, and how the interactive experience feels. What the repository does support is a narrow claim. Agda's own history is visible in `AIM4/` and `Miller/` and in the nightly changelog, its tooling is aimed at people who read compiler internals as well as proofs, and its build matrix is wide enough that the compiler you already have is probably supported. Anything beyond that, you will have to read the user manual and the Agda Wiki for, and the Wiki is the place the README sends you twice.

Editorial conclusion

Agda rewards a reader who treats the repository as the documentation. The README is forty lines of links and one important boundary, the statement that it covers Agda and not the standard library, and nearly everything a new user actually needs sits one hop away in the user manual, the quick guide and the Agda Wiki. The practical picture is a Haskell project with a wide GHC compatibility matrix, a nightly release alongside tagged point releases, and an `examples/` tree that doubles as a textbook. Verified code still has to be trusted, since the proof assistant checks programs rather than executing them, and the release notes show a compiler where subtle mistakes in `primitive` blocks and rewrite pragmas are still being fixed. Start at the quick guide for editing and type checking, then read `examples/Termination/` and `examples/cubical/` before deciding whether the theorem proving or the dependent typing side is the part you want.

Frequently asked questions

Official sources

1. agda/agda on GitHub
2. Issues
3. Project website
4. README
5. Releases