See what a command actually changed—not what it claimed it changed.
SideEffectMap snapshots a directory, runs one command without a shell, snapshots again, and emits a deterministic map of created, modified, and deleted files.
python -m pip install -e .
sideeffectmap run --root . -- python examples/write_demo.pyThe JSON report includes:
- command exit code, duration, timeout state, stdout, and stderr;
- before/after hashes, sizes, and modes for every changed file;
- a compact change summary;
- an
effects_sha256fingerprint for comparison across runs.
Audit a formatter:
sideeffectmap run --root . --output formatter-effects.json -- ruff format .Fail CI if a supposedly read-only command writes anything:
sideeffectmap run --root . --fail-on-change -- python scripts/inspect.pyIgnore generated paths:
sideeffectmap run --root . --exclude coverage --exclude '*.log' -- npm testExit codes preserve the wrapped command's exit code. 10 means --fail-on-change found a write; 124 means timeout; 2 means invalid input.
- Black-box measurement works with scripts, CLIs, build tools, and agent tools.
shell=False: the command is executed as the argument vector shown in the report.- Small files are content-hashed; large files are still tracked by size and mode.
- Common dependency and VCS directories are ignored by default.
- No runtime dependencies and no daemon.
Version 0.1 measures regular-file changes beneath the selected root. It does not claim to trace network calls, kernel activity, registry writes, or files outside that root. Run untrusted commands inside a real sandbox; SideEffectMap is an observer, not containment.
python -m pip install -e .
python -m unittest discover -s tests -vCreated and maintained by SamAlpha1. The canonical origin is SamAlpha1/SideEffectMap; see .provenance/origin.json, NOTICE, and the immutable Git history.
MIT licensed. Copies must preserve the copyright and license notice.