Guides

Explore common workflows and use cases for ZigZag.

Use Cases

Feeding Context to LLMs

One of ZigZag's most powerful use cases is generating code reports that you can feed directly to LLMs like Claude, ChatGPT, or Copilot. Instead of manually copying files, ZigZag produces a single Markdown document with your entire codebase — organized, annotated, and ready to paste.

Enable the --llm-report flag for reports specifically optimized for LLM consumption:

zigzag run --paths ./src --llm-report --llm-max-lines 150

The LLM report format is more concise, with controlled line limits per file. You can also add a project description for additional context:

zigzag run --paths ./src --llm-report --llm-description "REST API backend built with Express and TypeScript"

For large codebases, use --chunk-size to split the LLM report into multiple files. Accepts byte counts with optional k/m suffixes:

zigzag run --paths ./src --llm-report --chunk-size 500k
zigzag run --paths ./src --llm-report --chunk-size 2m

When chunking is active, chunk 1 is written to report.llm.md, additional chunks to report.llm-2.md, report.llm-3.md, and a report.llm.manifest.json index is created listing all chunk files. Files are never split across chunk boundaries.

Config file setup for LLM workflows:

{
  "paths": ["src"],
  "ignores": ["*.test.ts", "*.spec.ts", "node_modules", "dist"],
  "llm_report": true,
  "llm_max_lines": 150,
  "llm_description": "E-commerce backend API",
  "llm_chunk_size": "500k"
}

Code Review and Onboarding

Generate a browsable HTML dashboard to help new team members understand a codebase, or use it during code review to get a bird's-eye view:

zigzag run --paths ./src --html --open

The --open flag automatically launches the dashboard in your browser. The dashboard includes:

• Summary cards showing total files, lines, size, and language breakdown
• A searchable file table
• A source code viewer with syntax highlighting
• Language distribution charts

CI/CD Integration

Add ZigZag to your CI pipeline to automatically generate and publish code reports on every push or release:

# GitHub Actions example
- name: Generate code report
  run: |
    zigzag run --paths ./src --json --html

- name: Upload reports
  uses: actions/upload-artifact@v4
  with:
    name: zigzag-reports
    path: zigzag-reports/

The JSON output is particularly useful for building custom dashboards or tracking codebase metrics over time.

Documentation Generation

Use ZigZag reports as an always-up-to-date reference for your codebase. Combine watch mode with HTML output to maintain a live documentation server during development:

zigzag run --paths ./src,./lib --html --watch

When multiple paths are provided with --html, ZigZag generates both individual per-path reports in subdirectories and a combined combined.html dashboard at the output root covering all directories at once.

Use zigzag serve to start the built-in HTTP server and serve the HTML report directly:

zigzag serve --port 8080

---

Tutorials

Tutorial: Watch Mode

Watch mode monitors your filesystem for changes and automatically rebuilds reports. It uses OS-level filesystem events (inotify on Linux, kqueue on macOS/BSD, ReadDirectoryChangesW on Windows) for instant detection.

zigzag run --paths ./src --watch

How it works:

• Only the changed file is re-read from disk
• The report is rebuilt from the in-memory state of all other files
• Events within a 50ms window are batched into a single report write
• Press Ctrl+C to stop

Combine with HTML output for a live-updating dashboard:

zigzag run --paths ./src --watch --html --open

Or enable it in your config file for persistent use:

{
  "paths": ["src"],
  "watch": true,
  "html_output": true
}

To override "watch": true from the config file for a single run, use --no-watch:

zigzag run --no-watch

Tutorial: HTML Dashboard

The HTML dashboard is a self-contained, interactive file — all CSS, JavaScript, and syntax highlighting are bundled into a single .html file. Open it in any browser without a server.

zigzag run --paths ./src --html

The dashboard includes:

Feature	Description
Summary cards	Total files, lines, size, and languages at a glance
Language chart	Bar chart of file counts per language
Size distribution	Histogram of file sizes across the codebase
File table	Sortable, searchable table of all source files
Source viewer	Click any file to view its source code in a slide-in panel
Syntax highlighting	Off-thread Prism highlighting for 20+ languages
Virtual scroll	Files over 500 lines use virtual scrolling for instant rendering
Dark mode	Follows your OS theme automatically

Supported languages for syntax highlighting: Zig, JavaScript, TypeScript, Lua, JSON, HTML, XML, SVG, CSS, SCSS, Bash/Shell, C, C++, Rust, Go, Python, Ruby, Java, Markdown, TOML, YAML, SQL.

Serve it on a specific port during development:

zigzag run --paths ./src --html --watch --port 3000 --open

When scanning multiple paths, ZigZag outputs individual reports per subdirectory plus a combined.html at the output root:

zigzag run --paths ./src,./lib --html
# produces: zigzag-reports/src/report.html
#           zigzag-reports/lib/report.html
#           zigzag-reports/combined.html  ← unified dashboard

Tutorial: JSON Reports

JSON output produces a machine-readable report alongside the Markdown file, useful for CI dashboards, code analysis pipelines, or custom tooling.

zigzag run --paths ./src --json

The JSON report structure:

{
  "meta": {
    "version": "0.16.0",
    "generated_at_ns": 1738245534000000000,
    "scanned_paths": ["./src"]
  },
  "summary": {
    "source_files": 12,
    "binary_files": 3,
    "total_lines": 1450,
    "total_size_bytes": 58320,
    "languages": [
      { "name": "zig", "files": 10, "lines": 1300, "size_bytes": 52000 },
      { "name": "json", "files": 2, "lines": 150, "size_bytes": 6320 }
    ]
  },
  "files": [
    {
      "path": "./src/main.zig",
      "size": 2345,
      "mtime_ns": 1738245534000000000,
      "extension": ".zig",
      "language": "zig",
      "lines": 87
    }
  ],
  "binaries": [
    {
      "path": "./src/assets/logo.png",
      "size": 4096,
      "mtime_ns": 1738240000000000000,
      "extension": ".png"
    }
  ]
}

Tutorial: Ignore Patterns

ZigZag supports multiple pattern types for excluding files and directories from reports:

Pattern Type	Example	Description
Wildcard extension	*.png, *.svg	Ignores all files with the extension (case-insensitive)
Exact filename	test.txt, .env	Ignores files with an exact name match
Wildcard prefix	test*	Ignores files starting with the prefix
Wildcard suffix	*config	Ignores files ending with the suffix
Directory name	node_modules, .cache	Ignores directories and all their contents

Example config:

{
  "paths": ["src"],
  "ignores": [
    "*.test.ts",
    "*.spec.ts",
    "*.snap",
    ".env",
    ".env.local",
    "coverage",
    "__mocks__"
  ]
}

Auto-ignored items — ZigZag automatically skips these common directories and files without any configuration:

node_modules, .git, .svn, .hg, .cache, __pycache__, .pytest_cache, target, build, dist, .idea, .vscode, .DS_Store, zig.conf.json

Binary file detection also runs automatically. Files are excluded by extension (images, archives, executables, media, fonts, compiled files, databases) and by content analysis (checking for null bytes and non-printable character ratios in the first 512 bytes).

Tutorial: Upload to ZagForge

Push your scan result to ZagForge after the report is written using the --upload flag:

zigzag run --upload

Authentication — the API key is discovered in this order:

1. ZAGFORGE_API_KEY environment variable
2. ~/.zagforge/credentials file containing a ZAGFORGE_API_KEY=zf_pk_… line

Watch mode behaviour — when --upload is active in watch mode, ZigZag uploads the initial snapshot once after the first scan completes. It does not re-upload on subsequent file changes.

Timeout — upload requests time out after 30 seconds. If the request fails, an error is printed to stderr and the watch loop continues.

--upload only works with the run subcommand. Using it in flag-only mode (without run) has no effect and prints a warning.

Config file setup:

{
  "paths": ["src"],
  "upload": false
}

Tutorial: Caching

ZigZag's caching system speeds up repeated runs by only reprocessing files that have changed.

How it works:

• Cache persists between runs in .cache/files/ relative to your working directory
• Uses file metadata (modification time and size) for change detection
• Performs atomic updates to prevent corruption
• Validates on startup and removes stale entries

Performance tips:

1. Keep cache enabled — Don't use --skip-cache unless you need a clean rebuild
2. Tune thresholds — Adjust --small and --mmap for your file size distribution
3. Use ignore patterns — Exclude unnecessary files early to reduce processing
4. Let parallel processing help — Worker count is auto-detected from CPU cores

To force a fresh rebuild (for example, after changing ignore patterns):

zigzag run --skip-cache