Getting Started

This guide walks you through installing ZigZag and generating your first code report.

Installation

Homebrew (macOS / Linux) — Recommended

brew tap LegationPro/zigzag
brew install zigzag

Pre-built Binaries

Download the latest archive for your platform from the Releases page, extract it, and place the zigzag binary somewhere on your PATH.

macOS — Gatekeeper notice

Because the binary is downloaded from the internet, macOS will quarantine it. Remove the flag with:

xattr -d com.apple.quarantine zigzag

Or right-click the binary in Finder, then click Open twice to approve it.

The release binaries are ad-hoc code-signed, which avoids the "damaged and can't be opened" error on Apple Silicon. The Homebrew tap is the easiest path for a warning-free install.

Building from Source

Requires Zig 0.15.2.

git clone https://github.com/LegationPro/zigzag.git
cd zigzag
zig build -Doptimize=ReleaseFast

The executable will be at zig-out/bin/zigzag. On Unix systems, running zigzag.sh automatically places the binary under /usr/local/bin.

Initialize a Project

Run zigzag init in your project root to create a zig.conf.json with sensible defaults:

cd my-project
zigzag init

This generates:

{
  "paths": [],
  "ignore_patterns": [],
  "skip_cache": false,
  "skip_git": false,
  "small_threshold": 1048576,
  "mmap_threshold": 16777216,
  "timezone": null,
  "output": "report.md",
  "watch": false,
  "log": false,
  "json_output": false,
  "html_output": false,
  "output_dir": "zigzag-reports",
  "llm_report": false,
  "llm_max_lines": 150,
  "llm_description": null
}

Generate Your First Report

Add the directories you want to scan, then run:

zigzag run --path ./src

ZigZag will scan your src/ directory and produce a report.md inside zigzag-reports/ containing your entire source code with metadata, organized with a table of contents.

Add Multiple Paths

Scan several directories at once — each gets its own report:

zigzag run --path ./src --path ./lib --path ./tests

Generate All Output Formats

Get Markdown, JSON, and HTML reports in one command:

zigzag run --path ./src --html --json

Using a Config File

Instead of passing flags every time, edit your zig.conf.json:

{
  "paths": ["src", "lib"],
  "ignore_patterns": ["*.test.ts", "*.spec.ts", ".env"],
  "watch": false,
  "json_output": true,
  "html_output": true,
  "output_dir": "zigzag-reports",
  "llm_report": true
}

Then simply run:

zigzag run

CLI flags always override config file values, so you can use the config as a baseline and tweak on the fly:

# Use config but enable watch mode for this run
zigzag run --watch

Config Loading Priority

Settings are applied from lowest to highest priority (later values win):

1. Hard-coded defaults
2. zig.conf.json (when using zigzag run)
3. CLI flags (always override file config)

When the first --path CLI flag is encountered, all file-loaded paths are replaced. Same for --ignore. Scalar fields always take the last CLI value.

Next Steps

• Learn about use cases and workflows for ZigZag
• Browse the CLI and configuration reference