Gives AI coding agents temporal awareness via a hook-backed ledger and decision rules. Activates whenever an agent reasons about recency, retry windows, memory staleness, deploy cooldowns, idle detection, or any "when / how long ago" question. Required for autonomous or long-running agents.
Gives AI coding agents temporal awareness via a hook-backed ledger and decision rules. Activates whenever an agent reasons about recency, retry windows, memory staleness, deploy cooldowns, idle detection, or any "when / how long ago" question. Required for autonomous or long-running agents.
If the host platform does not support hooks (Cursor, Hermes, ADAL, plain skill-only mode), chronos degrades: run date -u or date -Iseconds at decision points and state explicitly "derived from shell, not ledger".
When to consult time — 7 triggers
1. Before retrying a failed command
Read the ledger for the same tool + args_hash.
If the last failure was < 60s ago with the same args, change strategy — don't re-run identically.
If 60s – 10min, consider one retry with a rationale.
If > 10min, circumstances may have changed; re-run is reasonable.
Deploy cooldowns: the same rule applies to deployments and pushes. If the last deploy failed under 60s ago, check logs and fix config before re-deploying. Don't re-trigger a broken pipeline without a changed state.
2. Before trusting memory, a cached finding, or a prior read
Staleness thresholds by source:
Source
Stale after
Action when stale
git status, running processes, env vars
5 min (same session)
Re-query
File contents previously Read
1 hr OR any write to that path since Read
Re-Read
Persistent memory (MemPalace, KG facts)
7 days since last write
Re-verify before use
External API responses (prices, PR status, issues)
5 min
Re-fetch
Build/test results
After any source change since that run
Re-run
LLM's own prior claim ("earlier I saw...")
Always verify against ledger
Consult ledger
3. Before reporting progress or writing a summary
Use session_duration to pick verbosity:
< 5 min — terse answer, no recap.
5 – 30 min — one-paragraph summary of what changed.
> 30 min — structured recap with timestamped milestones from the ledger.
4. Before running a long or destructive command
Scan the ledger for the same tool recently. If the last 3 duration_ms values for that tool are growing (e.g. each > 2× the previous median), something is degrading. Surface it, don't silently wait.
5. Idle-loop detection (autonomous mode)
Whenever since_last_user exceeds the idle threshold (default 900s / 15 min, configurable via CHRONOS_IDLE_THRESHOLD_SEC) and you are still in an autonomous loop: pause. Summarize progress, list pending decisions, ask for direction. This prevents silent runaway.
For explicit autonomous loops (/loop, /autonomous), the threshold may be higher — but always escalate when session_duration > 2h without user input.
6. Before any "wait" / "in a few minutes" / "just now" statement
Replace imprecise language with a concrete delta from the ledger:
❌ "Just tried that."
✅ "Last attempt was 47s ago (tool_use_id abc123, failed with EACCES)."
❌ "Let's wait a moment."
✅ "Retry at 2026-04-23T20:45:00Z (+3 min from now)."
7. Date or time questions
Never guess. In order of preference:
Read now_utc / now_local from the SessionStart context if session_duration < 10 min.
Read latest finished_at in the ledger if < 10 min ago.
Run date -u +"%Y-%m-%dT%H:%M:%SZ" fresh.
How to read the ledger
Ledger path is injected as ledger: <path> in SessionStart context.
One line = one event (JSONL, append-only). Latest line for a given tool_use_id wins.
# Last 10 eventstail -n 10 "$LEDGER_PATH"# Events in last 10 minutes (helper script)
./scripts/ledger_read.sh --since 10m
# Events for a specific tool in last hour
./scripts/ledger_read.sh --tool Bash --since 1h
# Last duration for a specific args_hash
./scripts/ledger_read.sh --tool Bash --args-hash abc123 --last
Two lines per tool call: one on PreToolUse (started_at), one on PostToolUse (finished_at + duration). This is deliberate — async writes avoid adding latency.
args_hash is written by the PreToolUse hook: SHA-256 of the serialized tool arguments, first 12 hex characters. Filter the ledger by it to identify identical repeated calls. Do not compute it yourself — read it from the ledger only.
Failure modes to avoid
Do not re-derive elapsed time by counting messages or turns. Use wall clock from ledger.
Do not trust your own prior claim of "just now" from earlier in context. Ledger is the source of truth.
Do not issue "try again in a few minutes" without a concrete ISO timestamp or delta.
Do not silently hang in autonomous mode. Trigger #5 always applies.
Do not assume the ledger exists. Check for ledger: in your context first; degrade to date -u if absent.
Degraded mode (no hooks platform)
If you don't see chronos baseline in your context, the host platform doesn't support hooks. You still follow the decision rules — just swap ledger reads for:
Current time: date -u +"%Y-%m-%dT%H:%M:%SZ" (bash) or Get-Date -AsUTC -Format o (pwsh)
File mtime: stat -c %Y <path> (bash) or (Get-Item <path>).LastWriteTimeUtc (pwsh)
Git age: git log -1 --format=%cI <path> for last-commit ISO timestamp
State this explicitly: "No ledger on this platform; I'm using date -u as fallback."
Install / wiring
See installers/<platform>/ for platform-specific setup:
claude-code/ — full hook stack (5 events)
codex/ — full hook stack (PreToolUse matches Bash only)
opencode/ — TS plugin writes ledger; read via ledger_read.sh
cursor/ — rules-only degraded mode
hermes/, adal/, pi/, openclaw/ — SKILL-only ports
Why this matters
From arxiv 2510.23853 "Your LLM Agents are Temporally Blind" (Oct 2025): even when timestamps are present in context, the best frontier models achieve only 65% alignment with human temporal judgment. Timestamps appear in fewer than 4% of reasoning traces. The fix is not more plumbing — it's explicit decision rules that make the agent look at the clock at the right moments.
