envoic - Environment Scanner and Cleanup Skill

Use envoic to discover and safely clean Python virtual environments, node_modules, and development artifacts.

Quick Start

uvx envoic scan .
uvx envoic manage . --dry-run
npx envoic scan . --deep

If uvx is unavailable, install Python package with pip install envoic. If npx is unavailable, install JS package with npm install -g envoic.

Primary Workflows

1) Onboarding Health Check

1. Run uvx envoic info .venv (or npx envoic info node_modules).
2. If environment is broken or stale, propose delete-and-recreate steps.

2) Disk Space Recovery

1. Run uvx envoic scan <root> --deep and/or npx envoic scan <root> --deep.
2. Identify largest stale candidates.
3. Run manage --dry-run, then actual cleanup only after confirmation.

3) Build/Test Artifact Cleanup

1. Scan project root.
2. Prefer deleting SAFE artifacts first.
3. Warn for CAREFUL artifacts.

Safety Contract

1. Always scan before delete.
2. Prefer --dry-run before destructive operations.
3. Never delete lock files or project manifest files.
4. Require explicit user confirmation for non-dry-run cleanup.

See full policy in references/safety.md.

Verified Trigger Phrases

• "Find and remove stale virtualenvs"
• "Clean old node_modules and caches"
• "I hit ENOSPC, free up disk from dev artifacts"
• "Audit environment sprawl in this workspace"
• "Check if this .venv is broken"
• "List largest build artifacts"
• "Dry-run cleanup plan for Python and JS"
• "Find dangling venv symlinks"
• "Clean test/build caches safely"
• "Generate JSON report for stale environments"

References

• Full command catalog: references/commands.md
• Safety and risk tiers: references/safety.md
• Troubleshooting and fallbacks: references/troubleshooting.md

Tool-Specific Surface Files

• Codex: .agents/skills/envoic/SKILL.md (symlink/copy of this skill)
• Cursor: .cursorrules (generated adapter)
• Copilot: .github/copilot-instructions.md (generated adapter)
• Claude: .claude-plugin/plugins.yaml (generated adapter)