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