mammoth

module

v0.9.0 Latest Latest Go to latest Published: Mar 18, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/2389-research/mammoth

Links

Open Source Insights

README ¶

Mammoth

A DOT-based pipeline runner for LLM agent workflows. Define a graph, run it, watch it think.

Pipeline execution powered by github.com/2389-research/tracker.

Architecture

Layer	Package	Description
LLM SDK	`llm/`	Unified client for OpenAI, Anthropic, and Gemini APIs
Pipeline Runner	`tracker` (external)	DOT-based DAG execution, node handlers, human-in-the-loop gates
Run State	`runstate/`	Pipeline run persistence, auto-resume, audit

Supporting packages: dot/ (DOT parser/serializer/validator), spec/ (event-sourced spec builder), web/ (unified web layer), editor/ (DOT graph editor), render/ (DOT→SVG/PNG), tui/ (Bubble Tea terminal UI), mcp/ (MCP server), cmd/mammoth/ (CLI).

Install

Homebrew (macOS/Linux)

brew install 2389-research/tap/mammoth

Go

go install github.com/2389-research/mammoth/cmd/mammoth@latest

Download binary

Pre-built binaries for macOS and Linux (amd64/arm64) are available on the releases page.

# Example: Linux amd64 — replace VERSION with the desired release (e.g. 0.2.0)
VERSION="0.2.0"
curl -sL "https://github.com/2389-research/mammoth/releases/download/v${VERSION}/mammoth_${VERSION}_Linux_x86_64.tar.gz" | tar xz
sudo mv mammoth /usr/local/bin/

Build from source

git clone https://github.com/2389-research/mammoth.git
cd mammoth
make build
# Binary is at ./bin/mammoth

Quick Start

# Set an API key (at least one required)
export ANTHROPIC_API_KEY="sk-ant-..."
# or: export OPENAI_API_KEY="sk-..."
# or: export GEMINI_API_KEY="..."

# Run a pipeline
mammoth run pipeline.dot

Usage

# Validate a pipeline without running it
mammoth -validate pipeline.dot

# Run with the terminal UI
mammoth run -tui pipeline.dot

# Start the web UI
mammoth serve --port 2389

Testing

# Run all tests (5,200+ tests)
go test ./...

# Run with race detector
make test-race

# Run with coverage
go test ./... -coverprofile=coverage.out
go tool cover -func=coverage.out

Documentation

Quickstart — Get a pipeline running in under five minutes
CLI Usage — Pipeline execution, validation, and server mode
CLI Specification — Commands, flags, output formats, and exit codes
DSL Reference — DOT digraph syntax for LLM agent pipelines
Handlers — 9 built-in execution units
Backend Configuration — Provider keys, model catalog, retry
API Reference — Go packages, HTTP endpoints, types, and events
Walkthrough — Write, validate, and run pipelines from scratch
Parity Matrix — Spec coverage tracking
Test Coverage — Per-package thresholds

Browse the full docs hub at docs/index.html.

Pipeline Execution

Pipeline execution is handled by the tracker library. Mammoth provides the DOT parser/validator (dot/), web UI (web/), TUI (tui/), MCP server (mcp/), and CLI (cmd/mammoth/) that consume tracker's API.

License

MIT License. See LICENSE for details.

Built by 2389 Research, Inc. | [email protected]

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
agent
cmd
mammoth command ABOUTME: Pipeline run audit narrative generator using LLM analysis.	ABOUTME: Pipeline run audit narrative generator using LLM analysis.
mammoth-mcp command ABOUTME: Entrypoint for the mammoth MCP server binary.	ABOUTME: Entrypoint for the mammoth MCP server binary.
dot ABOUTME: Consolidated AST types for the unified DOT parser, merging mammoth attractor and dot-editor ASTs.	ABOUTME: Consolidated AST types for the unified DOT parser, merging mammoth attractor and dot-editor ASTs.
validator ABOUTME: Unified lint rules for DOT pipeline graphs, merged from mammoth-dot-editor and attractor/validate.go.	ABOUTME: Unified lint rules for DOT pipeline graphs, merged from mammoth-dot-editor and attractor/validate.go.
editor ABOUTME: Embedded filesystem for editor templates and static assets.	ABOUTME: Embedded filesystem for editor templates and static assets.
llm
sse
mcp ABOUTME: Package mcp exposes the tracker pipeline runner as an MCP server.	ABOUTME: Package mcp exposes the tracker pipeline runner as an MCP server.
render ABOUTME: In-memory render cache that wraps a DOT rendering function with sha256-keyed caching.	ABOUTME: In-memory render cache that wraps a DOT rendering function with sha256-keyed caching.
runstate ABOUTME: Defines RunState types and FSRunStateStore for persisting pipeline run state to the filesystem.	ABOUTME: Defines RunState types and FSRunStateStore for persisting pipeline run state to the filesystem.
spec
agents ABOUTME: AgentContext feeds state and history to LLM-backed agents within the swarm.	ABOUTME: AgentContext feeds state and history to LLM-backed agents within the swarm.
agents/tools ABOUTME: Implements the ask_user_boolean tool for asking yes/no questions via mux Tool interface.	ABOUTME: Implements the ask_user_boolean tool for asking yes/no questions via mux Tool interface.
core ABOUTME: Goroutine-based actor for processing spec commands and broadcasting events.	ABOUTME: Goroutine-based actor for processing spec commands and broadcasting events.
core/export ABOUTME: Shared lane ordering and card grouping logic for all exporters.	ABOUTME: Shared lane ordering and card grouping logic for all exporters.
export ABOUTME: Shared lane ordering and card grouping logic for all exporters.	ABOUTME: Shared lane ordering and card grouping logic for all exporters.
server ABOUTME: Shared application state for the mammoth spec builder HTTP server.	ABOUTME: Shared application state for the mammoth spec builder HTTP server.
store ABOUTME: Append-only JSONL event log for durable event storage.	ABOUTME: Append-only JSONL event log for durable event storage.
web ABOUTME: Embedded filesystem for spec builder templates and static assets.	ABOUTME: Embedded filesystem for spec builder templates and static assets.
tui ABOUTME: Top-level Bubble Tea AppModel that orchestrates all TUI sub-panels into a unified layout.	ABOUTME: Top-level Bubble Tea AppModel that orchestrates all TUI sub-panels into a unified layout.
web ABOUTME: Build run types and SSE event formatting for pipeline execution.	ABOUTME: Build run types and SSE event formatting for pipeline execution.