Environment Inspection

Overview

Collect a quick, machine-readable snapshot of the current workspace so agents know operating constraints, dev tooling, and where to look first for context.

Quick Start

Generate JSON (default):

python scripts/inspect_environment.py

Readable text:

python scripts/inspect_environment.py --format text

Key fields:

• os: system, release, version, machine
• shell: detected shell/command host
• environment: container hint, WSL flag, VM hint (via systemd-detect-virt when available)
• git: repo presence, root, branch, upstream, dirty state
• python: interpreter path/version, active venv/conda, whether running inside a venv
• virtualenv_dirs: nearby .venv/venv/env folders
• markdown_dirs: directories (depth-limited) containing .md files worth skimming
• tools: availability of common CLIs (uv, mcpc, rg/grep/jq/git/python/node/npm/pnpm, etc.)

Options

• --root PATH to inspect a different directory (default: cwd).
• --format json|text for programmatic vs quick-read output (default: json).
• --md-limit N / --md-depth N to cap markdown directory discovery (defaults: 40 dirs, depth 5; skips .git/node_modules/.venv/venv/.tox/dist/build/.cache).
• --extra-tool NAME (repeatable) to probe additional binaries.

Notes and Heuristics

• Container detection uses marker files and /proc/1/cgroup; WSL is reported separately.
• VM detection is opportunistic via systemd-detect-virt; missing tools yield null.
• Git checks are no-op outside a repo and never modify state.
• Traversal is pruned to avoid heavy dirs; adjust limits if you need more coverage.