hello-env#

• Version: 1.0.2
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/better-agent-skills

A zero-dependency Bash health check for any dev environment — host, container, or K8s pod.

一个零依赖的开源环境自检脚本，适用于本地、容器、K8s Pod 环境。

Pure bash. No Python, no npm, no third-party packages. Works on macOS, Linux, and inside containers.

Compatibility#

PlatformStatusLinux (any distro)✅ FullmacOS (bash 3.2.57+ default)✅ Full — uses eval-based indirect var expansion for bash 3.xWindows (WSL / WSL2)✅ Full (effectively Linux)Windows (Git Bash / MSYS / Cygwin)⚠️ Partial — OS/user/tools/network checks work; cgroup container detection and PVC monitoring are skipped (Linux-only kernel features)Windows (PowerShell / cmd)❌ Not supported by design (bash script)Agent PlatformStatusClaude Code✅ Standard SKILL.md, drops inCodex✅ SameOpenClaw✅ Native formatCursor / Cline / others✅ Generic Markdown + bash, no platform hooks

---

Quick start#

bash

# Run with defaults (current directory as workdir, default K8s probe vars)
bash scripts/check-env.sh

# Custom workdir
bash scripts/check-env.sh --workdir /opt/myapp

# Probe extra environment variables (comma-separated)
bash scripts/check-env.sh --probe-env "MY_REGION,MY_TIER,DEPLOY_ENV"

# Force PVC monitoring (when K8s probe vars are absent but you still want it)
bash scripts/check-env.sh --force-pvc

# Combine
bash scripts/check-env.sh \
  --workdir /opt/myapp \
  --watch-dir /opt/myapp/plugins \
  --config /etc/myapp/config.json \
  --probe-env "MY_REGION,MY_TIER" \
  --force-pvc

---

What it checks#

#ModuleOutput1OSmacOS / Linux distro + version2Current Userwhoami + UID/GID3Node.jsPath ( which node) + version4Python3Path + version5Basic Toolsgit, curl, jq, docker, make — present / missing6NetworkHostname + IP + inferred private subnet (10.x / 172.16-31.x / 192.168.x)7Container / K8sProbes configurable env vars; defaults to KUBERNETES_SERVICE_HOST + K8S_NAMESPACE; falls back to /.dockerenv / cgroup heuristics8WorkdirPath exists + git initialized check9Config fileOnly checked if --config <path> provided10PVC persistenceMount device-number + watch-dir count snapshot diff (auto when K8s probe hits, or --force-pvc)

Output legend: ✅ ok · ℹ️ info · ⚠️ warning · ❌ failure

---

CLI flags#

FlagDefaultDescription--workdir <path>``pwdWorking directory to check (existence + git init)--watch-dir <path>``<workdir>Directory whose subfolder count is snapshotted for PVC monitoring--config <path>_(unset)_Optional config file to check existence--probe-env "A,B,C"``KUBERNETES_SERVICE_HOST,K8S_NAMESPACEComma-separated env vars to probe for container/K8s context--force-pvcoffForce PVC monitoring even when no K8s indicator is found--snapshot-dir <path>``<workdir>/.hello-envWhere to store device/count snapshots-h, --help—Show inline help

---

Environment variables (lower priority than CLI flags)#

VariableEquivalent flagHELLO_ENV_WORKDIR``--workdir``HELLO_ENV_WATCH_DIR``--watch-dir``HELLO_ENV_CONFIG``--config``HELLO_ENV_PROBE_ENV``--probe-env``HELLO_ENV_FORCE_PVC=1``--force-pvc``HELLO_ENV_SNAPSHOT_DIR``--snapshot-dir

---

PVC remount detection (why this matters)#

K8s PersistentVolumes can silently get reattached to a fresh disk during pod restarts or node failover. Symptoms users typically see:

"All the files I created yesterday are gone after the pod restarted."

This script catches it early by snapshotting on each run:

• <snapshot-dir>/last-device — the mount device for <workdir>
• <snapshot-dir>/last-watch-count — find <watch-dir> -maxdepth 1 -mindepth 1 -type d | wc -l

Next run decides:

DeviceWatch-dir countVerdictchangedany⚠️ Likely PVC remountunchangeddecreasedℹ️ Probably manual removalunchangednot decreased✅ Healthy

When PVC monitoring activates:

• Any of the env vars listed in --probe-env is set, OR
• --force-pvc / HELLO_ENV_FORCE_PVC=1 is on

If neither, you get a hint:

ℹ️ Not detected as containerized environment. Use --force-pvc to enable PVC monitoring anyway.

---

Examples#

CI runner sanity check#

bash

bash scripts/check-env.sh --workdir "$CI_PROJECT_DIR" --probe-env "CI,GITLAB_CI,GITHUB_ACTIONS"

K8s pod with custom labels#

bash

bash scripts/check-env.sh \
  --probe-env "KUBERNETES_SERVICE_HOST,K8S_NAMESPACE,MY_REGION,MY_TIER" \
  --watch-dir /workspace/plugins

Local Docker container without K8s#

bash

bash scripts/check-env.sh --force-pvc --workdir /app

---

Exit codes#

• 0 — All checks ran (warnings allowed)
• Non-zero only on argument parsing errors

This is a diagnostic tool, not a gate. It reports — it doesn't block.