anthropics / anthropics/claude-cookbooks

[PROPOSAL] Grounding Claude Code with always-fresh state via UserPromptSubmit hooks

Ouverte
#637 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
Jupyter Notebook
Étoiles
52.7k
Forks
6.3k
Merge moyen
25 min
PR mergées (30 j)
6

Description

### Preflight Checklist
- [x] I have searched existing cookbooks and this topic isn't already covered
- [x] This proposal focuses on Claude API/SDK capabilities (not external frameworks)
- [x] I am prepared to implement this cookbook (or have a clear implementation plan)

### Problem Statement

Claude (like any LLM) has no built-in sense of *now*. The system prompt usually carries a static date string, model outputs drift toward the training cutoff, and any time-sensitive task — scheduling, deadlines, log timestamps, "is this still active" — silently goes wrong. The same drift exists for other "current state" the model assumes but doesn't actually observe: current git branch, current working directory, current logged-in user, current feature-flag state.

Claude Code's [`UserPromptSubmit`](https://docs.anthropic.com/en/docs/claude-code/hooks) hook event is the right mechanism to fix this — but it's under-documented and most users don't realise it can inject arbitrary structured context into every turn. A cookbook recipe would make the pattern legible and reusable.

### Claude Capabilities Demonstrated

- **Claude Code hooks** — `UserPromptSubmit` for per-turn context injection (the primary feature)
- **Skills** — a companion `/time-keep` (or equivalent) skill so the model can also pull the value on demand
- **Trust hierarchy** — the recipe shows how to write hook-injected blocks the model should trust *over* its own assumptions ("Trust this over any earlier 'current date' the assistant or context may state")

### Differentiation

The existing skills notebooks teach *what skills are*. This recipe teaches a complementary pattern: when you need state to be present *automatically* on every turn (not invoked when the model decides to), hooks are the right tool. Current time is the obvious worked example; the recipe generalises to git branch, env vars, feature flags, or any "ground truth" the model would otherwise hallucinate.

### Notebook outline (~4 cells)

1. **The drift problem** — concrete example of Claude confidently picking the wrong date because the only "current date" in context is a stale system-prompt string.
2. **Minimal hook** — ~30 lines of bash registered as a `UserPromptSubmit` hook in `~/.claude/settings.json`, injecting a structured `` block.
3. **Generalising the pattern** — same hook shape but injecting `` (current branch + dirty status) and `` (env-var snapshot), so the model can reference these without asking.
4. **Companion skill for on-demand pulls** — when the model wants the value mid-turn rather than at prompt-submit time.

### Additional Context

Reference implementation already exists publicly: [JonoGitty/ai-time-keep](https://github.com/JonoGitty/ai-time-keep) (MIT, ~50 lines of bash, installer + uninstaller, also has a Codex `AGENTS.md` snippet). I'd write the notebook against the simpler hook script directly rather than asking readers to install the repo, so the recipe stands alone.

### Questions for maintainers

1. Does this fit under `skills/` (since it pairs hook + skill) or somewhere else (`misc/`, `claude-code/`)?
2. Should the recipe stay narrow on time as the worked example, or include the git-state / feature-flag generalisation?
3. Any preference on bash vs Python for the hook itself? Bash is what's in the wild and what Claude Code's hook docs use, but Python would be more portable for the cookbook audience.

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.