Give LLM agents (Claude in this case, but may be adaptable to others) an awareness of time in an unobtrusive way.

A developer created a time-awareness hook for LLM agents like Claude Code that injects timestamps at a human-like cadence, keeping the agent oriented in time without filling the context window with noise. The hook is rate-limited to emit a full timestamp once per hour and a short timestamp when more than five minutes have passed, using a pure function with no I/O for testability. It works with Claude Code 2.1.177 and can be wired into UserPromptSubmit and PostToolUse events via a single script.

A self-contained recipe. Read this one file and you can reproduce the whole mechanism from scratch — a human or another LLM, knowing nothing else. An LLM agent has no clock . It only knows what is in its context window. So: - Inject a timestamp on every action → the context fills with noise. - Inject one once at session start → it goes stale within minutes. The goal is to inject timestamps at a human-like cadence : frequent enough that the agent stays oriented in time and notices the passage of time — e.g. "that build took 40 minutes" , but sparse enough to be almost invisible. Claude Code hooks are external commands the harness runs on certain events. A hook can print a line of JSON of this shape: {"hookSpecificOutput":{"hookEventName":"<event ","additionalContext":"⏱ ..."}} The additionalContext string is injected into the model's context . That is the entire delivery channel: the hook prints that line, the model sees the timestamp on its next think. - Verified working on Claude Code 2.1.177 . - Every hook receives a JSON object on stdin that includes session id and hook event name plus event-specific fields . additionalContext injection works for both UserPromptSubmit and PostToolUse events the two we use . Wire the same script into two events: — fires once per user turn → tracks the UserPromptSubmit human's cadence a fresh stamp each time you talk to the agent .— fires after each tool call → tracks time during long PostToolUse autonomous runs when the human isn't typing. Both call one script which is internally rate-limited , so the vast majority of PostToolUse invocations print nothing . That is what makes it cheap to leave enabled on every tool call. The script emits one of three things: long — ⏱ Monday, June 23, 2026 10:27 PM EDT — the first emit of each wall-clock hour. short — ⏱ 10:33 PM EDT — when more than 5 minutes have passed since the last short emit. none — silent, otherwise. A long emit also resets the short timer , so you never get a long immediately echoed by a short. The decision is a pure function of four numbers, with no I/O — which makes it trivially testable: decide now epoch, now hourkey, last hourkey, last short epoch : if now hourkey = last hourkey - long new state: now hourkey, now epoch incl. first run elif now epoch - last short 300 - short new state: last hourkey, now epoch else - none state unchanged hourkey is date +%Y%m%d%H — so a new hour, a new day, or "24h later, same hour" all register as a new hour. | Part | Path | |---|---| | The script executable | ~/bin/time-awareness-hook here: a symlink into ~/dotfiles/bin/ | | The tests | ~/dotfiles/bin/test/time-awareness-hook test | | The wiring | ~/.claude/settings.json → hooks | | Per-session state | ${XDG STATE HOME:-~/.local/state}/claude-time-awareness/state-<session id | State is per session keyed on the hook's session id , so concurrent sessions don't interfere; the state file is two lines hourkey then last short epoch . Stale state files 1 day are pruned on each long emit. Save the following as an executable on your PATH e.g. ~/bin/time-awareness-hook , then chmod +x it. bash /usr/bin/env bash time-awareness-hook — emit a rate-limited human timestamp so Claude Code stays aware of wall-clock time and its passage it has no clock; it only knows what lands in context . Wired into ~/.claude/settings.json as a UserPromptSubmit and/or PostToolUse hook; the emitted JSON's additionalContext is injected into the model's context. Cadence mimics how a human glances at a clock : emit the LONG form weekday + full date + time the first time per wall-clock hour, the SHORT form just the time when MORE than 5 minutes have passed since the last short, and nothing otherwise. A LONG emit also resets the short timer so you never get a long immediately echoed by a short. Architecture is hexagonal: a PURE decision core --decide , no I/O decides none|short|long from now epoch, now hourkey, last hourkey, last short epoch ; the adapter supplies those from the clock + a per-session state file and emits. Test seams env : TIMESTAMP HOOK NOW epoch override , TIMESTAMP HOOK STATE DIR, TIMESTAMP HOOK SESSION. State lives under XDG STATE HOME, one file per session. set -u SHORT INTERVAL=300 seconds; "more than 5 minutes" = strict this --- pure core ------------------------------------------------------------- decide NOW EPOCH NOW HOURKEY LAST HOURKEY LAST SHORT EPOCH prints: "<emit <new hourkey <new short epoch " emit in none|short|long decide { local now epoch="$1" now hourkey="$2" last hourkey="$3" last short="${4:-0}" if "$now hourkey" = "$last hourkey" ; then printf 'long %s %s\n' "$now hourkey" "$now epoch" new hour incl. first run elif $ now epoch - last short -gt "$SHORT INTERVAL" ; then printf 'short %s %s\n' "$last hourkey" "$now epoch" 5 min since last short else printf 'none %s %s\n' "$last hourkey" "$last short" too soon; state unchanged fi } --- adapter helpers ------------------------------------------------------- portable epoch - formatted string GNU date first, BSD date fallback fmt { date -d "@$1" +"$2" 2 /dev/null || date -r "$1" +"$2"; } pull a top-level string field out of the hook's stdin JSON json get { local json="$1" key="$2" if command -v jq /dev/null 2 &1; then printf '%s' "$json" | jq -r --arg k "$key" '. $k // empty' 2 /dev/null else printf '%s' "$json" | grep -oE "\"$key\" :space: : :space: \" ^\" \"" \ | head -1 | sed -E "s/. : :space: \" ^\" \"/\1/" fi } safe { printf '%s' "$1" | tr -c 'A-Za-z0-9 .-' ' '; } usage { cat <<'EOF' time-awareness-hook — rate-limited timestamp injection for Claude Code USAGE time-awareness-hook hook mode: reads hook JSON on stdin, emits additionalContext JSON or nothing on stdout time-awareness-hook --decide NOW HOURKEY LAST HOURKEY LAST SHORT pure core: prints "<none|short|long <hourkey <short epoch " time-awareness-hook -h | --help time-awareness-hook --about time-awareness-hook --test run test suite stdout muted; exit = fails CADENCE long : first emit of each wall-clock hour weekday, full date, time short : when 5 min since the last short just the time none : otherwise silent A long emit resets the short timer. ENV test seams TIMESTAMP HOOK NOW epoch-seconds override for "now" TIMESTAMP HOOK STATE DIR state directory default: $XDG STATE HOME/claude-time-awareness TIMESTAMP HOOK SESSION session id fallback when stdin lacks one EOF } --- hook mode ------------------------------------------------------------- hook main { never block waiting on a tty when run by hand with no stdin local input="" if -t 0 ; then input="$ cat "; fi local session event session="$ json get "$input" session id " event="$ json get "$input" hook event name " -n "$session" || session="${TIMESTAMP HOOK SESSION:-default}" -n "$event" || event="UserPromptSubmit" local now state dir state file now="${TIMESTAMP HOOK NOW:-$ date +%s }" state dir="${TIMESTAMP HOOK STATE DIR:-${XDG STATE HOME:-$HOME/.local/state}/claude-time-awareness}" mkdir -p "$state dir" 2 /dev/null || true state file="$state dir/state-$ safe "$session" " local now hourkey last hourkey="" last short="0" now hourkey="$ fmt "$now" '%Y%m%d%H' " if -f "$state file" ; then { read -r last hourkey; read -r last short; } < "$state file" 2 /dev/null || true -n "$last short" || last short="0" fi local emit new hourkey new short read -r emit new hourkey new short < < decide "$now" "$now hourkey" "$last hourkey" "$last short" "$emit" = "none" && return 0 persist new state atomically only on an actual emit local tmp="$state file.tmp.$$" printf '%s\n%s\n' "$new hourkey" "$new short" "$tmp" 2 /dev/null && mv -f "$tmp" "$state file" 2 /dev/null hourly housekeeping: drop state files older than a day cheap, runs ~once/hour "$emit" = "long" && find "$state dir" -maxdepth 1 -type f -name 'state- ' -mtime +0 -delete 2 /dev/null local stamp case "$emit" in long stamp="$ fmt "$now" '⏱ %A, %B %d, %Y %I:%M %p %Z' " ;; short stamp="$ fmt "$now" '⏱ %I:%M %p %Z' " ;; esac printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}\n' "$event" "$stamp" } --- dispatch -------------------------------------------------------------- case "${1:-}" in -h|--help usage; exit 0 ;; --about echo "time-awareness-hook: rate-limited timestamp injection for Claude Code $ uname -s $ uname -m "; exit 0 ;; --decide shift; decide "$@"; exit 0 ;; --test tf="$HOME/dotfiles/bin/test/time-awareness-hook test" if -f "$ tf" ; then exec bash "$ tf" /dev/null; fi echo "no test file at $ tf" &2; exit 0 ;; hook main; exit 0 ;; esac Note: the bash function bodies are tab-indented. If you copy/paste, keep the tabs or it still runs — bash doesn't care — but match your house style . Edit ~/.claude/settings.json user-global — or a project's .claude/settings.json — and merge this hooks object in. If a hooks object already exists, add these two keys to it; do not clobber sibling hooks. { "hooks": { "UserPromptSubmit": { "hooks": { "type": "command", "command": "$HOME/bin/time-awareness-hook" } } , "PostToolUse": { "hooks": { "type": "command", "command": "$HOME/bin/time-awareness-hook" } } } } - Omitting "matcher" on PostToolUse matches all tools fine — it's rate-limited . Add "matcher": "Bash" etc. to scope it to specific tools. - Use $HOME/bin/... not a bare name for portability across machines. The effect is immediate — no session restart needed. Long form first call of the hour for a fresh session : printf '{"hook event name":"PostToolUse","session id":"demo"}' \ | TIMESTAMP HOOK STATE DIR="$ mktemp -d " ~/bin/time-awareness-hook - {"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"⏱ Monday, June 23, 2026 10:27 PM EDT"}} In a live session you'll then see lines like ⏱ 10:33 PM EDT appear in the agent's context — long once per hour, short after 5 min, silent otherwise. Save as ~/dotfiles/bin/test/time-awareness-hook test and run it directly bash time-awareness-hook test — it exits with the number of failures. It tests the pure core at every boundary first run, the exactly-300s vs 301s line, the hour-rollover override and the adapter with an injected clock and an isolated temp state dir, so it's fully deterministic. bash /usr/bin/env bash Tests for time-awareness-hook: rate-limited timestamp injection for Claude time cognizance. Architecture under test is hexagonal: a PURE decision core --decide that takes now epoch, now hourkey, last hourkey, last short epoch and emits one of none|short|long plus the new state — no clock, no state file, no stdin. The hook adapter default mode reads stdin JSON + clock + state and calls that same core. We test the pure core directly deterministic, no I/O and exercise the adapter with an injected clock + temp state dir. Conventions: progress - stdout, failures - stderr, exit code == number of failures. NEVER use set -e here error paths are under test ; set -u only. set -u HOOK="$HOME/dotfiles/bin/time-awareness-hook" tests=0 fails=0 expect eq { actual expected msg tests++ if "$1" = "$2" ; then echo "✓ $3" else echo "✗ $3" &2 echo " expected: $2 " &2 echo " actual: $1 " &2 fails++ fi } expect contains { haystack needle msg tests++ if printf '%s' "$1" | grep -q -- "$2"; then echo "✓ $3" else echo "✗ $3" &2; echo " $1 lacks $2 " &2; fails++ ; fi } expect not contains { haystack needle msg tests++ if printf '%s' "$1" | grep -q -- "$2"; then echo "✗ $3" &2; echo " $1 unexpectedly has $2 " &2; fails++ else echo "✓ $3"; fi } portable epoch- format GNU first, BSD fallback so expectations match the hook fmt { date -d "@$1" +"$2" 2 /dev/null || date -r "$1" +"$2"; } ---- PURE CORE: time-awareness-hook --decide now epoch now hourkey last hourkey last short ---- emit { "$HOOK" --decide "$@" | cut -d' ' -f1; } state { "$HOOK" --decide "$@" | cut -d' ' -f2-; } echo " pure decision core" 1. first run empty prior hour - long, short reset to now expect eq "$ emit 1000000000 2026062221 '' 0 " "long" "first run - long" expect eq "$ state 1000000000 2026062221 '' 0 " "2026062221 1000000000" "first run state = nowhour + now" 2. same hour, 100s since short - none expect eq "$ emit 1000000100 2026062221 2026062221 1000000000 " "none" "same hour <5min - none" 3. same hour, exactly 300s - none rule is 'MORE than 5 min', strict expect eq "$ emit 1000000300 2026062221 2026062221 1000000000 " "none" "exactly 5min - none strict " 4. same hour, 301s - short, updates short epoch, keeps hour expect eq "$ emit 1000000301 2026062221 2026062221 1000000000 " "short" "just over 5min - short" expect eq "$ state 1000000301 2026062221 2026062221 1000000000 " "2026062221 1000000301" "short keeps hour, bumps short epoch" 5. hour changed but short was 10s ago - long overrides + resets short timer expect eq "$ emit 1000000010 2026062222 2026062221 1000000000 " "long" "hour change overrides recent short" expect eq "$ state 1000000010 2026062222 2026062221 1000000000 " "2026062222 1000000010" "long resets short epoch to now" ---- ADAPTER: full stdin/state path with injected clock + isolated state dir ---- echo " hook adapter injected clock + temp state " --tmpdir places this in $TMPDIR RAM ; per project convention it self-cleans, and avoiding an explicit rm dodges the rm-safe wrapper's noise on teardown. TMP="$ mktemp -d --tmpdir time-awareness-hook.XXXXXX " run { now epoch session printf '{"hook event name":"PostToolUse","session id":"%s"}' "$2" \ | TIMESTAMP HOOK NOW="$1" TIMESTAMP HOOK STATE DIR="$TMP" "$HOOK" } WD="$ fmt 1000000000 %A " weekday name only appears in the LONG format 6. fresh session - long emit JSON additionalContext, weekday present + state file created o6="$ run 1000000000 sessA " expect contains "$o6" "additionalContext" "fresh session emits additionalContext JSON" expect contains "$o6" "$WD" "fresh session emit is LONG weekday present " expect eq "$ -f "$TMP/state-sessA" && echo yes " "yes" "state file created for session" 7. same session 2 min later, same hour - none silent expect eq "$ run 1000000120 sessA " "" "2 min later same hour - no output" 8. same session ~6.5 min later - short time present, weekday absent o8="$ run 1000000400 sessA " expect contains "$o8" "additionalContext" "6+ min later emits" expect not contains "$o8" "$WD" "6+ min emit is SHORT no weekday " 9. session isolation: a different session id is fresh - long, separate state file o9="$ run 1000000400 sessB " expect contains "$o9" "$WD" "different session is independent - LONG" expect eq "$ -f "$TMP/state-sessB" && echo yes " "yes" "separate state file per session" ---- summary ---- if "$fails" -gt 0 ; then echo "$fails of $tests tests FAILED" &2 else echo "all $tests tests passed" fi exit "$fails" Bash + GNU date date -d @epoch is tried first, BSD date -r epoch is the fallback — so it works on both Linux and macOS .is used if present; otherwise a jq grep / sed fallback parses the two fields we need from the stdin JSON. So jq is optional .- A Claude Code recent enough to inject hookSpecificOutput.additionalContext for UserPromptSubmit / PostToolUse confirmed on 2.1.177 . Two hooks because the human and the agent move on different clocks: a user turn is the human's heartbeat; a tool call is the agent's. Covering both means the agent is oriented whether you're driving or it's running autonomously. Rate-limiting in the script, not the wiring , so PostToolUse can stay on every tool with negligible cost — it returns instantly with no output the vast majority of the time. Long-hourly / short- 5min / silent mirrors how people actually track time: you register the hour when it rolls over, and you're vaguely aware of ~5-minute chunks in between. The long-emit-resets-short rule prevents a redundant short right after a long. The pure no clock, no files, no stdin is the part worth lifting into any agent harness — it's what makes the cadence testable with an injected clock, and it's language-agnostic port the 3-line rule anywhere . --decide core Per-session state keyed on session id keeps concurrent agent sessions from stomping each other's timers.