Environment Awareness

Environment Awareness

Overview

The most common AI agent failure mode: running Linux commands on Windows, using npm when the project uses pnpm, ignoring active virtual environments. Every wrong command wastes time and can cause real damage.

Core principle: DETECT the environment before issuing ANY shell command. One probe now prevents ten failed commands later.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO SHELL COMMANDS WITHOUT KNOWING THE TARGET ENVIRONMENT

If you have not confirmed OS, shell, and package manager, you are not authorized to run commands.

When to Use

Mandatory at session start:

• First interaction in any new conversation
• Switching to a different project or repository
• After entering a container, VM, or remote machine

Also required when:

• A command fails with "not found" or "not recognized"
• Installing dependencies or running build scripts
• Writing platform-specific code (file paths, process management, networking)
• Diagnosing "works on my machine" problems

Do not skip when:

• You think you already know the environment (verify, do not assume)
• The user mentions their OS casually (confirm shell and toolchain too)
• Working in CI/CD (runners have different environments than local machines)

The Entry Protocol

BEFORE running any shell command:

1. PLATFORM: Have you confirmed OS and architecture?
2. SHELL: Do you know which shell is interpreting your commands?
3. PACKAGE MANAGER: Have you checked for lockfiles?
4. RUNTIMES: Do you know which language runtimes are available?
5. VIRTUAL ENV: Are there active virtual environments or version managers?

If any answer is NO: probe first, command second.

Detection Flowchart

digraph env_detect {
    rankdir=TB;
    node [shape=box, style=filled, fillcolor="#e8e8e8"];

    start [label="Session Start", shape=oval, fillcolor="#ccffcc"];
    os [label="1. Detect OS\nprocess.platform\nor uname", shape=diamond, fillcolor="#ffffcc"];
    shell [label="2. Detect Shell\n$SHELL / $PSVersionTable\n/ COMSPEC", shape=diamond, fillcolor="#ffffcc"];
    pkg [label="3. Detect Package Manager\nCheck lockfiles\nin project root", shape=diamond, fillcolor="#ffffcc"];
    runtime [label="4. Detect Runtimes\nnode/python/go\n--version", shape=diamond, fillcolor="#ffffcc"];
    venv [label="5. Check Virtual Envs\nVIRTUAL_ENV / CONDA\nnvm / rbenv", shape=diamond, fillcolor="#ffffcc"];
    container [label="6. Container Check\n/.dockerenv\nor cgroup", shape=diamond, fillcolor="#ffffcc"];
    ready [label="Environment Known\nProceed with\ncorrect commands", shape=oval, fillcolor="#ccffcc"];

    start -> os -> shell -> pkg -> runtime -> venv -> container -> ready;
}

Detection Checklist

Run this sequence once per session. Results inform every subsequent command.

1. Operating System

| Method | Works On | Command | |--------|----------|---------| | Environment variable | Claude Code / Node | Check process.platform in tool context | | uname | Linux, macOS, Git Bash | uname -s | | System info | Windows (any shell) | systeminfo or ver |

Key distinctions:

• win32 = Windows (regardless of 32/64-bit)
• darwin = macOS
• linux = Linux or WSL (check further with grep -i microsoft /proc/version for WSL)

2. Shell

NEVER assume bash. Windows alone has CMD, PowerShell, Git Bash, and WSL.

| Check | Command | Reveals | |-------|---------|---------| | Shell variable | echo $SHELL | Default shell (Unix) | | PowerShell test | $PSVersionTable | PowerShell version | | Process name | echo $0 | Current shell (Unix) | | COMSPEC | echo %COMSPEC% | CMD path (Windows) |

Critical: On Windows, the Claude Code / AI agent shell context is often Git Bash, but the user's terminal may be PowerShell. Commands you generate for the user to copy must match THEIR shell.

3. Package Manager

Detection priority -- check lockfiles first:

| Lockfile | Package Manager | |----------|----------------| | bun.lockb or bun.lock | bun | | pnpm-lock.yaml | pnpm | | yarn.lock | yarn | | package-lock.json | npm |

If no lockfile found:

1. Check packageManager field in package.json
2. Check for global install: which pnpm || which yarn || which bun
3. Default to npm only as last resort

For non-JS projects: | File | Manager | |------|---------| | Pipfile.lock | pipenv | | poetry.lock | poetry | | uv.lock | uv | | requirements.txt | pip | | go.sum | go modules | | Cargo.lock | cargo | | Gemfile.lock | bundler |

4. Runtime Versions

Probe on first use, not eagerly. Only check what the project actually needs.

node --version      # Node.js
python3 --version   # Python (use python3, not python, on macOS/Linux)
go version          # Go
rustc --version     # Rust
java --version      # Java
ruby --version      # Ruby

5. Virtual Environments

| Signal | Indicates | |--------|-----------| | $VIRTUAL_ENV is set | Python venv/virtualenv active | | $CONDA_DEFAULT_ENV is set | Conda environment active | | .python-version file | pyenv version pinned | | .nvmrc or .node-version file | Node version pinned | | .ruby-version file | rbenv/rvm version pinned | | .tool-versions file | asdf version manager |

When a version manager is detected: Use its commands (nvm use, pyenv shell) instead of assuming the global runtime is correct.

6. Container Detection

| Check | Inside Container? | |-------|-------------------| | /.dockerenv exists | Docker | | grep -q container /proc/1/cgroup 2>/dev/null | Docker/Podman | | $container env var is set | Podman | | printenv KUBERNETES_SERVICE_HOST | Kubernetes pod |

System Inventory

After confirming the platform and shell, discover what tools, databases, cloud CLIs, and services the user has installed. This inventory feeds directly into planning -- if the user has SQLite but not PostgreSQL, or Docker but not Podman, downstream skills like deployment-advisor and task-planning can make smarter recommendations instead of guessing.

When to Run

• Always: Git, GitHub CLI (needed by many GodMode skills)
• If the project touches data: Database CLIs
• If the project will be deployed: Cloud and container tools
• If the project processes media or structured data: ffmpeg, jq, curl
• Never run the full list blindly. Match checks to project type. A static site does not need a MongoDB probe.

Inventory Checks

Run each relevant check silently, redirecting stderr so missing tools do not produce noise:

Databases:

| Tool | Check | Notes | |------|-------|-------| | PostgreSQL | psql --version 2>/dev/null | Check for pg_dump too if backups matter | | MySQL / MariaDB | mysql --version 2>/dev/null | MariaDB identifies itself in the version string | | SQLite | sqlite3 --version 2>/dev/null | Often pre-installed on macOS and Linux | | MongoDB | mongod --version 2>/dev/null | Also check mongosh for the modern shell | | Redis | redis-server --version 2>/dev/null | Also check redis-cli |

Cloud & Hosting CLIs:

| Tool | Check | |------|-------| | AWS CLI | aws --version 2>/dev/null | | Google Cloud | gcloud --version 2>/dev/null | | Azure CLI | az --version 2>/dev/null | | Vercel | vercel --version 2>/dev/null | | Supabase | supabase --version 2>/dev/null | | Fly.io | fly version 2>/dev/null | | Netlify | netlify --version 2>/dev/null | | Railway | railway --version 2>/dev/null |

Container Tools:

| Tool | Check | |------|-------| | Docker | docker --version 2>/dev/null | | Docker Compose | docker compose version 2>/dev/null | | Podman | podman --version 2>/dev/null |

Developer Tools:

| Tool | Check | |------|-------| | Git | git --version 2>/dev/null | | GitHub CLI | gh --version 2>/dev/null | | curl | curl --version 2>/dev/null | | jq | jq --version 2>/dev/null | | ffmpeg | ffmpeg -version 2>/dev/null |

Reporting Format

Report findings concisely. Do not dump raw version output -- extract the version number and summarize:

Available: PostgreSQL 16.2, Docker 27.1, gh 2.45, SQLite 3.43
Not found: Redis, AWS CLI, Podman

Principles

1. Silence errors and force exit code 0. Always redirect stderr to /dev/null AND append ; true at the end of chained version checks. Missing tools produce non-zero exit codes that surface as red errors in Claude Code. A missing tool is information, not a failure — the output must never show red.

```bash # WRONG: last missing tool causes exit 127 (red error in Claude Code) psql --version 2>/dev/null; redis-server --version 2>/dev/null; mongod --version 2>/dev/null

# RIGHT: force clean exit regardless of which tools are missing psql --version 2>/dev/null; redis-server --version 2>/dev/null; mongod --version 2>/dev/null; true ```

1. Scope to project. Only check categories relevant to the codebase. Read the project's config files, Dockerfile, CI config, or deployment manifests to decide what matters.
2. Check once, reference often. Store results in your working context. Do not re-probe mid-session unless the user installs something new.
3. Feed downstream skills. The inventory directly informs deployment-advisor (what can we deploy to?), task-planning (what constraints exist?), and project-bootstrap (what do we need to install?).

Platform-Specific Command Mappings

Use the correct command for the detected environment:

| Operation | Linux/macOS | Windows CMD | Windows PowerShell | Git Bash on Windows | |-----------|-------------|-------------|-------------------|-------------------| | List files | ls -la | dir | Get-ChildItem | ls -la | | Find process | ps aux \| grep | tasklist | Get-Process | ps aux \| grep | | Set env var | export VAR=val | set VAR=val | $env:VAR = "val" | export VAR=val | | Null device | /dev/null | NUL | $null | /dev/null | | Path separator | : | ; | ; | : | | Delete file | rm file | del file | Remove-Item file | rm file | | Find files | find . -name | dir /s /b | Get-ChildItem -Recurse | find . -name | | Check port | lsof -i :PORT | netstat -an | Get-NetTCPConnection | netstat -an |

When to Probe vs Assume

| Category | Action | Reason | |----------|--------|--------| | OS | ALWAYS probe | Affects every command's syntax | | Shell | ALWAYS probe | Determines quoting, piping, redirection | | Package manager | ALWAYS probe | Wrong manager corrupts lockfile | | Runtime versions | Probe on first use | Only matters when running that runtime | | Virtual environments | Probe when relevant | Wrong env installs to wrong location | | Container | Probe when behavior is unexpected | Containers lack many host tools |

Cognitive Traps

| Rationalization | What Is Actually True | |----------------|----------------------| | "It's probably Linux" | 30% of developers use Windows. macOS is another 25%. Probe first. | | "bash is universal" | Windows CMD and PowerShell have fundamentally different syntax. Git Bash exists but is not guaranteed. | | "npm is the default" | Using npm in a pnpm project corrupts the lockfile and breaks CI. | | "I'll fix it if the command fails" | A failed rm -rf with wrong path syntax can still delete data. Failed installs leave broken state. | | "The user said Windows, so PowerShell" | Could be CMD, Git Bash, WSL, or Cygwin. Confirm the shell, not just the OS. | | "CI and local are the same" | CI runners use different OS, different shell, different tool versions. Probe there too. |

Guardrails -- HALT and Detect

Stop and run detection if you catch yourself:

• Running ls without knowing if the shell supports it
• Using /dev/null without confirming Unix-like shell
• Running npm install without checking for other lockfiles
• Using python instead of python3 without version checking
• Assuming ~ expands correctly (it does not in CMD)
• Writing path strings with / without confirming OS
• Using grep flags without confirming GNU vs BSD
• Piping commands without knowing if the shell supports |

Every item on this list means: halt command execution. Probe first.

Integration

Complementary skills:

• godmode:project-bootstrap -- Environment detection runs during project setup
• godmode:fault-diagnosis -- Environment mismatch is a common root cause of mysterious failures
• godmode:workspace-isolation -- Worktree and container setup needs correct platform commands
• godmode:deployment-advisor -- System inventory results feed directly into deployment recommendations and platform selection

The Bottom Line

One detection probe now > ten failed commands later

Know the OS. Know the shell. Know the package manager. Before the first command. Every single session.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NoobyGains
• Source: NoobyGains/godmode
• License: MIT

Install and usage instructions live in the source repository linked above.