# UserPromptSubmit Hook

> **TL;DR.** The UserPromptSubmit hook is a [Claude Code](https://code.

- **Category:** AI / Developer Tools / Claude Code
- **Stage:** established
- **Age:** 335 days
- **Origin date:** 2025-07-16
- **First detected:** 2026-04-21
- **Canonical URL:** https://earlyterms.com/term/userpromptsubmit-hook
- **Sources:** 8 primary URLs

## Definition

The UserPromptSubmit hook is a [Claude Code](https://code.claude.com/docs/en/hooks) lifecycle event that fires the moment a user hits enter on a prompt, before Claude processes it. A shell command configured in `settings.json` receives the prompt text plus `cwd`, `session_id`, and transcript path on stdin, and can inject context, block the prompt, or rename the session on exit.

Anthropic shipped it in [Claude Code 1.0.54 on July 16, 2025](https://x.com/iannuttall/status/1945704745890451762), alongside the addition of `cwd` to every hook input. It has since become the default entry point for prompt-side automation in the Claude Code ecosystem — the community repo [disler/claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery) alone has 3.5k stars teaching patterns built around it.

## Example

A common community pattern: a UserPromptSubmit hook forks a background `claude -p --model haiku` call that reads the last few transcript turns and writes a 3-6 word title, so parallel Claude Code sessions get auto-generated tab names. Another variant looks up prompt keywords in a local docs index and injects matching context.

## Analogy

The doorman for every prompt — checks your coat, slips a note in your pocket, decides if you get in.

## Why it's emerging now

Nine months after shipping in Claude Code 1.0.54, UserPromptSubmit is the de-facto entry point for prompt-side automation — session auto-titling, doc-index context injection, "you're right" filters — and autocomplete is full of error queries that no tutorial has cleanly answered yet.

## Related terms

- *parent:* claude-code
- *related:* agents-md
- *related:* claude-agent-sdk
- *related:* context-engineering
- *related:* mcp-server
- *related:* agent-harness
- *related:* PreToolUse hook
- *related:* SessionStart hook
- *related:* Stop hook
- *related:* pre-commit
- *related:* prompt injection

## Sources

1. [Claude Code Hooks reference — UserPromptSubmit](https://code.claude.com/docs/en/hooks)
2. [Ian Nuttall — Claude Code 1.0.54 launch tweet (Jul 16, 2025)](https://x.com/iannuttall/status/1945704745890451762)
3. [disler/claude-code-hooks-mastery (3.5k stars)](https://github.com/disler/claude-code-hooks-mastery)
4. [DataCamp — Claude Code Hooks: A Practical Guide](https://www.datacamp.com/tutorial/claude-code-hooks)
5. [GitHub Issue #13912 — stdout error despite docs](https://github.com/anthropics/claude-code/issues/13912)
6. [GitHub Issue #27365 — updatedPrompt feature request](https://github.com/anthropics/claude-code/issues/27365)
7. [Lucian Wischik gist — 'You're right' filter hook](https://gist.github.com/ljw1004/34b58090c16ee6d5e6f13fce07463a31)
8. [Anthropic Agent SDK — hooks for agents](https://platform.claude.com/docs/en/agent-sdk/hooks)

---
_Generated by EarlyTerms · https://earlyterms.com/term/userpromptsubmit-hook_