{"id":"9f4378ce-9db6-4843-99cd-ace1a143d3cd","entityType":"agent","slug":"clawhub-othmanadi-chronos-2","name":"Chronos","canonicalUrl":"https://www.xpersona.co/agent/clawhub-othmanadi-chronos-2","canonicalPath":"/agent/clawhub-othmanadi-chronos-2","generatedAt":"2026-10-12T22:07:28.621Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-12T00:50:22.542Z","emptyReason":null},"description":"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. Skill: Chronos Owner: othmanadi Summary: 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. Tags: latest:0.1.1 Version history: v0.1.1 | 2026-09-02T21:17:13.737Z | auto - Removed","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 965 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s17ds6610wra1m85mmdwy4zja184wyga:chronos-2","sourceUrl":"https://clawhub.ai/othmanadi/chronos-2","homepage":"https://clawhub.ai/othmanadi/skills/chronos-2","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/othmanadi/chronos-2","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/othmanadi/skills/chronos-2","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Gives AI coding agents temporal awareness via a hook-backed ledger and decision rules. Activates whenever an agent reasons about recency, retry windows, memory "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:50:22.542Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:50:22.542Z","emptyReason":null},"stars":null,"forks":null,"downloads":965,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"0.1.1","tractionLabel":"965 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:50:22.530Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T00:50:22.542Z","lastCrawledAt":"2026-10-12T00:50:22.530Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T00:50:22.530Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.1","createdAt":"2026-09-02T21:17:13.737Z","changelog":"- Removed the skill-card.md file. - No changes to functionality or documentation beyond file deletion.","fileCount":54,"zipByteSize":5117326},{"version":"0.1.0","createdAt":"2026-08-30T18:20:14.123Z","changelog":"Initial major release of Chronos, providing temporal awareness and decision rules for AI coding agents. - Introduces a hook-backed time ledger, available when supported by the host platform. - Supplies session baseline, per-turn timing deltas, and an append-only tool-use ledger. - Defines seven key triggers for when agents must consult or reason explicitly about time and recency. - Details degraded fallback mode for platforms without hook support, ensuring graceful functionality. - Includes concrete rules and ledger query examples for retries, memory staleness, and progress reporting. - Documents installation and platform-specific wiring procedures.","fileCount":54,"zipByteSize":5117054}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ds6610wra1m85mmdwy4zja184wyga:chronos-2","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T22:07:28.620Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-othmanadi-chronos-2/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-12T00:50:22.542Z","emptyReason":null},"readme":"Skill: Chronos\n\nOwner: othmanadi\n\nSummary: 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.\n\nTags: latest:0.1.1\n\nVersion history:\n\nv0.1.1 | 2026-09-02T21:17:13.737Z | auto\n\n- Removed the skill-card.md file.\n- No changes to functionality or documentation beyond file deletion.\n\nv0.1.0 | 2026-08-30T18:20:14.123Z | auto\n\nInitial major release of Chronos, providing temporal awareness and decision rules for AI coding agents.\n\n- Introduces a hook-backed time ledger, available when supported by the host platform.\n- Supplies session baseline, per-turn timing deltas, and an append-only tool-use ledger.\n- Defines seven key triggers for when agents must consult or reason explicitly about time and recency.\n- Details degraded fallback mode for platforms without hook support, ensuring graceful functionality.\n- Includes concrete rules and ledger query examples for retries, memory staleness, and progress reporting.\n- Documents installation and platform-specific wiring procedures.\n\nArchive index:\n\nArchive v0.1.1: 54 files, 5117326 bytes\n\nFiles: .cursor (0b), .cursor/rules (0b), .cursor/rules/chronos.mdc (1787b), .gitignore (51b), AGENTS.md (2070b), assets (0b), assets/banner.png (2985450b), assets/profile-banner.png (2103440b), CHANGELOG.md (1441b), CONTRIBUTING.md (1386b), installers (0b), installers/adal (0b), installers/adal/README.md (483b), installers/claude-code (0b), installers/claude-code/install.sh (4615b), installers/claude-code/settings.json (1321b), installers/claude-code/settings.windows-ps.json (1155b), installers/codex (0b), installers/codex/config.toml.fragment (108b), installers/codex/hooks.json (829b), installers/codex/install.sh (1685b), installers/cursor (0b), installers/cursor/README.md (579b), installers/detect-shell.sh (872b), installers/hermes (0b), installers/hermes/README.md (493b), installers/openclaw (0b), installers/openclaw/README.md (551b), installers/opencode (0b), installers/opencode/plugin.ts (3572b), installers/opencode/README.md (981b), installers/pi (0b), installers/pi/README.md (854b), LICENSE (1079b), package.json (826b), README.md (10789b), scripts (0b), scripts/_lib.ps1 (3874b), scripts/_lib.sh (4026b), scripts/ledger_read.ps1 (1644b), scripts/ledger_read.sh (2055b), scripts/post_tool.ps1 (1270b), scripts/post_tool.sh (1879b), scripts/pre_tool.ps1 (812b), scripts/pre_tool.sh (1355b), scripts/prompt_submit.ps1 (1969b), scripts/prompt_submit.sh (2463b), scripts/session_start.ps1 (1335b), scripts/session_start.sh (1665b), scripts/stop.ps1 (602b), scripts/stop.sh (898b), skill-card.md (2617b), SKILL.md (7717b), _meta.json (128b)\n\nFile v0.1.1:SKILL.md\n\n---\nname: chronos\ndescription: 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.\nversion: 1.0.0\nlicense: MIT\nauthor: OthmanAdi\ntags: [time, temporal, autonomy, ledger, agents, hooks, session-management]\nhomepage: https://aware-bloom-szmt.here.now\nrepository: https://github.com/OthmanAdi/chronos\nallowed-tools: Read, Bash(date *), Bash(stat *), Bash(cat *), Bash(jq *), Bash(ls *), Bash(git log *), Bash(git status *)\n---\n\n# Chronos — Time Awareness for Agents\n\nYou are not temporally blind. Stop guessing \"when\" and \"how long ago\". You have a ledger. Use it.\n\n## What chronos gives you\n\nWhen the host platform supports hooks (Claude Code, Codex, OpenCode-plugin), chronos populates three sources of truth:\n\n1. **SessionStart baseline** — injected into your context at session start:\n   - `now_utc` — ISO-8601 UTC\n   - `now_local` — ISO-8601 with offset\n   - `tz` — timezone name + offset\n   - `ledger` — absolute path to this session's JSONL tool-use ledger\n   - `state` — absolute path to this session's state file\n   - `session` — session ID\n\n2. **Per-turn delta** — injected on every user message:\n   - `now`, `turn`, `session_duration`, `since_last_user`\n\n3. **Tool-use ledger** — JSONL file, one entry per tool invocation:\n   - `{tool_use_id, tool, args_hash, started_at, finished_at, duration_ms, success}`\n\nIf 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\".\n\n## When to consult time — 7 triggers\n\n### 1. Before retrying a failed command\n\nRead the ledger for the same `tool` + `args_hash`.\n\n- If the last failure was `< 60s` ago with the same args, **change strategy** — don't re-run identically.\n- If `60s – 10min`, consider one retry with a rationale.\n- If `> 10min`, circumstances may have changed; re-run is reasonable.\n\n**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.\n\n### 2. Before trusting memory, a cached finding, or a prior read\n\nStaleness thresholds by source:\n\n| Source | Stale after | Action when stale |\n|---|---|---|\n| `git status`, running processes, env vars | 5 min (same session) | Re-query |\n| File contents previously Read | 1 hr OR any write to that path since Read | Re-Read |\n| Persistent memory (MemPalace, KG facts) | 7 days since last write | Re-verify before use |\n| External API responses (prices, PR status, issues) | 5 min | Re-fetch |\n| Build/test results | After any source change since that run | Re-run |\n| LLM's own prior claim (\"earlier I saw...\") | Always verify against ledger | Consult ledger |\n\n### 3. Before reporting progress or writing a summary\n\nUse `session_duration` to pick verbosity:\n\n- `< 5 min` — terse answer, no recap.\n- `5 – 30 min` — one-paragraph summary of what changed.\n- `> 30 min` — structured recap with timestamped milestones from the ledger.\n\n### 4. Before running a long or destructive command\n\nScan 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.\n\n### 5. Idle-loop detection (autonomous mode)\n\nWhenever `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.\n\nFor explicit autonomous loops (`/loop`, `/autonomous`), the threshold may be higher — but always escalate when `session_duration > 2h` without user input.\n\n### 6. Before any \"wait\" / \"in a few minutes\" / \"just now\" statement\n\nReplace imprecise language with a concrete delta from the ledger:\n\n- ❌ \"Just tried that.\"\n- ✅ \"Last attempt was 47s ago (tool_use_id abc123, failed with EACCES).\"\n\n- ❌ \"Let's wait a moment.\"\n- ✅ \"Retry at 2026-04-23T20:45:00Z (+3 min from now).\"\n\n### 7. Date or time questions\n\nNever guess. In order of preference:\n\n1. Read `now_utc` / `now_local` from the SessionStart context if `session_duration < 10 min`.\n2. Read latest `finished_at` in the ledger if `< 10 min` ago.\n3. Run `date -u +\"%Y-%m-%dT%H:%M:%SZ\"` fresh.\n\n## How to read the ledger\n\nLedger path is injected as `ledger: <path>` in SessionStart context.\n\n**One line = one event** (JSONL, append-only). Latest line for a given `tool_use_id` wins.\n\n```bash\n# Last 10 events\ntail -n 10 \"$LEDGER_PATH\"\n\n# Events in last 10 minutes (helper script)\n./scripts/ledger_read.sh --since 10m\n\n# Events for a specific tool in last hour\n./scripts/ledger_read.sh --tool Bash --since 1h\n\n# Last duration for a specific args_hash\n./scripts/ledger_read.sh --tool Bash --args-hash abc123 --last\n```\n\nEntry shape:\n\n```json\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1\",\"started_at\":\"2026-04-23T20:00:00Z\"}\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1\",\"finished_at\":\"2026-04-23T20:00:12Z\",\"duration_ms\":12034,\"success\":true}\n```\n\nTwo lines per tool call: one on PreToolUse (started_at), one on PostToolUse (finished_at + duration). This is deliberate — async writes avoid adding latency.\n\n`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.\n\n## Failure modes to avoid\n\n- **Do not** re-derive elapsed time by counting messages or turns. Use wall clock from ledger.\n- **Do not** trust your own prior claim of \"just now\" from earlier in context. Ledger is the source of truth.\n- **Do not** issue \"try again in a few minutes\" without a concrete ISO timestamp or delta.\n- **Do not** silently hang in autonomous mode. Trigger #5 always applies.\n- **Do not** assume the ledger exists. Check for `ledger: ` in your context first; degrade to `date -u` if absent.\n\n## Degraded mode (no hooks platform)\n\nIf 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:\n\n- Current time: `date -u +\"%Y-%m-%dT%H:%M:%SZ\"` (bash) or `Get-Date -AsUTC -Format o` (pwsh)\n- File mtime: `stat -c %Y <path>` (bash) or `(Get-Item <path>).LastWriteTimeUtc` (pwsh)\n- Git age: `git log -1 --format=%cI <path>` for last-commit ISO timestamp\n\nState this explicitly: \"No ledger on this platform; I'm using `date -u` as fallback.\"\n\n## Install / wiring\n\nSee `installers/<platform>/` for platform-specific setup:\n\n- `claude-code/` — full hook stack (5 events)\n- `codex/` — full hook stack (PreToolUse matches Bash only)\n- `opencode/` — TS plugin writes ledger; read via `ledger_read.sh`\n- `cursor/` — rules-only degraded mode\n- `hermes/`, `adal/`, `pi/`, `openclaw/` — SKILL-only ports\n\n## Why this matters\n\nFrom [arxiv 2510.23853](https://arxiv.org/html/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**.\n\nThis SKILL.md is those rules.\n\nFile v0.1.1:installers/adal/README.md\n\n# chronos — ADAL (SylphAI adal-cli)\n\nADAL supports Agent Skills. Drop SKILL.md into the ADAL skills location (docs at https://docs.sylph.ai/).\n\n## Install\n\n```bash\n# path may vary by ADAL version — check docs\nmkdir -p ~/.adal/skills/chronos\ncp SKILL.md ~/.adal/skills/chronos/SKILL.md\ncp AGENTS.md ~/.adal/skills/chronos/AGENTS.md\n```\n\n## Degraded mode only\n\nADAL hook API is not publicly documented. Chronos runs in SKILL-only mode: decision rules + shell fallback (`date -u`).\n\nFile v0.1.1:installers/cursor/README.md\n\n# chronos — Cursor\n\nCursor has no hooks. SKILL-only degraded mode via `.cursor/rules/chronos.mdc`.\n\n## Install (project)\n\n```bash\nmkdir -p .cursor/rules\ncp .cursor/rules/chronos.mdc .cursor/rules/chronos.mdc\n```\n\n## Install (user global)\n\n```bash\nmkdir -p ~/.cursor/rules\ncp .cursor/rules/chronos.mdc ~/.cursor/rules/chronos.mdc\n```\n\nRule has `alwaysApply: true` — agent sees it every chat.\n\n## What you get\n\n- Decision rules always in context\n- Instructions to run `date -u` + `stat` for time queries\n\n## What you don't get\n\nNo ledger, no per-turn delta, no idle detection.\n\nFile v0.1.1:installers/hermes/README.md\n\n# chronos — Hermes (NousResearch)\n\nHermes injects skills from `~/.hermes/skills/` as user messages. No shell hooks — SKILL-only mode.\n\n## Install\n\n```bash\nmkdir -p ~/.hermes/skills/chronos\ncp SKILL.md ~/.hermes/skills/chronos/SKILL.md\n```\n\nAgent will follow decision rules using shell fallback (`date -u`, `stat`).\n\n## What you get\n\n- Decision rules (7 triggers)\n- Shell-fallback time queries\n\n## What you don't get\n\n- Automatic ledger (no hooks)\n- Per-turn elapsed inject\n- Idle warnings\n\nFile v0.1.1:installers/openclaw/README.md\n\n# chronos — OpenClaw\n\nOpenClaw uses `skills/<name>/SKILL.md` (Agent Skills standard).\n\n## Install\n\n```bash\nmkdir -p skills/chronos\ncp SKILL.md skills/chronos/SKILL.md\ncp AGENTS.md skills/chronos/AGENTS.md\n```\n\n## Optional: plugin SDK for ledger\n\nOpenClaw has a plugin-sdk (`openclaw/plugin-sdk`). Time-awareness plugin stub:\n\n```ts\n// See openclaw/plugin-sdk docs for full wiring.\n// Hook into session + tool events, append to ~/.chronos/ledger-*.jsonl\n```\n\n## Degraded mode\n\nSKILL-only works fine. Agent follows decision rules with shell fallback.\n\nFile v0.1.1:installers/opencode/README.md\n\n# chronos — OpenCode install\n\nOpenCode plugins can't push arbitrary context into the model. Chronos works in \"ledger-only\" mode: the plugin writes the ledger + state file; SKILL.md instructs the agent to `Read` those files at decision points.\n\n## Install\n\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp installers/opencode/plugin.ts ~/.config/opencode/plugins/chronos.ts\n```\n\nAlso copy the portable `SKILL.md` to a skills location OpenCode loads:\n\n```bash\nmkdir -p ~/.config/opencode/skills/chronos\ncp SKILL.md ~/.config/opencode/skills/chronos/SKILL.md\n```\n\n## How the agent uses it\n\nSKILL.md tells the agent to:\n1. Read `~/.chronos/session-<sid>.json` for baseline + last_user timestamp\n2. Read `~/.chronos/ledger-<sid>.jsonl` for tool-use history\n\nNo `additionalContext` injection on this platform — honest degraded mode.\n\n## Env\n\n- `CHRONOS_HOME` — override ledger location (default: `~/.chronos`)\n- `CHRONOS_IDLE_THRESHOLD_SEC` — idle warning threshold (default: 900)\n\nFile v0.1.1:installers/pi/README.md\n\n# chronos — PI (badlogic/pi-mono)\n\nPI supports Agent Skills. Copy SKILL.md into skills directory.\n\n## Install\n\n```bash\nmkdir -p ~/.pi/skills/chronos\ncp SKILL.md ~/.pi/skills/chronos/SKILL.md\n```\n\n## Optional: ledger via PI extension\n\nPI exposes `pi.on(\"tool_call\", ...)` event API. To add a ledger:\n\n```ts\n// example extension stub — see pi-mono docs for full wiring\nimport { pi } from \"@badlogic/pi\";\nimport * as fs from \"fs\";\nimport * as path from \"path\";\nimport * as os from \"os\";\n\nconst LEDGER = path.join(os.homedir(), \".chronos\", \"ledger-pi.jsonl\");\n\npi.on(\"tool_call\", (ev) => {\n  fs.appendFileSync(LEDGER, JSON.stringify({\n    tool: ev.name,\n    started_at: new Date().toISOString(),\n    duration_ms: ev.duration_ms,\n    success: !ev.error,\n  }) + \"\\n\");\n});\n```\n\n## Degraded mode\n\nWithout extension: SKILL rules still apply, shell-fallback.\n\nFile v0.1.1:README.md\n\n# chronos\n\n![How AI reacts when you ask what time it is](assets/banner.png)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)\n[![Platforms](https://img.shields.io/badge/platforms-8-black)](README.md#platform-matrix)\n[![Paper](https://img.shields.io/badge/arxiv-2510.23853-black)](https://arxiv.org/abs/2510.23853)\n\n**Time awareness for AI coding agents.** Stops your agent from guessing \"when\" and \"how long ago\".\n\n```bash\nnpx skills add OthmanAdi/chronos --skill chronos -g\n```\n\nOr from npm: `pi install npm:chronos-skill` ([package](https://www.npmjs.com/package/chronos-skill); the bare `chronos` name on npm belongs to an unrelated project)\n\nWorks across Claude Code, Codex, OpenCode, Cursor, PI, OpenClaw, Hermes, ADAL.\n\n---\n\n## The problem\n\nLLMs do not know what time it is. They guess. They report \"just now\" when it was two hours ago. They retry failed commands without checking that the last attempt was 10 seconds ago. They run silently in autonomous loops with no idle detection.\n\n[Arxiv 2510.23853](https://arxiv.org/abs/2510.23853) measured this empirically: even frontier models with timestamps injected into context reach only **65% temporal reasoning alignment** with human judgment. Timestamps appear in fewer than 4% of reasoning traces. The ceiling exists because having access to timestamps is not enough. Agents need explicit rules for *when to look at the clock*.\n\nChronos is those rules, backed by a queryable tool-use ledger.\n\n---\n\n## What chronos gives you\n\n### 1. Portable decision rules — SKILL.md\n\nSeven triggers that govern when an agent must consult time:\n\n1. Before retrying a failed command: check the ledger for the last attempt and elapsed time\n2. Before trusting memory or a cached result: apply staleness thresholds by source type\n3. Before reporting progress: use `session_duration` to set summary verbosity\n4. Before running a long or destructive command: detect tool degradation from ledger timing\n5. Idle-loop detection: pause and surface decisions when the agent runs without user input too long\n6. Before any \"just now\" or \"in a minute\" statement: replace with a concrete ISO delta from the ledger\n7. Date and time questions: consult the baseline first, never guess\n\n### 2. Hook-backed automation (Claude Code, Codex, OpenCode)\n\nFour hook events populate three data sources on every session:\n\n```mermaid\nsequenceDiagram\n    participant A as Agent\n    participant H as Hook Scripts\n    participant L as ~/.chronos/\n\n    Note over A,L: Session start\n    H->>L: Initialize ledger + state file\n    H->>A: Inject baseline (now_utc, tz, ledger path, session ID)\n\n    Note over A,L: Each user message\n    H->>L: Increment turn counter, record last_user_at\n    H->>A: Inject per-turn delta (turn, session_duration, since_last_user)\n\n    Note over A,L: Each tool call\n    H->>L: Append started_at + args_hash (PreToolUse)\n    Note over H,L: Tool executes\n    H->>L: Append finished_at + duration_ms + success (PostToolUse)\n\n    Note over A,L: Session end\n    H->>A: Check idle time, emit warning if autonomous threshold exceeded\n```\n\n### 3. Honest degraded mode (Cursor, Hermes, ADAL)\n\nPlatforms without hook support still get full decision rules. SKILL.md instructs the agent to use `date -u`, `stat`, and `git log` as fallback sources and to state explicitly which source it used.\n\n---\n\n## Platform matrix\n\n| Platform | Support | What you get |\n|---|---|---|\n| **Claude Code** | Full | All 5 hooks plus SKILL.md |\n| **Codex CLI** | Full | All 5 hooks (PreToolUse targets Bash only) plus AGENTS.md |\n| **OpenCode** | Partial | TypeScript plugin writes ledger; SKILL reads it |\n| **PI (pi-mono)** | Partial | SKILL plus optional extension for ledger |\n| **OpenClaw** | Partial | SKILL plus optional plugin-sdk for ledger |\n| **Cursor** | Skill-only | Always-on rule with shell-fallback instructions |\n| **Hermes** | Skill-only | SKILL injects as user message |\n| **ADAL** | Skill-only | SKILL.md only (hook API not public) |\n\n---\n\n## vs. prior art\n\n| | **chronos** | hodgesmr/temporal-awareness | temporal-awareness-mcp |\n|---|---|---|---|\n| Decision rules | 7 triggers | None | None |\n| Tool-use ledger | JSONL, per-call timing | None | None |\n| Session baseline | SessionStart hook | Single date injection | API call per request |\n| Per-turn elapsed | UserPromptSubmit hook | None | None |\n| Idle detection | Stop hook | None | None |\n| Degraded mode | Graceful fallback with explicit disclosure | N/A | N/A |\n| Platforms | 8 | Claude Code only | Any MCP client |\n| Shell | bash plus PowerShell | bash | Node.js |\n| Install | `./install.sh` (non-destructive merge) | Manual symlink | MCP client config |\n\n`hodgesmr/temporal-awareness` is the prior Claude Code skill in this space. It shells `date` once at session start. No ledger, no decision rules, no multi-platform.\n\nThe MCP servers (`pmbstyle/temporal-awareness-mcp`, `@vreme/temporal-mcp`) provide time data to MCP-compatible clients. They do not ship decision rules and require separate MCP infrastructure.\n\n---\n\n## Install\n\n### Claude Code (full hook stack)\n\n```bash\ngit clone https://github.com/OthmanAdi/chronos ~/chronos\ncd ~/chronos\n./installers/claude-code/install.sh         # user scope\n./installers/claude-code/install.sh --project  # project scope only\n```\n\nMerges hooks into `~/.claude/settings.json` without clobbering existing hooks. Backs up the original.\n\nVerify: start a Claude Code session. You should see `chronos baseline` in context. Run a few tools, then:\n\n```bash\ntail ~/.chronos/ledger-*.jsonl\n```\n\n### Codex\n\n```bash\n./installers/codex/install.sh\n```\n\nInstalls `~/.codex/hooks.json` and enables `[features] codex_hooks = true` in `~/.codex/config.toml`.\n\n### OpenCode\n\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp installers/opencode/plugin.ts ~/.config/opencode/plugins/chronos.ts\nmkdir -p ~/.config/opencode/skills/chronos\ncp SKILL.md ~/.config/opencode/skills/chronos/SKILL.md\n```\n\n### Cursor\n\n```bash\nmkdir -p ~/.cursor/rules\ncp .cursor/rules/chronos.mdc ~/.cursor/rules/\n```\n\n### Other platforms\n\nSee `installers/<platform>/README.md`.\n\n### Uninstall\n\n```bash\n./installers/claude-code/install.sh --uninstall\n```\n\nRemoves all chronos hooks from settings.json, backs up the original, deletes `~/.claude/skills/chronos/`.\n\n---\n\n## Configuration\n\nSet these environment variables before running Claude Code (or add to shell profile):\n\n| Variable | Default | Effect |\n|---|---|---|\n| `CHRONOS_HOME` | `~/.chronos` | Ledger and state directory |\n| `CHRONOS_IDLE_THRESHOLD_SEC` | `900` | Seconds before idle warning fires in autonomous mode |\n| `CHRONOS_LEDGER_RETENTION_DAYS` | `30` | Delete ledgers older than this many days |\n| `CHRONOS_LEDGER_GZIP_AFTER_DAYS` | `1` | Compress ledgers older than this many days |\n\n---\n\n## Usage\n\n### Query the ledger directly\n\n```bash\n# Last 10 events\ntail -n 10 ~/.chronos/ledger-*.jsonl\n\n# Events in the last 10 minutes\n./scripts/ledger_read.sh --since 10m\n\n# All Bash calls in the last hour\n./scripts/ledger_read.sh --tool Bash --since 1h\n\n# Count by tool type\n./scripts/ledger_read.sh --since 1h | jq -s 'group_by(.tool) | map({tool:.[0].tool, count:length})'\n```\n\n### Check session state\n\n```bash\ncat ~/.chronos/session-$(cat ~/.chronos/current-session).json\n# { \"started_at_utc\": \"...\", \"turn\": 12, \"session_duration_sec\": 847, ... }\n```\n\n---\n\n## Ledger schema\n\nJSONL, append-only. Two events per tool call:\n\n```json\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1d2c3b4a5\",\"started_at\":\"2026-04-23T20:00:00Z\",\"started_epoch\":1777233600}\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1d2c3b4a5\",\"finished_at\":\"2026-04-23T20:00:12Z\",\"finished_epoch\":1777233612,\"duration_ms\":12000,\"success\":true}\n```\n\n`args_hash` is SHA-256 of the serialized tool arguments, first 12 hex characters. Use it to correlate start and finish events, and to detect repeated identical calls.\n\n---\n\n## Architecture\n\n```\nchronos/\n  SKILL.md                      portable decision rules (primary)\n  AGENTS.md                     mirror for Codex, ADAL, OpenClaw, Hermes, PI\n  .cursor/rules/chronos.mdc     Cursor degraded-mode rule\n  scripts/\n    _lib.sh  _lib.ps1           shared library (time functions, ledger helpers)\n    session_start.sh  .ps1      SessionStart hook\n    prompt_submit.sh  .ps1      UserPromptSubmit hook\n    pre_tool.sh  .ps1           PreToolUse hook\n    post_tool.sh  .ps1          PostToolUse hook\n    stop.sh  .ps1               Stop hook\n    ledger_read.sh  .ps1        ledger query utility\n  installers/\n    claude-code/                flagship installer\n    codex/\n    opencode/\n    cursor/\n    hermes/  pi/  openclaw/  adal/\n    detect-shell.sh\n```\n\nRuntime state lives at `~/.chronos/`:\n\n- `ledger-<session>.jsonl`: append-only tool-use event log\n- `session-<session>.json`: baseline, turn counter, last_user_at timestamp\n- `current-session`: session ID fallback for platforms without stdin session_id injection\n\n---\n\n## Design principles\n\n- **Honest degradation.** If a platform cannot do hooks, SKILL.md tells the agent explicitly what fallback to use and requires disclosure.\n- **Async where possible.** PreToolUse and PostToolUse run with `async: true`, adding zero latency to tool calls.\n- **Portable core.** SKILL.md works on every supported platform. Hook scripts are an optional enhancement layer.\n- **Cross-platform parity.** Every bash script has a PowerShell counterpart. No `jq` required on Windows.\n- **Self-cleaning.** Ledgers compress after 1 day and delete after 30. No manual maintenance.\n\n---\n\n## Why this was built\n\nNo existing tool combined: hook-backed timing, per-turn elapsed counters, a queryable tool-use ledger, and decision rules that change agent behavior, deployed across multiple agent platforms in a single installable skill.\n\nAcademic context: [Your LLM Agents are Temporally Blind](https://arxiv.org/abs/2510.23853) (Oct 2025) evaluated LLM temporal reasoning on the TicToc dataset (1,800 multi-turn dialogues, 76 scenario types). The measured gap exists even when frontier models have timestamps available. The fix is not more timestamps. It is explicit rules for *when to consult them*.\n\n---\n\n## Credits\n\nBuilt by [OthmanAdi](https://github.com/OthmanAdi). MIT licensed.\n\nPrior art and references:\n\n- [hodgesmr/temporal-awareness](https://github.com/hodgesmr/temporal-awareness): prior Claude Code skill, date-shelling only\n- [Claude Code hooks](https://code.claude.com/docs/en/hooks): hook event reference\n- [Codex CLI hooks](https://developers.openai.com/codex/hooks): Codex hook configuration\n- [arxiv 2510.23853](https://arxiv.org/abs/2510.23853): temporal blindness empirical study\n- [GitHub issue #24182](https://github.com/anthropics/claude-code/issues/24182): open request for native per-turn timestamps in Claude Code\n\n---\n\n## License\n\nMIT\n\nFile v0.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn73c6y92fm99h1q8rbmnw4em97zz97d\",\n  \"slug\": \"chronos-2\",\n  \"version\": \"0.1.1\",\n  \"publishedAt\": 1788383833737\n}\n\nFile v0.1.1:AGENTS.md\n\n# chronos — Time Awareness (AGENTS.md mirror)\n\nThis file mirrors SKILL.md for agents that load `AGENTS.md` instead of or in addition to skills (Codex, ADAL, OpenClaw, Hermes, PI-mono).\n\nSee `SKILL.md` for the full spec. Quick reference below.\n\n## You have a ledger (or you don't)\n\nIf hooks are installed on your platform (Claude Code, Codex, OpenCode-plugin), you'll see `chronos baseline` in your context at session start with:\n- `now_utc`, `now_local`, `tz`, `ledger` path, `state` path, `session` id\n\nOn every user turn:\n- `now_utc`, `turn`, `session_duration`, `since_last_user`\n\nTool-use ledger at `ledger` path is JSONL — one line per event:\n- PreToolUse: `{tool_use_id, tool, args_hash, started_at, started_epoch}`\n- PostToolUse: `{tool_use_id, tool, finished_at, finished_epoch, duration_ms, success}`\n\nIf not installed: use `date -u` + `stat -c %Y` as fallback. State it explicitly.\n\n## 7 triggers — when to consult time\n\n1. **Retry check.** Same tool + args_hash failed < 60s ago → change strategy. 10min+ → re-run ok.\n2. **Staleness check.** git/processes > 5min, files > 1h or modified-since, memory > 7 days, API > 5min.\n3. **Progress verbosity.** < 5min terse, 5–30min paragraph, > 30min structured recap.\n4. **Long-command degradation.** Last 3 durations growing? Surface, don't wait silently.\n5. **Idle-loop.** `since_last_user > 15min` in autonomous mode → pause, summarize, ask.\n6. **No vague time.** Replace \"just now\" / \"a moment\" with concrete delta from ledger.\n7. **Date questions.** Read SessionStart baseline if fresh, else `date -u`.\n\n## Read the ledger\n\n```bash\n# last 10 min of events\nscripts/ledger_read.sh --since 10m\n\n# last 3 Bash runs\nscripts/ledger_read.sh --tool Bash | tail -n 6\n\n# specific args_hash\nscripts/ledger_read.sh --tool Bash --args-hash abc123 --last\n```\n\n## Failure modes\n\n- Don't count turns for elapsed time — use wall clock.\n- Don't trust your own \"just now\" from earlier in context.\n- Don't hang silently in autonomous mode.\n- If no ledger: say so, use shell fallback.\n\nSee `SKILL.md` for full detail.\n\nFile v0.1.1:CHANGELOG.md\n\n# Changelog\n\n## v1.0.0 (2026-04-24)\n\nInitial release.\n\n**Core skill:**\n- SKILL.md with 7 temporal decision triggers for AI coding agents\n- Staleness thresholds table by source type (git status, file contents, persistent memory, external APIs, build results)\n- Degraded mode instructions for platforms without hook support\n- `args_hash` documentation for ledger-based retry detection\n\n**Hook stack:**\n- SessionStart: injects UTC baseline, timezone, ledger path, session ID\n- UserPromptSubmit: per-turn elapsed counters (turn, session_duration, since_last_user)\n- PreToolUse: records tool call start to JSONL ledger\n- PostToolUse: records tool call finish with duration_ms and success flag\n- Stop: idle detection for autonomous agents, configurable threshold\n\n**Platform support:**\n- Full hook stack: Claude Code, Codex CLI\n- Partial (TS plugin or extension): OpenCode, PI, OpenClaw\n- Skill-only degraded mode: Cursor, Hermes, ADAL\n\n**Scripts:**\n- bash and PowerShell parity for all 5 hooks plus ledger_read utility\n- jq-optional on Windows via PowerShell ConvertFrom-Json fallback\n- Ledger self-cleanup: gzip after 1 day, delete after 30 days\n\n**Installer:**\n- Non-destructive array concat merge into settings.json (no existing hook clobber)\n- Backup before every write\n- `--uninstall` flag: removes chronos hooks and skill directory cleanly\n- `--dry-run` flag: shows diff without writing\n- Project scope (`--project`) and user scope support\n\nFile v0.1.1:CONTRIBUTING.md\n\n# Contributing\n\n## Adding a platform port\n\nTo add chronos support for a new agent platform:\n\n1. Create `installers/<platform>/README.md` describing the platform's hook or plugin API\n2. Write the context injection: SessionStart must emit `now_utc`, `now_local`, `tz`, `ledger`, `state`, `session`\n3. Write per-turn injection: UserPromptSubmit must emit `turn`, `session_duration`, `since_last_user`\n4. Write the ledger writer: PreToolUse appends `started_at`, PostToolUse appends `finished_at + duration_ms + success`\n5. If the platform has no hook API, add a `SKILL-only` entry to the platform matrix in README.md with degraded mode instructions\n6. Test with a pre-existing hook in the config (verify the installer does not clobber it)\n\n## Reporting a bug\n\nOpen an issue with:\n- Platform and version (Claude Code 1.x, Codex CLI x.y, etc.)\n- Shell (bash, zsh, PowerShell version)\n- What you ran and what you expected\n- The relevant ledger output if available (`tail ~/.chronos/ledger-*.jsonl`)\n\n## Pull request rules\n\n- No new runtime dependencies. bash, PowerShell, and optionally jq are the only allowed tools.\n- All script changes must work on both bash and PowerShell (add `.ps1` counterpart for any new `.sh` script)\n- Run the installer with a pre-existing hook in `~/.claude/settings.json` and confirm it is preserved\n- Keep SKILL.md under 500 lines\n- No Co-Authored-By in commits\n\nArchive v0.1.0: 54 files, 5117054 bytes\n\nFiles: .cursor (0b), .cursor/rules (0b), .cursor/rules/chronos.mdc (1787b), .gitignore (51b), AGENTS.md (2070b), assets (0b), assets/banner.png (2985450b), assets/profile-banner.png (2103440b), CHANGELOG.md (1441b), CONTRIBUTING.md (1386b), installers (0b), installers/adal (0b), installers/adal/README.md (483b), installers/claude-code (0b), installers/claude-code/install.sh (4615b), installers/claude-code/settings.json (1321b), installers/claude-code/settings.windows-ps.json (1155b), installers/codex (0b), installers/codex/config.toml.fragment (108b), installers/codex/hooks.json (829b), installers/codex/install.sh (1685b), installers/cursor (0b), installers/cursor/README.md (579b), installers/detect-shell.sh (872b), installers/hermes (0b), installers/hermes/README.md (493b), installers/openclaw (0b), installers/openclaw/README.md (551b), installers/opencode (0b), installers/opencode/plugin.ts (3572b), installers/opencode/README.md (981b), installers/pi (0b), installers/pi/README.md (854b), LICENSE (1079b), package.json (826b), README.md (10789b), scripts (0b), scripts/_lib.ps1 (3874b), scripts/_lib.sh (4026b), scripts/ledger_read.ps1 (1644b), scripts/ledger_read.sh (2055b), scripts/post_tool.ps1 (1270b), scripts/post_tool.sh (1879b), scripts/pre_tool.ps1 (812b), scripts/pre_tool.sh (1355b), scripts/prompt_submit.ps1 (1969b), scripts/prompt_submit.sh (2463b), scripts/session_start.ps1 (1335b), scripts/session_start.sh (1665b), scripts/stop.ps1 (602b), scripts/stop.sh (898b), skill-card.md (1964b), SKILL.md (7717b), _meta.json (128b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: chronos\ndescription: 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.\nversion: 1.0.0\nlicense: MIT\nauthor: OthmanAdi\ntags: [time, temporal, autonomy, ledger, agents, hooks, session-management]\nhomepage: https://aware-bloom-szmt.here.now\nrepository: https://github.com/OthmanAdi/chronos\nallowed-tools: Read, Bash(date *), Bash(stat *), Bash(cat *), Bash(jq *), Bash(ls *), Bash(git log *), Bash(git status *)\n---\n\n# Chronos — Time Awareness for Agents\n\nYou are not temporally blind. Stop guessing \"when\" and \"how long ago\". You have a ledger. Use it.\n\n## What chronos gives you\n\nWhen the host platform supports hooks (Claude Code, Codex, OpenCode-plugin), chronos populates three sources of truth:\n\n1. **SessionStart baseline** — injected into your context at session start:\n   - `now_utc` — ISO-8601 UTC\n   - `now_local` — ISO-8601 with offset\n   - `tz` — timezone name + offset\n   - `ledger` — absolute path to this session's JSONL tool-use ledger\n   - `state` — absolute path to this session's state file\n   - `session` — session ID\n\n2. **Per-turn delta** — injected on every user message:\n   - `now`, `turn`, `session_duration`, `since_last_user`\n\n3. **Tool-use ledger** — JSONL file, one entry per tool invocation:\n   - `{tool_use_id, tool, args_hash, started_at, finished_at, duration_ms, success}`\n\nIf 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\".\n\n## When to consult time — 7 triggers\n\n### 1. Before retrying a failed command\n\nRead the ledger for the same `tool` + `args_hash`.\n\n- If the last failure was `< 60s` ago with the same args, **change strategy** — don't re-run identically.\n- If `60s – 10min`, consider one retry with a rationale.\n- If `> 10min`, circumstances may have changed; re-run is reasonable.\n\n**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.\n\n### 2. Before trusting memory, a cached finding, or a prior read\n\nStaleness thresholds by source:\n\n| Source | Stale after | Action when stale |\n|---|---|---|\n| `git status`, running processes, env vars | 5 min (same session) | Re-query |\n| File contents previously Read | 1 hr OR any write to that path since Read | Re-Read |\n| Persistent memory (MemPalace, KG facts) | 7 days since last write | Re-verify before use |\n| External API responses (prices, PR status, issues) | 5 min | Re-fetch |\n| Build/test results | After any source change since that run | Re-run |\n| LLM's own prior claim (\"earlier I saw...\") | Always verify against ledger | Consult ledger |\n\n### 3. Before reporting progress or writing a summary\n\nUse `session_duration` to pick verbosity:\n\n- `< 5 min` — terse answer, no recap.\n- `5 – 30 min` — one-paragraph summary of what changed.\n- `> 30 min` — structured recap with timestamped milestones from the ledger.\n\n### 4. Before running a long or destructive command\n\nScan 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.\n\n### 5. Idle-loop detection (autonomous mode)\n\nWhenever `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.\n\nFor explicit autonomous loops (`/loop`, `/autonomous`), the threshold may be higher — but always escalate when `session_duration > 2h` without user input.\n\n### 6. Before any \"wait\" / \"in a few minutes\" / \"just now\" statement\n\nReplace imprecise language with a concrete delta from the ledger:\n\n- ❌ \"Just tried that.\"\n- ✅ \"Last attempt was 47s ago (tool_use_id abc123, failed with EACCES).\"\n\n- ❌ \"Let's wait a moment.\"\n- ✅ \"Retry at 2026-04-23T20:45:00Z (+3 min from now).\"\n\n### 7. Date or time questions\n\nNever guess. In order of preference:\n\n1. Read `now_utc` / `now_local` from the SessionStart context if `session_duration < 10 min`.\n2. Read latest `finished_at` in the ledger if `< 10 min` ago.\n3. Run `date -u +\"%Y-%m-%dT%H:%M:%SZ\"` fresh.\n\n## How to read the ledger\n\nLedger path is injected as `ledger: <path>` in SessionStart context.\n\n**One line = one event** (JSONL, append-only). Latest line for a given `tool_use_id` wins.\n\n```bash\n# Last 10 events\ntail -n 10 \"$LEDGER_PATH\"\n\n# Events in last 10 minutes (helper script)\n./scripts/ledger_read.sh --since 10m\n\n# Events for a specific tool in last hour\n./scripts/ledger_read.sh --tool Bash --since 1h\n\n# Last duration for a specific args_hash\n./scripts/ledger_read.sh --tool Bash --args-hash abc123 --last\n```\n\nEntry shape:\n\n```json\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1\",\"started_at\":\"2026-04-23T20:00:00Z\"}\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1\",\"finished_at\":\"2026-04-23T20:00:12Z\",\"duration_ms\":12034,\"success\":true}\n```\n\nTwo lines per tool call: one on PreToolUse (started_at), one on PostToolUse (finished_at + duration). This is deliberate — async writes avoid adding latency.\n\n`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.\n\n## Failure modes to avoid\n\n- **Do not** re-derive elapsed time by counting messages or turns. Use wall clock from ledger.\n- **Do not** trust your own prior claim of \"just now\" from earlier in context. Ledger is the source of truth.\n- **Do not** issue \"try again in a few minutes\" without a concrete ISO timestamp or delta.\n- **Do not** silently hang in autonomous mode. Trigger #5 always applies.\n- **Do not** assume the ledger exists. Check for `ledger: ` in your context first; degrade to `date -u` if absent.\n\n## Degraded mode (no hooks platform)\n\nIf 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:\n\n- Current time: `date -u +\"%Y-%m-%dT%H:%M:%SZ\"` (bash) or `Get-Date -AsUTC -Format o` (pwsh)\n- File mtime: `stat -c %Y <path>` (bash) or `(Get-Item <path>).LastWriteTimeUtc` (pwsh)\n- Git age: `git log -1 --format=%cI <path>` for last-commit ISO timestamp\n\nState this explicitly: \"No ledger on this platform; I'm using `date -u` as fallback.\"\n\n## Install / wiring\n\nSee `installers/<platform>/` for platform-specific setup:\n\n- `claude-code/` — full hook stack (5 events)\n- `codex/` — full hook stack (PreToolUse matches Bash only)\n- `opencode/` — TS plugin writes ledger; read via `ledger_read.sh`\n- `cursor/` — rules-only degraded mode\n- `hermes/`, `adal/`, `pi/`, `openclaw/` — SKILL-only ports\n\n## Why this matters\n\nFrom [arxiv 2510.23853](https://arxiv.org/html/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**.\n\nThis SKILL.md is those rules.\n\nFile v0.1.0:installers/adal/README.md\n\n# chronos — ADAL (SylphAI adal-cli)\n\nADAL supports Agent Skills. Drop SKILL.md into the ADAL skills location (docs at https://docs.sylph.ai/).\n\n## Install\n\n```bash\n# path may vary by ADAL version — check docs\nmkdir -p ~/.adal/skills/chronos\ncp SKILL.md ~/.adal/skills/chronos/SKILL.md\ncp AGENTS.md ~/.adal/skills/chronos/AGENTS.md\n```\n\n## Degraded mode only\n\nADAL hook API is not publicly documented. Chronos runs in SKILL-only mode: decision rules + shell fallback (`date -u`).\n\nFile v0.1.0:installers/cursor/README.md\n\n# chronos — Cursor\n\nCursor has no hooks. SKILL-only degraded mode via `.cursor/rules/chronos.mdc`.\n\n## Install (project)\n\n```bash\nmkdir -p .cursor/rules\ncp .cursor/rules/chronos.mdc .cursor/rules/chronos.mdc\n```\n\n## Install (user global)\n\n```bash\nmkdir -p ~/.cursor/rules\ncp .cursor/rules/chronos.mdc ~/.cursor/rules/chronos.mdc\n```\n\nRule has `alwaysApply: true` — agent sees it every chat.\n\n## What you get\n\n- Decision rules always in context\n- Instructions to run `date -u` + `stat` for time queries\n\n## What you don't get\n\nNo ledger, no per-turn delta, no idle detection.\n\nFile v0.1.0:installers/hermes/README.md\n\n# chronos — Hermes (NousResearch)\n\nHermes injects skills from `~/.hermes/skills/` as user messages. No shell hooks — SKILL-only mode.\n\n## Install\n\n```bash\nmkdir -p ~/.hermes/skills/chronos\ncp SKILL.md ~/.hermes/skills/chronos/SKILL.md\n```\n\nAgent will follow decision rules using shell fallback (`date -u`, `stat`).\n\n## What you get\n\n- Decision rules (7 triggers)\n- Shell-fallback time queries\n\n## What you don't get\n\n- Automatic ledger (no hooks)\n- Per-turn elapsed inject\n- Idle warnings\n\nFile v0.1.0:installers/openclaw/README.md\n\n# chronos — OpenClaw\n\nOpenClaw uses `skills/<name>/SKILL.md` (Agent Skills standard).\n\n## Install\n\n```bash\nmkdir -p skills/chronos\ncp SKILL.md skills/chronos/SKILL.md\ncp AGENTS.md skills/chronos/AGENTS.md\n```\n\n## Optional: plugin SDK for ledger\n\nOpenClaw has a plugin-sdk (`openclaw/plugin-sdk`). Time-awareness plugin stub:\n\n```ts\n// See openclaw/plugin-sdk docs for full wiring.\n// Hook into session + tool events, append to ~/.chronos/ledger-*.jsonl\n```\n\n## Degraded mode\n\nSKILL-only works fine. Agent follows decision rules with shell fallback.\n\nFile v0.1.0:installers/opencode/README.md\n\n# chronos — OpenCode install\n\nOpenCode plugins can't push arbitrary context into the model. Chronos works in \"ledger-only\" mode: the plugin writes the ledger + state file; SKILL.md instructs the agent to `Read` those files at decision points.\n\n## Install\n\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp installers/opencode/plugin.ts ~/.config/opencode/plugins/chronos.ts\n```\n\nAlso copy the portable `SKILL.md` to a skills location OpenCode loads:\n\n```bash\nmkdir -p ~/.config/opencode/skills/chronos\ncp SKILL.md ~/.config/opencode/skills/chronos/SKILL.md\n```\n\n## How the agent uses it\n\nSKILL.md tells the agent to:\n1. Read `~/.chronos/session-<sid>.json` for baseline + last_user timestamp\n2. Read `~/.chronos/ledger-<sid>.jsonl` for tool-use history\n\nNo `additionalContext` injection on this platform — honest degraded mode.\n\n## Env\n\n- `CHRONOS_HOME` — override ledger location (default: `~/.chronos`)\n- `CHRONOS_IDLE_THRESHOLD_SEC` — idle warning threshold (default: 900)\n\nFile v0.1.0:installers/pi/README.md\n\n# chronos — PI (badlogic/pi-mono)\n\nPI supports Agent Skills. Copy SKILL.md into skills directory.\n\n## Install\n\n```bash\nmkdir -p ~/.pi/skills/chronos\ncp SKILL.md ~/.pi/skills/chronos/SKILL.md\n```\n\n## Optional: ledger via PI extension\n\nPI exposes `pi.on(\"tool_call\", ...)` event API. To add a ledger:\n\n```ts\n// example extension stub — see pi-mono docs for full wiring\nimport { pi } from \"@badlogic/pi\";\nimport * as fs from \"fs\";\nimport * as path from \"path\";\nimport * as os from \"os\";\n\nconst LEDGER = path.join(os.homedir(), \".chronos\", \"ledger-pi.jsonl\");\n\npi.on(\"tool_call\", (ev) => {\n  fs.appendFileSync(LEDGER, JSON.stringify({\n    tool: ev.name,\n    started_at: new Date().toISOString(),\n    duration_ms: ev.duration_ms,\n    success: !ev.error,\n  }) + \"\\n\");\n});\n```\n\n## Degraded mode\n\nWithout extension: SKILL rules still apply, shell-fallback.\n\nFile v0.1.0:README.md\n\n# chronos\n\n![How AI reacts when you ask what time it is](assets/banner.png)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)\n[![Platforms](https://img.shields.io/badge/platforms-8-black)](README.md#platform-matrix)\n[![Paper](https://img.shields.io/badge/arxiv-2510.23853-black)](https://arxiv.org/abs/2510.23853)\n\n**Time awareness for AI coding agents.** Stops your agent from guessing \"when\" and \"how long ago\".\n\n```bash\nnpx skills add OthmanAdi/chronos --skill chronos -g\n```\n\nOr from npm: `pi install npm:chronos-skill` ([package](https://www.npmjs.com/package/chronos-skill); the bare `chronos` name on npm belongs to an unrelated project)\n\nWorks across Claude Code, Codex, OpenCode, Cursor, PI, OpenClaw, Hermes, ADAL.\n\n---\n\n## The problem\n\nLLMs do not know what time it is. They guess. They report \"just now\" when it was two hours ago. They retry failed commands without checking that the last attempt was 10 seconds ago. They run silently in autonomous loops with no idle detection.\n\n[Arxiv 2510.23853](https://arxiv.org/abs/2510.23853) measured this empirically: even frontier models with timestamps injected into context reach only **65% temporal reasoning alignment** with human judgment. Timestamps appear in fewer than 4% of reasoning traces. The ceiling exists because having access to timestamps is not enough. Agents need explicit rules for *when to look at the clock*.\n\nChronos is those rules, backed by a queryable tool-use ledger.\n\n---\n\n## What chronos gives you\n\n### 1. Portable decision rules — SKILL.md\n\nSeven triggers that govern when an agent must consult time:\n\n1. Before retrying a failed command: check the ledger for the last attempt and elapsed time\n2. Before trusting memory or a cached result: apply staleness thresholds by source type\n3. Before reporting progress: use `session_duration` to set summary verbosity\n4. Before running a long or destructive command: detect tool degradation from ledger timing\n5. Idle-loop detection: pause and surface decisions when the agent runs without user input too long\n6. Before any \"just now\" or \"in a minute\" statement: replace with a concrete ISO delta from the ledger\n7. Date and time questions: consult the baseline first, never guess\n\n### 2. Hook-backed automation (Claude Code, Codex, OpenCode)\n\nFour hook events populate three data sources on every session:\n\n```mermaid\nsequenceDiagram\n    participant A as Agent\n    participant H as Hook Scripts\n    participant L as ~/.chronos/\n\n    Note over A,L: Session start\n    H->>L: Initialize ledger + state file\n    H->>A: Inject baseline (now_utc, tz, ledger path, session ID)\n\n    Note over A,L: Each user message\n    H->>L: Increment turn counter, record last_user_at\n    H->>A: Inject per-turn delta (turn, session_duration, since_last_user)\n\n    Note over A,L: Each tool call\n    H->>L: Append started_at + args_hash (PreToolUse)\n    Note over H,L: Tool executes\n    H->>L: Append finished_at + duration_ms + success (PostToolUse)\n\n    Note over A,L: Session end\n    H->>A: Check idle time, emit warning if autonomous threshold exceeded\n```\n\n### 3. Honest degraded mode (Cursor, Hermes, ADAL)\n\nPlatforms without hook support still get full decision rules. SKILL.md instructs the agent to use `date -u`, `stat`, and `git log` as fallback sources and to state explicitly which source it used.\n\n---\n\n## Platform matrix\n\n| Platform | Support | What you get |\n|---|---|---|\n| **Claude Code** | Full | All 5 hooks plus SKILL.md |\n| **Codex CLI** | Full | All 5 hooks (PreToolUse targets Bash only) plus AGENTS.md |\n| **OpenCode** | Partial | TypeScript plugin writes ledger; SKILL reads it |\n| **PI (pi-mono)** | Partial | SKILL plus optional extension for ledger |\n| **OpenClaw** | Partial | SKILL plus optional plugin-sdk for ledger |\n| **Cursor** | Skill-only | Always-on rule with shell-fallback instructions |\n| **Hermes** | Skill-only | SKILL injects as user message |\n| **ADAL** | Skill-only | SKILL.md only (hook API not public) |\n\n---\n\n## vs. prior art\n\n| | **chronos** | hodgesmr/temporal-awareness | temporal-awareness-mcp |\n|---|---|---|---|\n| Decision rules | 7 triggers | None | None |\n| Tool-use ledger | JSONL, per-call timing | None | None |\n| Session baseline | SessionStart hook | Single date injection | API call per request |\n| Per-turn elapsed | UserPromptSubmit hook | None | None |\n| Idle detection | Stop hook | None | None |\n| Degraded mode | Graceful fallback with explicit disclosure | N/A | N/A |\n| Platforms | 8 | Claude Code only | Any MCP client |\n| Shell | bash plus PowerShell | bash | Node.js |\n| Install | `./install.sh` (non-destructive merge) | Manual symlink | MCP client config |\n\n`hodgesmr/temporal-awareness` is the prior Claude Code skill in this space. It shells `date` once at session start. No ledger, no decision rules, no multi-platform.\n\nThe MCP servers (`pmbstyle/temporal-awareness-mcp`, `@vreme/temporal-mcp`) provide time data to MCP-compatible clients. They do not ship decision rules and require separate MCP infrastructure.\n\n---\n\n## Install\n\n### Claude Code (full hook stack)\n\n```bash\ngit clone https://github.com/OthmanAdi/chronos ~/chronos\ncd ~/chronos\n./installers/claude-code/install.sh         # user scope\n./installers/claude-code/install.sh --project  # project scope only\n```\n\nMerges hooks into `~/.claude/settings.json` without clobbering existing hooks. Backs up the original.\n\nVerify: start a Claude Code session. You should see `chronos baseline` in context. Run a few tools, then:\n\n```bash\ntail ~/.chronos/ledger-*.jsonl\n```\n\n### Codex\n\n```bash\n./installers/codex/install.sh\n```\n\nInstalls `~/.codex/hooks.json` and enables `[features] codex_hooks = true` in `~/.codex/config.toml`.\n\n### OpenCode\n\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp installers/opencode/plugin.ts ~/.config/opencode/plugins/chronos.ts\nmkdir -p ~/.config/opencode/skills/chronos\ncp SKILL.md ~/.config/opencode/skills/chronos/SKILL.md\n```\n\n### Cursor\n\n```bash\nmkdir -p ~/.cursor/rules\ncp .cursor/rules/chronos.mdc ~/.cursor/rules/\n```\n\n### Other platforms\n\nSee `installers/<platform>/README.md`.\n\n### Uninstall\n\n```bash\n./installers/claude-code/install.sh --uninstall\n```\n\nRemoves all chronos hooks from settings.json, backs up the original, deletes `~/.claude/skills/chronos/`.\n\n---\n\n## Configuration\n\nSet these environment variables before running Claude Code (or add to shell profile):\n\n| Variable | Default | Effect |\n|---|---|---|\n| `CHRONOS_HOME` | `~/.chronos` | Ledger and state directory |\n| `CHRONOS_IDLE_THRESHOLD_SEC` | `900` | Seconds before idle warning fires in autonomous mode |\n| `CHRONOS_LEDGER_RETENTION_DAYS` | `30` | Delete ledgers older than this many days |\n| `CHRONOS_LEDGER_GZIP_AFTER_DAYS` | `1` | Compress ledgers older than this many days |\n\n---\n\n## Usage\n\n### Query the ledger directly\n\n```bash\n# Last 10 events\ntail -n 10 ~/.chronos/ledger-*.jsonl\n\n# Events in the last 10 minutes\n./scripts/ledger_read.sh --since 10m\n\n# All Bash calls in the last hour\n./scripts/ledger_read.sh --tool Bash --since 1h\n\n# Count by tool type\n./scripts/ledger_read.sh --since 1h | jq -s 'group_by(.tool) | map({tool:.[0].tool, count:length})'\n```\n\n### Check session state\n\n```bash\ncat ~/.chronos/session-$(cat ~/.chronos/current-session).json\n# { \"started_at_utc\": \"...\", \"turn\": 12, \"session_duration_sec\": 847, ... }\n```\n\n---\n\n## Ledger schema\n\nJSONL, append-only. Two events per tool call:\n\n```json\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1d2c3b4a5\",\"started_at\":\"2026-04-23T20:00:00Z\",\"started_epoch\":1777233600}\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1d2c3b4a5\",\"finished_at\":\"2026-04-23T20:00:12Z\",\"finished_epoch\":1777233612,\"duration_ms\":12000,\"success\":true}\n```\n\n`args_hash` is SHA-256 of the serialized tool arguments, first 12 hex characters. Use it to correlate start and finish events, and to detect repeated identical calls.\n\n---\n\n## Architecture\n\n```\nchronos/\n  SKILL.md                      portable decision rules (primary)\n  AGENTS.md                     mirror for Codex, ADAL, OpenClaw, Hermes, PI\n  .cursor/rules/chronos.mdc     Cursor degraded-mode rule\n  scripts/\n    _lib.sh  _lib.ps1           shared library (time functions, ledger helpers)\n    session_start.sh  .ps1      SessionStart hook\n    prompt_submit.sh  .ps1      UserPromptSubmit hook\n    pre_tool.sh  .ps1           PreToolUse hook\n    post_tool.sh  .ps1          PostToolUse hook\n    stop.sh  .ps1               Stop hook\n    ledger_read.sh  .ps1        ledger query utility\n  installers/\n    claude-code/                flagship installer\n    codex/\n    opencode/\n    cursor/\n    hermes/  pi/  openclaw/  adal/\n    detect-shell.sh\n```\n\nRuntime state lives at `~/.chronos/`:\n\n- `ledger-<session>.jsonl`: append-only tool-use event log\n- `session-<session>.json`: baseline, turn counter, last_user_at timestamp\n- `current-session`: session ID fallback for platforms without stdin session_id injection\n\n---\n\n## Design principles\n\n- **Honest degradation.** If a platform cannot do hooks, SKILL.md tells the agent explicitly what fallback to use and requires disclosure.\n- **Async where possible.** PreToolUse and PostToolUse run with `async: true`, adding zero latency to tool calls.\n- **Portable core.** SKILL.md works on every supported platform. Hook scripts are an optional enhancement layer.\n- **Cross-platform parity.** Every bash script has a PowerShell counterpart. No `jq` required on Windows.\n- **Self-cleaning.** Ledgers compress after 1 day and delete after 30. No manual maintenance.\n\n---\n\n## Why this was built\n\nNo existing tool combined: hook-backed timing, per-turn elapsed counters, a queryable tool-use ledger, and decision rules that change agent behavior, deployed across multiple agent platforms in a single installable skill.\n\nAcademic context: [Your LLM Agents are Temporally Blind](https://arxiv.org/abs/2510.23853) (Oct 2025) evaluated LLM temporal reasoning on the TicToc dataset (1,800 multi-turn dialogues, 76 scenario types). The measured gap exists even when frontier models have timestamps available. The fix is not more timestamps. It is explicit rules for *when to consult them*.\n\n---\n\n## Credits\n\nBuilt by [OthmanAdi](https://github.com/OthmanAdi). MIT licensed.\n\nPrior art and references:\n\n- [hodgesmr/temporal-awareness](https://github.com/hodgesmr/temporal-awareness): prior Claude Code skill, date-shelling only\n- [Claude Code hooks](https://code.claude.com/docs/en/hooks): hook event reference\n- [Codex CLI hooks](https://developers.openai.com/codex/hooks): Codex hook configuration\n- [arxiv 2510.23853](https://arxiv.org/abs/2510.23853): temporal blindness empirical study\n- [GitHub issue #24182](https://github.com/anthropics/claude-code/issues/24182): open request for native per-turn timestamps in Claude Code\n\n---\n\n## License\n\nMIT\n\nFile v0.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn73c6y92fm99h1q8rbmnw4em97zz97d\",\n  \"slug\": \"chronos-2\",\n  \"version\": \"0.1.0\",\n  \"publishedAt\": 1788114014123\n}\n\nFile v0.1.0:AGENTS.md\n\n# chronos — Time Awareness (AGENTS.md mirror)\n\nThis file mirrors SKILL.md for agents that load `AGENTS.md` instead of or in addition to skills (Codex, ADAL, OpenClaw, Hermes, PI-mono).\n\nSee `SKILL.md` for the full spec. Quick reference below.\n\n## You have a ledger (or you don't)\n\nIf hooks are installed on your platform (Claude Code, Codex, OpenCode-plugin), you'll see `chronos baseline` in your context at session start with:\n- `now_utc`, `now_local`, `tz`, `ledger` path, `state` path, `session` id\n\nOn every user turn:\n- `now_utc`, `turn`, `session_duration`, `since_last_user`\n\nTool-use ledger at `ledger` path is JSONL — one line per event:\n- PreToolUse: `{tool_use_id, tool, args_hash, started_at, started_epoch}`\n- PostToolUse: `{tool_use_id, tool, finished_at, finished_epoch, duration_ms, success}`\n\nIf not installed: use `date -u` + `stat -c %Y` as fallback. State it explicitly.\n\n## 7 triggers — when to consult time\n\n1. **Retry check.** Same tool + args_hash failed < 60s ago → change strategy. 10min+ → re-run ok.\n2. **Staleness check.** git/processes > 5min, files > 1h or modified-since, memory > 7 days, API > 5min.\n3. **Progress verbosity.** < 5min terse, 5–30min paragraph, > 30min structured recap.\n4. **Long-command degradation.** Last 3 durations growing? Surface, don't wait silently.\n5. **Idle-loop.** `since_last_user > 15min` in autonomous mode → pause, summarize, ask.\n6. **No vague time.** Replace \"just now\" / \"a moment\" with concrete delta from ledger.\n7. **Date questions.** Read SessionStart baseline if fresh, else `date -u`.\n\n## Read the ledger\n\n```bash\n# last 10 min of events\nscripts/ledger_read.sh --since 10m\n\n# last 3 Bash runs\nscripts/ledger_read.sh --tool Bash | tail -n 6\n\n# specific args_hash\nscripts/ledger_read.sh --tool Bash --args-hash abc123 --last\n```\n\n## Failure modes\n\n- Don't count turns for elapsed time — use wall clock.\n- Don't trust your own \"just now\" from earlier in context.\n- Don't hang silently in autonomous mode.\n- If no ledger: say so, use shell fallback.\n\nSee `SKILL.md` for full detail.\n\nFile v0.1.0:CHANGELOG.md\n\n# Changelog\n\n## v1.0.0 (2026-04-24)\n\nInitial release.\n\n**Core skill:**\n- SKILL.md with 7 temporal decision triggers for AI coding agents\n- Staleness thresholds table by source type (git status, file contents, persistent memory, external APIs, build results)\n- Degraded mode instructions for platforms without hook support\n- `args_hash` documentation for ledger-based retry detection\n\n**Hook stack:**\n- SessionStart: injects UTC baseline, timezone, ledger path, session ID\n- UserPromptSubmit: per-turn elapsed counters (turn, session_duration, since_last_user)\n- PreToolUse: records tool call start to JSONL ledger\n- PostToolUse: records tool call finish with duration_ms and success flag\n- Stop: idle detection for autonomous agents, configurable threshold\n\n**Platform support:**\n- Full hook stack: Claude Code, Codex CLI\n- Partial (TS plugin or extension): OpenCode, PI, OpenClaw\n- Skill-only degraded mode: Cursor, Hermes, ADAL\n\n**Scripts:**\n- bash and PowerShell parity for all 5 hooks plus ledger_read utility\n- jq-optional on Windows via PowerShell ConvertFrom-Json fallback\n- Ledger self-cleanup: gzip after 1 day, delete after 30 days\n\n**Installer:**\n- Non-destructive array concat merge into settings.json (no existing hook clobber)\n- Backup before every write\n- `--uninstall` flag: removes chronos hooks and skill directory cleanly\n- `--dry-run` flag: shows diff without writing\n- Project scope (`--project`) and user scope support\n\nFile v0.1.0:CONTRIBUTING.md\n\n# Contributing\n\n## Adding a platform port\n\nTo add chronos support for a new agent platform:\n\n1. Create `installers/<platform>/README.md` describing the platform's hook or plugin API\n2. Write the context injection: SessionStart must emit `now_utc`, `now_local`, `tz`, `ledger`, `state`, `session`\n3. Write per-turn injection: UserPromptSubmit must emit `turn`, `session_duration`, `since_last_user`\n4. Write the ledger writer: PreToolUse appends `started_at`, PostToolUse appends `finished_at + duration_ms + success`\n5. If the platform has no hook API, add a `SKILL-only` entry to the platform matrix in README.md with degraded mode instructions\n6. Test with a pre-existing hook in the config (verify the installer does not clobber it)\n\n## Reporting a bug\n\nOpen an issue with:\n- Platform and version (Claude Code 1.x, Codex CLI x.y, etc.)\n- Shell (bash, zsh, PowerShell version)\n- What you ran and what you expected\n- The relevant ledger output if available (`tail ~/.chronos/ledger-*.jsonl`)\n\n## Pull request rules\n\n- No new runtime dependencies. bash, PowerShell, and optionally jq are the only allowed tools.\n- All script changes must work on both bash and PowerShell (add `.ps1` counterpart for any new `.sh` script)\n- Run the installer with a pre-existing hook in `~/.claude/settings.json` and confirm it is preserved\n- Keep SKILL.md under 500 lines\n- No Co-Authored-By in commits","readmeExcerpt":"Skill: Chronos Owner: othmanadi Summary: 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. Tags: latest:0.1.1 Version history: v0.1.1 | 2026-09-02T21:17:13.737Z | auto - Removed ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Last 10 events\ntail -n 10 \"$LEDGER_PATH\"\n\n# Events in last 10 minutes (helper script)\n./scripts/ledger_read.sh --since 10m\n\n# Events for a specific tool in last hour\n./scripts/ledger_read.sh --tool Bash --since 1h\n\n# Last duration for a specific args_hash\n./scripts/ledger_read.sh --tool Bash --args-hash abc123 --last"},{"language":"json","snippet":"{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1\",\"started_at\":\"2026-04-23T20:00:00Z\"}\n{\"tool_use_id\":\"abc\",\"tool\":\"Bash\",\"args_hash\":\"f0e1\",\"finished_at\":\"2026-04-23T20:00:12Z\",\"duration_ms\":12034,\"success\":true}"},{"language":"bash","snippet":"# path may vary by ADAL version — check docs\nmkdir -p ~/.adal/skills/chronos\ncp SKILL.md ~/.adal/skills/chronos/SKILL.md\ncp AGENTS.md ~/.adal/skills/chronos/AGENTS.md"},{"language":"bash","snippet":"mkdir -p .cursor/rules\ncp .cursor/rules/chronos.mdc .cursor/rules/chronos.mdc"},{"language":"bash","snippet":"mkdir -p ~/.cursor/rules\ncp .cursor/rules/chronos.mdc ~/.cursor/rules/chronos.mdc"},{"language":"bash","snippet":"mkdir -p ~/.hermes/skills/chronos\ncp SKILL.md ~/.hermes/skills/chronos/SKILL.md"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: chronos\ndescription: 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.\nversion: 1.0.0\nlicense: MIT\nauthor: OthmanAdi\ntags: [time, temporal, autonomy, ledger, agents, hooks, session-management]\nhomepage: https://aware-bloom-szmt.here.now\nrepository: https://github.com/OthmanAdi/chronos\nallowed-tools: Read, Bash(date *), Bash(stat *), Bash(cat *), Bash(jq *), Bash(ls *), Bash(git log *), Bash(git status *)\n---\n\n# Chronos — Time Awareness for Agents\n\nYou are not temporally blind. Stop guessing \"when\" and \"how long ago\". You have a ledger. Use it.\n\n## What chronos gives you\n\nWhen the host platform supports hooks (Claude Code, Codex, OpenCode-plugin), chronos populates three sources of truth:\n\n1. **SessionStart baseline** — injected into your context at session start:\n   - `now_utc` — ISO-8601 UTC\n   - `now_local` — ISO-8601 with offset\n   - `tz` — timezone name + offset\n   - `ledger` — absolute path to this session's JSONL tool-use ledger\n   - `state` — absolute path to this session's state file\n   - `session` — session ID\n\n2. **Per-turn delta** — injected on every user message:\n   - `now`, `turn`, `session_duration`, `since_last_user`\n\n3. **Tool-use ledger** — JSONL file, one entry per tool invocation:\n   - `{tool_use_id, tool, args_hash, started_at, finished_at, duration_ms, success}`\n\nIf 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\".\n\n## When to consult time — 7 triggers\n\n### 1. Before retrying a failed command\n\nRead the ledger for the same `tool` + `args_hash`.\n\n- If the last failure was `< 60s` ago with the same args, **change strategy** — don't re-run identically.\n- If `60s – 10min`, consider one retry with a rationale.\n- If `> 10min`, circumstances may have changed; re-run is reasonable.\n\n**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.\n\n### 2. Before trusting memory, a cached finding, or a prior read\n\nStaleness thresholds by source:\n\n| Source | Stale after | Action when stale |\n|---|---|---|\n| `git status`, running processes, env vars | 5 min (same session) | Re-query |\n| File contents previously Read | 1 hr OR any write to that path since Read | Re-Read |\n| Persistent memory (MemPalace, KG facts) | 7 days since last write | Re-verify before use |\n| External API responses (prices, PR status, issues) | 5 min | Re-fetch |\n| Build/test results | After any source change since that run | Re-run |\n| LLM's own prior claim (\"earlier I saw...\") | Always verify against ledge"},{"path":"installers/adal/README.md","content":"# chronos — ADAL (SylphAI adal-cli)\n\nADAL supports Agent Skills. Drop SKILL.md into the ADAL skills location (docs at https://docs.sylph.ai/).\n\n## Install\n\n```bash\n# path may vary by ADAL version — check docs\nmkdir -p ~/.adal/skills/chronos\ncp SKILL.md ~/.adal/skills/chronos/SKILL.md\ncp AGENTS.md ~/.adal/skills/chronos/AGENTS.md\n```\n\n## Degraded mode only\n\nADAL hook API is not publicly documented. Chronos runs in SKILL-only mode: decision rules + shell fallback (`date -u`)."},{"path":"installers/cursor/README.md","content":"# chronos — Cursor\n\nCursor has no hooks. SKILL-only degraded mode via `.cursor/rules/chronos.mdc`.\n\n## Install (project)\n\n```bash\nmkdir -p .cursor/rules\ncp .cursor/rules/chronos.mdc .cursor/rules/chronos.mdc\n```\n\n## Install (user global)\n\n```bash\nmkdir -p ~/.cursor/rules\ncp .cursor/rules/chronos.mdc ~/.cursor/rules/chronos.mdc\n```\n\nRule has `alwaysApply: true` — agent sees it every chat.\n\n## What you get\n\n- Decision rules always in context\n- Instructions to run `date -u` + `stat` for time queries\n\n## What you don't get\n\nNo ledger, no per-turn delta, no idle detection."},{"path":"installers/hermes/README.md","content":"# chronos — Hermes (NousResearch)\n\nHermes injects skills from `~/.hermes/skills/` as user messages. No shell hooks — SKILL-only mode.\n\n## Install\n\n```bash\nmkdir -p ~/.hermes/skills/chronos\ncp SKILL.md ~/.hermes/skills/chronos/SKILL.md\n```\n\nAgent will follow decision rules using shell fallback (`date -u`, `stat`).\n\n## What you get\n\n- Decision rules (7 triggers)\n- Shell-fallback time queries\n\n## What you don't get\n\n- Automatic ledger (no hooks)\n- Per-turn elapsed inject\n- Idle warnings"},{"path":"installers/openclaw/README.md","content":"# chronos — OpenClaw\n\nOpenClaw uses `skills/<name>/SKILL.md` (Agent Skills standard).\n\n## Install\n\n```bash\nmkdir -p skills/chronos\ncp SKILL.md skills/chronos/SKILL.md\ncp AGENTS.md skills/chronos/AGENTS.md\n```\n\n## Optional: plugin SDK for ledger\n\nOpenClaw has a plugin-sdk (`openclaw/plugin-sdk`). Time-awareness plugin stub:\n\n```ts\n// See openclaw/plugin-sdk docs for full wiring.\n// Hook into session + tool events, append to ~/.chronos/ledger-*.jsonl\n```\n\n## Degraded mode\n\nSKILL-only works fine. Agent follows decision rules with shell fallback."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"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. Skill: Chronos Owner: othmanadi Summary: 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. Tags: latest:0.1.1 Version history: v0.1.1 | 2026-09-02T21:17:13.737Z | auto - Removed","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1123,"uniquenessScore":50,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T00:50:22.542Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T00:50:22.542Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T22:07:28.621Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}