---

Welcome to the contributor guide

If you want to learn about NeoHaskell itself, checkout the NeoHaskell website.

This guide is intended to streamline the process of contributing to the NeoHaskell tooling.

The repository is a mono-repo that contains all the different parts of NeoHaskell:

• core/ → nhcore — the core library (event-sourcing + CQRS in core/service/)
• testbed/ → nhtestbed — reference app + acceptance tests
• integrations/ → nhintegrations — outbound integrations
• installer/ → neo-install — the Rust installer
• neo/ → neo — the Rust CLI and bundled IDE

The public Astro website and documentation now live in the separate neohaskell/website-v2 repository.

This README is the canonical guide for human contributors: environment setup, the full build/test commands, and Postgres. Two companion guides own the rest:

• AGENTS.md — the agent contract: hard rules, dialect style, and the spec-gated change pipeline.
• codemap/README.md — localization routing, API discovery, and codemap regeneration.

Architecture decisions live in docs/decisions/ (indexed in docs/decisions/README.md). The standalone website fetches the latest main commit from this repository when it builds, then generates the public ADR pages and runs its documentation evidence checks locally.

Installing the required tools

(This assumes that you're using MacOS, WSL2 or Linux)

1. Install Nix with flakes enabled
2. Run nix develop to enter the development shell
3. Run cabal update && cabal build all

Binary Cache (Faster Builds)

The project uses Cachix to cache build artifacts. The flake.nix is pre-configured to use our cache, so nix develop should automatically prompt you to trust it on first run.

If you want to explicitly enable it (or if you have a restrictive Nix config):

# Install cachix (if not already installed)
nix-env -iA cachix -f https://cachix.org/api/v1/install

# Add the NeoHaskell cache
cachix use neohaskell

This dramatically speeds up the first nix develop (from ~30 min to ~2 min).

The recommended IDE for any NeoHaskell project is Visual Studio Code.

Get the code

• Fork this repository
• git clone <url to your fork>
• cd NeoHaskell && code .

Install the recommended extensions

When opening the project for the first time, you will be prompted to install the recommended extensions, install them.

Code Formatting

This project uses the fourmolu formatter for consistent Haskell code styling. When using VS Code with the recommended extensions:

• Code will automatically format on save
• The formatter settings are controlled by the fourmolu.yaml file in the root directory

Linting

This project uses hlint, it will automatically be run in VSCode by the recommended extension. To run manually (same paths and config as the CI gate):

./dev lint

Since 2026-07-07 the hlint config is dialect-first: it encodes NeoHaskell's style rules (vanilla modules restricted to their Core wrappers, banned partials, $ → |> teaching hints) and runs as a CI gate. ./dev lint runs the exact same check locally. No Core wrapper for what you need? The escape hatch is documented at the top of .hlint.yaml.

Fast inner loop

The same tools the CI/agent pipeline uses work on demand for humans (they are the same scripts on purpose — if you can't reproduce what the pipeline saw, you can't debug it). One entrypoint, run ./dev for the full menu:

./dev watch                          # resident typecheck watcher (ghcid, -O0)
./dev check                          # instant typecheck status
./dev test "EventStore"              # run only matching specs, no linking (~4-9s)
./dev test "insert" nhcore-test-service   # pick a suite
./dev refresh                        # re-warm the -O0 build after pull/branch switch
./dev exec ghc --version             # anything else, with the pinned toolchain

Typecheck feedback lands in under a second once the watcher is running. You don't need to be inside nix develop: every verb enters it on demand (pinned toolchain from any bare shell). Measured baselines: telemetry/SCHEMA.md.

Running Tests

The core library tests are split into domain-specific suites that run in parallel on CI:

# Run all tests
cabal test all

# Run specific test suites
cabal test nhcore-test-core         # Core primitives (fast)
cabal test nhcore-test-auth         # Auth & JWT tests
cabal test nhcore-test-service      # Service layer (requires PostgreSQL)
cabal test nhcore-test-integration  # Integration tests

Note: nhcore-test-service requires a PostgreSQL instance. You can start one with:

docker run -d --name neohaskell-postgres \
  -e POSTGRES_USER=neohaskell \
  -e POSTGRES_PASSWORD=neohaskell \
  -e POSTGRES_DB=neohaskell \
  -p 5432:5432 \
  postgres:16-alpine

Collaborate on Discord

It's always better to hack with people, so why not join the Discord server?

Contributors

Thanks to everyone who has contributed to NeoHaskell!

The image above is generated automatically from the GitHub contributors graph by contrib.rocks — no manual upkeep required.