TLDR: A coding agent is a pilot with no instruments. It flies a repository for hours with no sense of who is in the cockpit, what machine it is on, what time it is, how much fuel is left, or whether the ground just moved. Situational awareness is the instrument panel: a set of signals injected into the context that tell the agent where it is and what changed. Some instruments exist. Most are missing. Here is the taxonomy, how to build each sense, and who already does.
–Martin, coding agent operator but also paraglider/glider pilot.
Definition
Situational awareness comes from aviation. Endsley’s classic definition (Toward a Theory of Situation Awareness in Dynamic Systems, Human Factors 1995): “the perception of the elements in the environment within a volume of time and space, the comprehension of their meaning, and the projection of their status in the near future.” Three levels: perceive, understand, anticipate.
A coding agent’s “volume of time and space” is the working directory, the session, and the machine. Its sensors are whatever the harness decides to inject into the context. Everything not injected does not exist. The transformer has no proprioception: it knows only what is written in the tokens.
1. User Awareness — who is this human
The agent talks to one person for weeks and knows nothing about them by default. Every session starts from zero: same tone for the novice and for the committer on the project, same verbosity for the terse and the expansive, no memory of past corrections.
The fix is a user block, injected at session start: name, git identity, email, communication preferences (“be terse”, “no trailing summaries”), conventions (“pytest exclusively”, “never force-push”). Two complementary sources:
- the dossier written by the user: explicit, reviewable, diffable
- the dossier written by the agent: accumulated from corrections and preferences across sessions
Who does it. Claude Code: the system prompt’s environment block carries the user’s name and git identity, and commits are signed accordingly. On top of that, CLAUDE.md files (project-, user-, org-level, loaded into every session) are the user-written dossier, and auto memory — notes Claude writes itself from “your corrections and preferences” — is the agent-written one. ChatGPT and Cursor have similar preference memories on the chat side.
2. System Awareness — where am I running
The model’s training data is full of generic Linux. The actual
machine is specific: which OS, how much RAM, which tools are installed,
what the paths are. Guessing instead of knowing produces the classic
failure: brew install on a Debian box, apt-get
in an Alpine container.
The fix is an environment block, injected at session start. The minimum viable instrument: working directory, platform, OS version, today’s date, model name. The valuable part is beyond the minimum — facts that are unguessable and machine-specific:
- which local binaries are the sanctioned tools
- hardware facts that change behavior: RAM, CPU cores, GPU present or not
- the one working notification path, the one working screenshot path
- paths the agent must never guess (home is not always
/home/user)
A dozen lines removes an entire class of hallucinated-environment bugs. Cheapest sense to build, highest hit rate.
Who does it. Claude Code injects the minimal block
(working directory, platform, OS version, date, model). Beware the Agent
SDK trap: the claude_code preset carries “context about the
working directory and environment”, the minimal default preset omits it
(modifying
system prompts).
3. Git Awareness — what state is the code in
Git is the agent’s ground truth for “what exists” and “what happened”. A fresh session without git awareness edits blind: it does not know the branch, whether the tree is dirty, or that the last five commits were all reverts of what it is about to reimplement.
The fix is git state in the context: branch,
git status, git log --oneline -5 at session
start — three shell commands. Two refinements:
- Re-inject regularly. Two hours and forty tool calls into a session, the branch may have changed (the user, a teammate, a CI job). A snapshot taken once goes stale while the agent reasons from it with full confidence.
- Tell the agent its own footprint. “You have touched these 7 files this session” is the single most useful git fact for a long task.
- For structural awareness of the codebase itself — which symbols live where, what calls what — the reference design is a ranked, token-budgeted repo map sent.
Who does it. Claude Code injects a
gitStatus block at session start (branch, status, recent
commits) — once, no refresh, no own-footprint. Aider ships the repo map
(docs): a
graph-ranked map of the repository’s key symbols within a
--map-tokens budget, updated per request.
4. Time Awareness — what time is it, how long did that take
Agents estimate durations in human-weeks and execute in machine-minutes — the anthropocentric time bias — and they have no clock at all: turn 3 and turn 30 look identical.
The fix is elapsed time in the context, every turn: three numbers per turn — session elapsed, last tool duration, wall time since the previous message — plus a timestamp on every tool result. That is the closest thing to temporal proprioception you can retrofit. Prompting alone (“you are fast”) decays across a long context; the harness must re-assert every turn.
Who does it. agentknit does: every turn opens with a session-elapsed line and every tool result carries a timestamp with start, end and duration. In general it takes a few hook lines (UserPromptSubmit/PreToolUse wrappers). Full treatment and evidence in Coding Agents Have Completely Wrong Sense of Time.
5. Token Awareness — how much fuel is left
The model cannot feel its context filling up. Without a counter, it discovers the budget when it hits the wall — truncated mid-sentence.
The fix is a model-facing counter: consumed and remaining,
injected after every tool call. Not a /context
command for the human; a number the model reads and plans around. The
operational rules: show the number, never show a scary number,
over-provision on purpose, and never lie about the count.
Who does it. The Claude API ships it by default
(<system_warning>Token usage: 35000/200000</system_warning>
after each tool call); Codex CLI has it behind a flag. Cognition’s Devin
report documents the side effect, “context anxiety”: the model wraps up
early and takes shortcuts when it believes the window is nearly full.
Full treatment in Token
Awareness.
6. Change Awareness — what moved while I was working
The least developed sense, and the one that bites hardest in long sessions. The agent builds a mental model of the files at read time. Then the world moves: the user edits in their editor, a formatter runs, a background process the agent itself spawned writes to disk, a teammate pushes. The agent’s model of the file is now wrong, and nothing tells it.
The fix, per Endsley’s three levels:
- Perceive: watch the working tree (inotify/FSEvents) and stream file-change events into the context as they happen, with provenance when determinable — at minimum “changed by a process outside this session’s tool calls”.
- Comprehend: attach information (eg number of changed lines, or even the diff), to the next turn.
- Project: re-read before writing and reconcile — “the user just rewrote the function I was about to patch; my plan is stale.”
The write side of this problem is the lost-update problem — see Live Sync Between Humans and AI Agents: two writers, one file, last write wins. Awareness comes before collision: the agent should know the ground moved before it lands the next write.
Who does it. Half of level 1, badly. Claude Code detects that a file changed between read and edit and injects a system note with a diff — but the note asserts the change came from “the user or a linter” and instructs the model not to mention it because “they are already aware” (issue #71585). The harness confabulates provenance. Change awareness without provenance awareness manufactures false certainty.
Design Principles
Across the six senses, the same three rules recur:
- Injected, not queried. A sense that requires the agent to remember to check is not a sense. Every working example (token counter, environment block, per-turn timestamps) is pushed by the harness. Prompting decays across a long context; the harness re-asserts.
- Numbers, not adjectives. “You are fast” doesn’t work; “~1 tool call/second, boot takes ~2 min” does. “Budget is low” produces anxiety; “165000 remaining” produces planning.
- Awareness without calibration is a bug. A padded token counter (Claude Code’s default reports 15M tokens on a 200k window), a change note with invented provenance, a stale git snapshot — each is worse than silence, because the model trusts injected facts absolutely. A sensor that lies is worse than no sensor.
Google Labs’ Situationally Aware Agents makes a similar point from the product side: “Having massive context isn’t enough if the agent doesn’t know what actually matters to your current state of work.”