pvc-timestamp-hook

---
name: pvc-timestamp-hook
description: Installs a timestamp hook into a target project's .claude/settings.local.json so every prompt in that project arrives stamped with the current date, weekday, and time. Use when asked to "add the time hook", "make this project time-aware", "install timestamps in this project", "put the timestamp thing in another folder", or when Claude keeps not knowing the date or how much time passed between messages. Creates or merges the settings file, adds gitignore coverage, verifies the command, and never touches user-level settings or memory hooks. Needs the date command (Git Bash on Windows) or Python 3 as a fallback.
metadata:
  author: pvc
  version: "1.0.2"
license: Apache-2.0
---

<!-- SPDX-License-Identifier: Apache-2.0 -->

# pvc-timestamp-hook

Makes one project time-aware. Installs a UserPromptSubmit hook that echoes the
current date, weekday, and time into context on every message, so Claude knows
when days pass between conversations without a tool call on every message. Time
only: no memory hooks, no background service, one line of context per prompt.

## When to Use

- A project where Claude should know the real time and date on every prompt
- "Add the time hook here" or "make this folder time-aware"
- "Put the timestamp thing in <folder>"
- Claude in some project keeps reasoning from a stale session-start date

The target is one project folder at a time. Default target: the project the
session is opened in. If the request names another folder, use that folder.

## What This Skill Does Not Do

- Does not install memory hooks of any kind (recall or auto-save). Those are a
  separate, deliberate per-project choice you make by hand
- Does not answer "what time is it" (run `date` for that)
- Does not touch user-level `~/.claude/settings.json` or any existing hook
  entries in the target
- Does not change the terminal UI (that is the `showMessageTimestamps` setting)

## Trigger Examples

Should trigger on:

- "Add the time hook to this project"
- "Make my-website time-aware"
- "Install timestamps in my other repo"
- "Claude never knows the date in my other project, fix that one too"

Should NOT trigger on:

- "What time is it?" (a question, not an install)
- "Give this project the memory hooks" (manual memory opt-in, not this skill)
- "Show timestamps on my messages in the terminal" (UI setting, not a hook)

## The Hook

The exact block this skill installs. `"shell": "bash"` is written out so the
hook never runs in PowerShell, where `date` is an alias of Get-Date and rejects
this format; the format prints the weekday because "how many days passed" is
the whole point.

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "date \"+[Current time: %Y-%m-%d (%A) %H:%M]\"",
            "shell": "bash"
          }
        ]
      }
    ]
  }
}
```

Every prompt then arrives with a line like:

```
[Current time: 2026-07-25 (Saturday) 10:12]
```

## Install Steps

1. Resolve the target project folder. Default: the current session's project
   root. If the request names a different folder, resolve that path and confirm
   it exists before touching anything.
2. Pipe-test the command in bash before installing: `echo '{}' | date "+[Current time: %Y-%m-%d (%A) %H:%M]"`.
   Expect one bracketed line. If `date` is missing (no Git Bash), use the
   Python fallback command from Resilience below.
3. Check `<target>/.claude/settings.local.json`:
   - Missing: create it containing exactly the hook block above (Path A)
   - Exists and already contains the `[Current time:` command string: change
     nothing (Path C)
   - Exists without it: Read it first, then merge. Keep every existing key.
     Append this hook entry to the existing `UserPromptSubmit` array, or add
     the key if absent (Path B)
4. Validate: `python -m json.tool <file>` (or `python3`). Must parse clean. No
   Python on the machine: read the file back and confirm it is valid JSON
   before continuing.
5. Gitignore: if the target is a git repo, make sure its `.gitignore` covers
   `.claude/settings.local.json` (append the line if missing, on its own line,
   with a newline first when the file does not end in one; create `.gitignore`
   with that line if the repo has none). Not a git repo: skip and say so.
6. Verify: Claude Code usually picks the new file up live; the next message
   arrives stamped. If no stamp appears, start a new Claude Code session
   (reload the VS Code window, or quit and relaunch `claude` in a terminal)
   and check again.

## What To Print

Four shapes. Pick exactly one.

Path A, fresh install:

```
Time hook installed in <target>.
- Created .claude/settings.local.json (JSON validated)
- Added .claude/settings.local.json to .gitignore
Send any message; it should arrive stamped [Current time: ...]. No stamp: start a new Claude Code session.
```

Path B, merged into existing settings:

```
Time hook added to <target>'s existing .claude/settings.local.json.
- Existing keys and hooks untouched, JSON validated
- .gitignore covers the file
Send any message; it should arrive stamped [Current time: ...]. No stamp: start a new Claude Code session.
```

Path C, already installed:

```
<target> already has the time hook; nothing changed.
```

Path D, edit blocked by the permission system:

```
The permission system blocked me from editing hook config. Two options:
1. Switch off auto mode (Shift+Tab cycles the permission modes), tell me to continue, and approve my edit
2. Paste this yourself into <target>/.claude/settings.local.json:
<the full hook block>
Then add .claude/settings.local.json to the project's .gitignore.
```

## Resilience

- Existing settings.local.json fails to parse: stop, show the parse error, do
  not overwrite a broken file. You decide whether to fix or replace it
- Permission classifier blocks the write (it often blocks hook-config edits in
  auto mode; a fresh file usually passes, edits sometimes do not): fall back to
  Path D, never work around the block
- `date` not found (machine without Git Bash): swap the command for
  `python -c "from datetime import datetime; print(datetime.now().strftime('[Current time: %Y-%m-%d (%A) %H:%M]'))"`
  and drop the `"shell"` key; pipe-test that instead, and escape the inner
  double quotes when you write it into the JSON `command` value
- Target folder does not exist or has no project in it: stop and ask for the
  right path, do not create folders
- Re-run on a project that already has the hook: Path C, idempotent, never
  duplicate the entry
- Two stamps on every prompt: the hook also sits in `~/.claude/settings.json`
  or the project's `.claude/settings.json`, which Claude Code merges with this
  file. Remove one copy

## Installation

Place this folder at `<repo>/.claude/skills/pvc-timestamp-hook/` in any project
that should be able to install the hook, in itself or in another folder. Claude
Code picks the skill up in the running session; start a new session if it does
not show. Verify by asking "What skills are available?".