Usage

Map a directory

undomap                    # current directory
undomap ~/code             # a folder of many repos: each repo is surveyed with git
undomap . --fix            # cheapest fix under every Zone VE place
undomap . --all            # every Zone VE place, not just the top 12

The report leads with Zone VE: {bytes} across {n} places your agent can erase forever, biggest first. Secrets (.env, keys, credentials) are always listed, even when they're small. Zone AE and Zone X follow, then the probes that were run.

Fixes

Each permanent place gets one fix, the cheapest that actually protects it. A few examples:

Finding	Fix
untracked, small	`git add -- notes && git commit`
gitignored, small	tarball outside the tree (it's ignored on purpose, so don't commit it)
secret-looking	copy to a password manager or `~/.config`
over 25 MB, or a binary/media file over 2 MB	`rsync` to somewhere the agent can't write, plus snapshots
folder outside git	`git init && git add -A && git commit`
repo with no remote	`git bundle create ~/repo.bundle --all`
symlink out of the tree	map the target too, or replace the link with a copy
inside a sync folder undomap can't verify	the same fix, tagged "possible Dropbox versioning, unverified", plus one line per folder with the cheapest check (start the app, install `attr`, …)

When no snapshot probe covers the map, one machine-level fix is added at the end: Time Machine, snapper or ZFS, or File History.

JSON and Markdown

undomap --json > undomap.json      # also drop it on the landing page to draw your own map
undomap --markdown >> "$GITHUB_STEP_SUMMARY"

Exit codes in scripts

undomap ~/agent-workspace || echo "something in Zone VE"
undomap . --max-permanent 1MB      # tolerate small things

GitHub Action

Useful before an agent step on a self-hosted runner, a mounted volume or a long-lived dev box. On a fresh checkout everything is tracked, so the Action matters where state persists.

- uses: Blackman99/undomap@v0
  id: map
  with:
    path: .                    # default
    fail-on-permanent: true    # default; false = warn only
    max-permanent: 0           # bytes allowed, e.g. 10MB
- run: echo "permanent=${{ steps.map.outputs.permanent-bytes }}"

Outputs: permanent-bytes, permanent-places, slow-bytes, json. The job summary gets the Zone VE table.

MCP server

claude mcp add undomap -- npx -y github:Blackman99/undomap mcp

// Cursor / Cline / any MCP client
{ "mcpServers": { "undomap": { "command": "npx", "args": ["-y", "github:Blackman99/undomap", "mcp"] } } }

Two read-only tools, map_report and list_permanent. Both take path, which defaults to the server's working directory. A good instruction for your agent: before rm -rf, git clean -fdx, git reset --hard or a checkpoint restore, call list_permanent on the workspace.

map_report also takes reach: true for the credential reach section, measured for the environment the server runs in, which is the agent's own.

Credential reach (lethal trifecta)

undomap --reach

A deletion is bad. A deletion by an agent that can also read your keys, reach the network and write outside the project can be an exfiltration. --reach adds one section that checks those three conditions for the process running undomap:

credentials: credential-looking files in the tree (.env, keys, credentials*.json, secrets/), well-known files in your home folder (~/.aws/credentials, gcloud, Azure, ~/.kube/config, Docker, gh, ~/.git-credentials, ~/.netrc, ~/.npmrc, ~/.ssh/id_*…) and set environment variables whose name looks like a credential (*_TOKEN, *_API_KEY, *_SECRET, AWS_SECRET_ACCESS_KEY, SSH_AUTH_SOCK…);
network: a non-loopback interface with an address. No connection is attempted, so a firewall can still block what this calls open;
write out: your home folder, the folder above the tree, or a symlink target outside it, writable by this process.

Values are never read. Files are only stated and checked with access(); they are never opened. For environment variables only the name is kept. Run it the way your agent runs (same user, same sandbox, or through the MCP server) to measure the agent's reach rather than yours. When all three are present, the fix is to break one leg; undomap prints the cheapest one it can see. --reach never changes the exit code.

Next sheet: Configuration