elspais

"L-Space is the ultimate library, connecting all libraries everywhere through the sheer weight of accumulated knowledge." — Terry Pratchett

elspais is a requirements validation and traceability tool for teams managing formal requirements across one or more repositories. It validates requirement formats, enforces hierarchy rules, tracks changes with content hashes, and generates traceability matrices linking requirements to code and tests.

Installation

# Homebrew (macOS/Linux)
brew install anspar-org/anspar/elspais

# pipx (isolated install)
pipx install elspais

# pip
pip install elspais

Optional extras

pip install elspais[trace-view]    # Static HTML traceability view
pip install elspais[trace-review]  # Interactive viewer server
pip install elspais[mcp]           # MCP server for AI integration
pip install elspais[coverage]      # Per-test line coverage from .coverage files
pip install elspais[dart]          # Dart and Flutter test selection by imports
pip install elspais[ast]           # Test and function boundaries in JS/TS, Go, Java, Kotlin, Rust, C#
pip install elspais[all]           # Everything

Quick Start

# Initialize configuration
elspais init

# Validate requirements
elspais checks

# Auto-fix hashes and formatting
elspais fix

# Generate traceability matrix
elspais trace --format html

# Interactive viewer (live server)
elspais viewer

# Built-in documentation
elspais docs

MCP Server (AI Integration)

elspais includes an MCP server for use with Claude Code, Claude Desktop, and other MCP-compatible clients.

# Install the MCP extra
pip install elspais[mcp]

# Register with Claude Code (all projects) and Claude Desktop
elspais mcp install --global --desktop

# Each shell supplies the daemon's address before launching the client
eval "$(elspais mcp env)"

The MCP server provides tools for searching requirements, navigating hierarchies, checking coverage, and drafting mutations — all operating on the live traceability graph.

Mutations use optimistic concurrency: several writers (agents and the viewer GUI) can share one daemon, so every mutation requires a version token from a prior read and stale writes are rejected rather than silently overwriting. See elspais docs concurrency for the protocol.

Requirement Format

Requirements are written in Markdown:

# REQ-d00001: Requirement Title

**Level**: Dev | **Status**: Active | **Implements**: REQ-p00001

## Assertions

A. The system SHALL provide user authentication via email/password.
B. Sessions SHALL expire after 30 minutes of inactivity.

*End* *Requirement Title* | **Hash**: a1b2c3d4
---

Hierarchy: PRD (product) → OPS (operations) → DEV (development)
Traceability: Children reference parents via Implements:
Assertions: Labeled A-Z, using SHALL for normative statements
Hash footer: SHA-256 content hash for change detection

Configuration

Create .elspais.toml in your repository root (or run elspais init):

[project]
name = "my-project"
namespace = "REQ"

[levels.prd]
rank = 1
letter = "p"
implements = ["prd"]

[levels.ops]
rank = 2
letter = "o"
implements = ["ops", "prd"]

[levels.dev]
rank = 3
letter = "d"
implements = ["dev", "ops", "prd"]

[scanning.spec]
directories = ["spec"]

[scanning.code]
directories = ["src"]

[id-patterns]
canonical = "{namespace}-{level.letter}{component}"

[rules.format]
require_hash = true
require_assertions = true

See docs/configuration.md for full reference.

Multi-Repository Support

Link associated repositories that extend a core requirement set:

elspais init --type associated --associated-prefix CAL
elspais associate ../core-repo
elspais checks

CLI Commands

elspais checks         Verify requirements traceability and configuration
elspais fix            Auto-fix spec file issues (hashes, formatting)
elspais trace          Generate traceability matrix (markdown, html, csv)
elspais viewer         Start interactive viewer server
elspais doctor         Diagnose environment and installation health
elspais analysis       Analyze foundational requirement importance
elspais changed        Detect git changes to spec files
elspais edit           Edit requirements in-place
elspais config         View and modify configuration
elspais associate      Manage associate repository links
elspais link suggest   Suggest requirement links for unlinked tests
elspais pdf            Compile spec files into PDF
elspais mcp            MCP server commands
elspais docs           Built-in user guide
elspais example        Requirement format examples

Run elspais <command> --help for detailed usage. See src/elspais/docs/cli/commands.md for full documentation.

Development

git clone https://github.com/anspar/elspais.git
cd elspais
make setup
make test

make setup builds .venv with Python 3.14, the one version elspais supports (uv python install 3.14 provides python3.14 where the system lacks it), installs elspais into it, and installs the git hooks. The hooks and the test targets both run the tools from that directory, so what they report describes this checkout and not some other installation of elspais.

Every dependency is installed at the version requirements/dev.lock pins, and CI installs the same, so a test run here and in CI see the same packages. After changing the dependencies in pyproject.toml, run make lock and commit the regenerated lock with the change; CI fails while the lock is out of date. Run make setup again when the lock moves.

Where Claude Code is installed, make setup also registers the elspais MCP server over http. The daemon behind it runs the program that started it, so start it with this checkout's elspais before launching Claude Code:

eval "$(.venv/bin/elspais mcp env)"
claude

License

GNU Affero General Public License v3 (AGPL-3.0) — see LICENSE.

Metadata

Release files for elspais 0.129.17

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for elspais 0.129.17
File	Size	Uploaded
elspais-0.129.17.tar.gz	3.3 MB	Oct 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for elspais 0.129.17
File	Interpreter	ABI	Platform	Reset
elspais-0.129.17-py3-none-any.whl 1.5 MB Oct 15, 2026	Python 3	none	any	Details

Total release size: 4.8 MB

Release files / elspais-0.129.17.tar.gz

Download URL	elspais-0.129.17.tar.gz
Size	3.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`fc58edb8965a3310c2a63c5b72112dae5f88969dacb005f6023413d8a3af9134`
BLAKE2b-256 checksum How to use checksums	`cc1bf191850e676581e864dcd0bfcf55401319fe8e8dc58fb6aa22444e3f0cfe`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Release files / elspais-0.129.17-py3-none-any.whl

Download URL	elspais-0.129.17-py3-none-any.whl
Size	1.5 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`dac0d94230c7aa37237215a0870e1b71a31ba24a2764cc11c4121a004276cc8e`
BLAKE2b-256 checksum How to use checksums	`831bff7225621ceda2c6982f0b759e3b9908e9789d95febf33ae768d172b6753`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`