UserPromptSubmit hook

The problem

By default, Claude Code is free to choose its own tools. It might read a file directly even when an MCP call would be cheaper and more accurate. We want to nudge it to prefer MCP.

The fix: a UserPromptSubmit hook

Claude Code supports hooks that fire on certain events. The UserPromptSubmit hook runs before your prompt reaches Claude, and whatever it outputs gets injected as a system reminder into the context.

That means we can inject the instruction "use MCP tools first" on every prompt. Claude can't forget it.

What init creates

If you selected Claude Code during larkx init, this is already in .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'IMPORTANT: For any code navigation in this project, always use larkx MCP tools first (search_symbol, get_file_summary, get_project_index, get_impact, get_call_chain, get_dead_code). Only fall back to Read/Grep if MCP returns no result.'",
            "shell": "bash"
          }
        ]
      }
    ]
  }
}

Verifying the hook

Open a fresh Claude Code chat and ask:

"Where is the indexProject function?"

Claude should immediately call search_symbol without first opening files. You can see the hook fire in the transcript as a UserPromptSubmit hook success message before your turn starts.

Disabling the hook temporarily

# Comment out or remove the hooks block from .claude/settings.json
# Restart Claude Code

Other Claude hook events

See the Claude Code hooks documentation for the full list of events you can hook (PreToolUse, PostToolUse, Stop, etc.). The same pattern works to enforce any policy on Claude.

Next: CLI Reference