temporal-core

May 9, 2026 · View on GitHub

Claude Code agents lose track of time. This plugin fixes it in 5 seconds.

Aher et al. (2026) found that surfacing elapsed time 6× boosted LLM agent deadline performance — without changing the underlying model. temporal-core is the minimal Claude Code implementation. Your session sees fragments like:
[temporal-core] session elapsed: 12m 34s
[temporal-core] since last action: 47s
3 hooks. 0 dependencies. 0 config. Apache-2.0.

Install

In Claude Code:

/plugin marketplace add Evanyuan-builder/temporal-core
/plugin install temporal-core@temporal-core

Or clone manually:

git clone https://github.com/Evanyuan-builder/temporal-core \
  ~/.claude/plugins/temporal-core

Requires jq on PATH (brew install jq on macOS). If missing, hooks gracefully no-op rather than break your session.

LLM agents systematically fail under real-time deadlines because they do not natively represent elapsed time. Aher et al. (2026), Real-Time Deadlines Reveal Temporal Awareness Failures in LLM Strategic Dialogues, found that explicitly surfacing remaining time boosted negotiation acceptance odds 6× — without changing the underlying model.

temporal-core is the minimal implementation of that idea for Claude Code: three small hooks inject elapsed-time signals into the agent's context, and a bundled temporal-awareness skill teaches the agent how to reason with them — pacing decisions, deadline-aware prioritization, recency reasoning, honest "how long did this take" answers.

How it works

┌─────────────────────────────────────────────────┐
│ User submits prompt                             │
│   ↓                                             │
│ UserPromptSubmit hook                           │
│   → reads session-start timestamp               │
│   → computes elapsed                            │
│   → injects [temporal-core] session elapsed: …  │
│                                                 │
│ Agent sees the signal.                          │
│ The bundled skill teaches it what to do.        │
│                                                 │
│ Agent decides to use a tool                     │
│   ↓                                             │
│ PreToolUse hook                                 │
│   → reads last-action timestamp                 │
│   → injects [temporal-core] since last action: … │
└─────────────────────────────────────────────────┘

State lives in ${TMPDIR}/temporal-core/${SESSION_ID}/ — two files, both epoch seconds. No persistence beyond the session.

v0.1 scope

Does:

Per-session elapsed time at every user turn
Inter-action gap before every tool call
Auto-suppress noisy < 5s gaps
Graceful no-op if jq unavailable

Does not (yet):

Track time across sessions
Enforce or alert on deadlines
Integrate with memory recency weighting
Track wall-clock time of long-running tools

Roadmap

v0.1 — single-session elapsed signals (this release)
v0.2 — Memory Core integration (recency weighting), cross-session continuity, deadline-aware skills
v0.3 — MCP server form for cross-client use (Cursor, Codex CLI, Continue)
v1.0 — Stable API, plugin marketplace publish, full eval against Aher et al. methodology

Research basis

Aher et al., Real-Time Deadlines Reveal Temporal Awareness Failures in LLM Strategic Dialogues (2026) — arxiv.org/html/2601.13206v1
Cognee, Temporal Cognification: Time-Aware AI Memory for LLMs — cognee.ai/blog
Test of Time benchmark (2024) — arxiv.org/html/2406.09170v1
TIME multi-level benchmark (2026) — huggingface.co/papers/2505.12891

Contributing

Issues and PRs welcome. v0.1 is a probe — if you find the signals useful, tell us how; if you don't, tell us why. Both move v0.2 in the right direction.

License

Built as part of the Industrial OS substrate stack — alongside Memory Core, RoleCore, and EvanCore.