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-reloadJSON output(--json
) — machine-readable reportJSON config(zig.conf.json
) for project-level defaultsTimezone-aware timestamps****Phase progress + rich summary— scan/aggregate/write indicators, machine info, timingsbench
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. Withrun
, 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 s** First-class C interop**— import C headers directly with@cImport
; no bindings, no FFI layerComptime— 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 DSLCross-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! 🚀