How we work with ZigZag

Introduction / Motivation

We've all done it. You open five different files, copy chunks of code into ChatGPT, and ask "Can you figure out what's wrong with this?" . The problem isn't the AI - it's that it doesn't have the context of your codebase. ZigZag fixes that automatically. Run zigzag run --llm-report in your terminal and it recursively scans your project, skips the noise (node_modules, .git, binaries, lockfiles), and condenses everything into a single token-efficient Markdown file you can hand to any LLM.

Why ZigZag when tools like Claude Code and CodeX exist?

Because ZigZag isn't an AI assistant; it's the middleman that sits between. It takes a sprawling codebase and turns it into a single (or chunked) token-efficient Markdown file. Where that file goes is up to you: ChatGPT's free tier, Gemini, DeepSeek, a local model, or the Claude Code subscription you already pay for. No API keys. No GPU. No monthly bill. Just a binary that reads your project and hands you the context.

Features

LLM report (--llm-report) — condensed, token-efficient output with per-file condensation + chunking via --chunk-size.

Binary file detection — Ignores reading binary files automatically.
Auto-skipped directories — node_modules, .git, .turbo, .nx, .parcel-cache, etc.
Watch mode — OS-level fs events (inotify/kqueue/ReadDirectoryChangesW), 50ms debounce
HTML dashboard (--html) — charts, virtual-scroll source viewer, syntax highlighting, live-reload
JSON output (--json) — machine-readable report
JSON config (zig.conf.json) for project-level defaults
Timezone-aware timestamps
Phase progress + rich summary — scan/aggregate/write indicators, machine info, timings
bench subcommand — per-phase timing table

Installation / Getting Started

ZigZag is built on Zig version 0.15.2, but plans to upgrade to 0.16.0 are in the works.

Building from source

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

The executable will be available at: zig-out/bin/zigzag

Basic Usage

The recommended workflow is config-first:

zigzag init                    # create zig.conf.json with sane defaults
zigzag run                     # scan using the config
zigzag run --llm-report        # ...and emit a token-efficient LLM report

Prefer flags? Skip the subcommand and pass everything inline:

zigzag --help
zigzag --paths ./src,./docs --ignores ".git,node_modules,*.test.zig" --timezone "-5"

Common combinations:

zigzag run --watch --html --open       # live dashboard in your browser
zigzag run --llm-report --chunk-size 500k   # split large codebases into chunks
zigzag bench                            # per-phase timing table

Without a subcommand, ZigZag ignores zig.conf.json and uses CLI flags only. With run, the config is the base and flags override it.

Why Zig?

Zig may not be a stable programming language, but it's already being adopted in large codebases such as:

Ghostty – a GPU-accelerated terminal
TigerBeetle – a high-performance financial transactional database

Zig also excels at:

Manual memory control — explicit allocators, no hidden allocations, no GC pauses
First-class C interop — import C headers directly with @cImport; no bindings, no FFI layer
Comptime — compile-time code execution replaces macros, generics, and templates with plain Zig
A build system that's just Zig — build.zig is a program, not a DSL
Cross-compilation out of the box — target any platform from any platform, no toolchain wrangling

Thank You for Reading!

Thank you for taking the time to read this article! I hope it gave you a clear idea of how ZigZag can simplify working with your codebase and enhance your AI-assisted development workflow.

If you’d like to try it out, contribute, or share feedback, check out the repository: GitHub - Zagforge-Org/zigzag

Happy coding! 🚀