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

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.

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:

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:

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

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

6. Container Detection

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:

Cloud & Hosting CLIs:

Container Tools:

Developer Tools:

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.

   # 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
   

2. 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.
3. Check once, reference often. Store results in your working context. Do not re-probe mid-session unless the user installs something new.
4. 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:

When to Probe vs Assume

Cognitive Traps

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.