keeping-system-clean

Keeping System Clean

A discipline for keeping the user's machine clean. Every transient dependency and scratch file from one-off, project-independent tasks goes into one predictable home-directory sandbox, never into the global Python/Node environment and never scattered across the filesystem.

The payoff that makes this worth a dedicated discipline: the entire footprint of all one-off work is consolidated into a single, auditable directory the user can inspect at a glance and delete in one command (rm -rf ~/.agent-sandbox). Avoiding global installs is necessary but not sufficient — tools like uvx/pipx already isolate individual installs. The distinct value here is that nothing is left to hunt down later: one folder holds it all, one command reclaims it.

The cardinal rule: never install globally, never leave clutter behind.

The golden path: prefer ephemeral runners

Before reaching for any install, ask whether the tool can run without a persistent install. For most one-shot tasks it can, and this is by far the cleanest option — it leaves literally nothing behind in any environment.

• Python one-offs → uv run --with <pkg> ... or uvx <tool>
• Node one-offs → npx -y <tool>

Examples:

# Run a Python script that needs requests + rich, zero residue:
uv run --with requests --with rich script.py

# Run a Python CLI tool one time:
uvx ruff check .
uvx --from httpie http GET https://example.com

# Run a Node CLI tool one time:
npx -y prettier --check .
npx -y cowsay "hello"

uv downloads packages into its own shared cache and assembles a throwaway environment per invocation; nothing touches the system Python or site-packages. npx -y fetches into the npm cache and runs without a global install. Reach for the persistent sandbox below only when ephemeral running won't work (you need the same env across many commands, an interactive REPL, or a long-lived dev loop).

When ephemeral won't do: the persistent sandbox

When you genuinely need a stable environment across multiple commands, use the shared sandbox in the user's home directory. Pick the right scope depending on whether the work is tied to a project:

• Project-independent / general / throwaway work → the shared common env inside ~/.agent-sandbox. This is the default this skill is about.
• Work tied to a specific repository → that repo's own .venv / node_modules, NOT this sandbox. Keep project deps with the project.

Layout

~/.agent-sandbox/                  # single root, everything lives here
├── README.md                      # written on first creation, explains the dir
├── python/
│   └── common/                    # the shared general-purpose Python venv
│       └── (venv contents)
├── node/
│   └── common/                    # shared general-purpose Node prefix
│       ├── package.json
│       └── node_modules/
├── bin/                           # symlinks/shims to tools the user wants on PATH
├── tmp/                           # scratch files, downloads, intermediate output
└── cache/                         # shared pip/npm/uv cache override (optional)

Why this shape:

• One root the user can inspect or delete wholesale (rm -rf ~/.agent-sandbox) to reclaim everything. No hunting across the system.
• python/ and node/ separated, each with a common env, leaving room to add named envs later (e.g. python/ml, python/scraping) if a recurring task needs an isolated set without polluting common.
• tmp/ is the only sanctioned place for scratch files — not ~/Desktop, not the cwd, not random /tmp litter that's hard to attribute later.
• bin/ gives a single, removable place to expose tools on PATH without sudo or touching system directories.

The exact resolution of ~ and the activation commands differ by OS. Read the matching reference file before running commands — do not guess paths:

• macOS / Linux → references/unix.md
• Windows (PowerShell + cmd) → references/windows.md

Both files cover: creating the root + README.md, creating/activating the common Python venv, setting up the common Node prefix, install commands, cache redirection, exposing tools on PATH, and teardown.

Decision flow

Need a package or scratch space?
│
├─ Is it a true one-shot command?
│     └─ YES → uv run --with / uvx   (Python)
│              npx -y                 (Node)
│              → nothing to clean up. Done.
│
├─ Does it belong to a specific repo/project?
│     └─ YES → use that project's own .venv / node_modules. Not this sandbox.
│
└─ General-purpose, reused across commands, or throwaway-but-multi-step?
      └─ Use ~/.agent-sandbox/{python,node}/common
         (read references/<os>.md for exact commands)

Operating rules

1. Never run bare pip install <pkg>, npm install -g, sudo pip, or easy_install. These mutate the system. If you catch yourself about to, stop and route through uv/npx or the sandbox venv instead.
2. Default to ephemeral (uv run/uvx/npx -y). Only create persistent sandbox envs when a single command genuinely can't do the job.
3. All scratch files go in ~/.agent-sandbox/tmp/ with a task-descriptive prefix (e.g. tmp/pdf-merge/), so the user can tell what each thing was.
4. Project deps stay with the project. Don't dump a project's requirements into common; that defeats reproducibility for that repo.
5. Detect, don't assume. Check whether uv is installed before using it; if absent, either suggest installing it (it's a single self-contained binary) or fall back to python -m venv. Likewise check for npx/node. The reference files show the detection commands.
6. Report and offer cleanup. When a task finishes, tell the user what landed in the sandbox and remind them the whole thing is disposable: "Everything I installed/created lives in ~/.agent-sandbox. Delete it any time with one command (see the README in that folder)."

First-run courtesy

The very first time you create ~/.agent-sandbox, also write the README.md described in the reference file. It documents what the directory is, why it exists, and the single command to nuke it — so months later the user (or another tool) finds a self-explaining folder instead of a mystery dotdir.