Skip to main content

Documentation Index

Fetch the complete documentation index at: https://filepacks.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Repeated workflows usually emit plain directories. That is easy to produce, but awkward to trust:
  • a directory has no stable artifact identity
  • verification is improvised
  • comparison depends on whatever diff tool you reach for
  • handoff often loses the exact context of what was packaged
filepacks fixes that by turning the directory into a deterministic .fpk archive with a canonical manifest.

​
The problem with loose directories

Suppose a baseline run and a candidate run both produce: 
outputs/results.json
outputs/summary.txt
Without an artifact boundary, you still have to answer:
  • what exactly was included in the snapshot?
  • are the files still byte-for-byte what was originally captured?
  • which files changed between runs?
Without an artifact boundary, those answers usually come from a mix of shell commands, ad hoc logs, screenshots, or local conventions.

​
What filepacks adds

filepacks gives you one portable file and a small repeatable workflow: 
npx filepacks pack ./outputs --output ./run.fpk
npx filepacks inspect ./run.fpk
npx filepacks verify ./run.fpk
npx filepacks compare ./baseline.fpk ./run.fpk
That workflow gives you:
  • a single .fpk file as the portable artifact boundary
  • manifest.json as the canonical file inventory
  • deterministic archive construction for stable bytes
  • local verification against recorded file sizes and hashes
  • structural comparison between baseline and candidate artifacts

​
Why determinism matters

If the same logical input produces the same artifact bytes, the archive digest becomes a meaningful identity for the packaged output. That helps with:
  • reproducible review
  • baseline-versus-candidate workflows
  • durable evidence capture in CI
  • human review grounded in concrete files
  • agent workflows that need deterministic evidence instead of ambiguous text summaries

​
Why this helps agents and evals

When an AI coding agent or eval runner produces output files, those outputs often need to survive beyond the original process. Packing them into a .fpk artifact makes them:
  • portable enough to hand to another person or agent
  • inspectable later without recreating the run
  • comparable against an accepted baseline
  • verifiable before use in review or automation
Example: 
npx filepacks pack ./agent-output --output ./run-42.fpk
npx filepacks compare ./run-41.fpk ./run-42.fpk
compare exits 0 if nothing changed and 20 if any packaged file changed. That is enough for a CI job, harness, or review bot to distinguish “same output” from “needs review”.

​
Why not just use tar, zip, screenshots, or logs?

Generic tools can capture files, but they do not define the public filepacks contract:
  • manifest.json must be first
  • payload files must live under payload/
  • directory entries are not allowed
  • paths must be normalized relative paths
  • tar header metadata is fixed for deterministic output
  • verification and comparison are part of the intended workflow
Screenshots and logs can help with explanation, but they are not a deterministic artifact format. They do not tell you exactly which files were packaged, how they hash, or whether a later copy still matches the original output.

​
Why filepacks stays narrow

The current OSS surface is intentionally conservative. It focuses on packaging, inspection, verification, and comparison of deterministic file evidence. It is not trying to be:
  • a cloud platform
  • a storage sync layer
  • a registry service
  • a general workflow engine
  • a replacement for Git

​
Where it fits

filepacks is a good fit when you want generated output to stay reviewable and portable without introducing a larger hosted system. That includes:
  • agent run outputs
  • eval artifacts that are just file trees
  • CI-generated reports and build outputs
  • regression bundles for baseline/candidate review
For concrete examples, continue to Use cases and Agent workflows.