# Introduction (/docs)

marmot compiles Go programs to native executables through MLIR and LLVM. It works like the
`go` command: run it inside a Go module, with the same packages, flags and tests.

```sh
marmot build ./cmd/app             # fast rebuilds
marmot build -release ./cmd/app    # whole program optimization
marmot run main.go
marmot test ./...
```

<Callout title="Status: experimental">
marmot compiles real Go programs, including itself, but it is new and not ready for
production use. See [Support](/docs/support) for what works and what does not.
</Callout>

## Why marmot [#why-marmot]

- **Small binaries.** A hello world with `println` is 148 KB in release mode, against
  1.68 MB from `go build`. With `fmt.Println` it is 665 KB against 2.4 MB.
- **Fast programs.** Release builds run 1.6x faster than Go on average over 43
  programs, with every program's output checked against Go.
- **Fast builds.** A rebuild with nothing changed takes 0.05 to 0.07 s on a 238
  package program, against 0.14 to 0.15 s.
- **Errors that teach.** Every error shows the source, the exact span, a label that says what
  is wrong there, and a suggested fix that `marmot fix` can apply. Coding agents get the same
  information as JSON.

<Shot name="error-short" alt="marmot build showing an undefined name error with the source, the span and a suggested fix" />

## The tools you install next to go [#the-tools-you-install-next-to-go]

marmot also does what people usually install separate tools for: `marmot fmt` (goimports),
`marmot check` (vet, golangci-lint, govulncheck, tidy and more, in one pass), `marmot fix`,
`marmot watch`, `marmot repl`, `marmot bench` (benchstat built in), `marmot prof` (pprof in the
terminal), `marmot size`, `marmot generate` with a cache, `marmot doctor`, and `marmot mcp` for
coding agents. See [Commands](/docs/commands).

## How it works [#how-it-works]

<Diagram name="overview" alt="Go source is type checked and turned into SSA, lowered to MLIR, optimized by Go-aware passes, then compiled by LLVM into a native binary linked with marmot's runtime" />

marmot keeps the parts of the Go toolchain that define the language (the `go/types` checker,
the SSA builder, Go's own standard library source) and replaces the parts that generate code.
[Design](/docs/design) explains each step.

## The name [#the-name]

A marmot is a close relative of the gopher, and it starts with M, like MLIR. Marmots stand
guard on a rock and whistle when something is wrong, which is what marmot's error messages are
for.