Prevent context drift

[MischaPanch]

Problem

When using Claude Code with Serena, the agent tends to drift towards using generic tools (Grep, Read, Bash) for code exploration instead of Serena's semantic tools (find_symbol, get_symbols_overview, search_for_pattern, etc.). This happens gradually as the conversation context grows and the initial instructions lose influence.

Proposal

Use Claude Code's hooks system to automatically remind the agent to use Serena's tools when it hasn't done so recently. The mechanism is session-scoped and zero-cost when the agent is behaving "correctly".

How It Works

Three hooks work together:

1. Post Serena tool use: writes the current timestamp to a session-scoped file
2. Post Grep/Read/Bash/Agent use: checks the timestamp — if >60 seconds since the last Serena call, injects a reminder into the agent's context
3. Session end: cleans up the timestamp file

The reminder only appears when:

• Serena has been used in the current session (the timestamp file exists)
• The agent hasn't used a Serena tool in the last 60 seconds
• The agent is using Grep, Read, or Bash (which are often substitutes for Serena's tools)

Serena CLI Extension

Extend the Serena CLI with a hook subcommand group for Claude Code hook integration:

serena hook stamp     # Write current timestamp to ~/.serena/reminder_serena_tools_<session_id>
serena hook check     # Print reminder if timestamp is older than 60s
serena hook cleanup   # Delete the timestamp file

Claude Code pipes a JSON object to stdin when invoking hook commands. This object contains a session_id field (among others) that uniquely identifies the current session. The CLI commands parse this to scope the timestamp file per session (~/.serena/reminder_serena_tools_<session_id>).

import json, sys

data = json.load(sys.stdin)
session_id = data["session_id"]

Hook Configuration (.claude/settings.json)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__serena__.*",
        "hooks": [
          {
            "type": "command",
            "command": "uvx serena hook stamp"
          }
        ]
      },
      {
        "matcher": "Grep|Read|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "uvx serena hook check"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "uvx serena hook cleanup"
          }
        ]
      }
    ]
  }
}

Properties

• Cross-platform: distributed with Serena, invoked via uvx
• Session-scoped: timestamp file includes session ID, no cross-session interference
• Zero-cost when behaving: the check command runs but prints nothing, so no tokens are wasted
• Self-activating: only fires when Serena is actually in use (timestamp file must exist)
• Clean: timestamp file is deleted on session end
• Documentation: extend Serena's docs with a section on recommended Claude Code hooks and how to configure them
• Optional: a serena setup claude-code command that automatically writes the hooks config to .claude/settings.json. We could do the same for other agents.

[MischaPanch]

Extension: we should also use the agent hook to solve issues of subagents not being instructed on tools. We can consider switching the logic, not being timebased but instead incrementing a counter on each grep/read/find invocation, setting the counter to zero on serena tool calls, and sending the reminder when the counter is at some number (say three). Timestamps are a bit clumsy.

We can also consider not using the filesystem but instead run another tiny service with serena (or extend the dashboard service, then we'd need sure that it always runs) to manage the counts, letting the hook commands connect to that. Though finding the service may be annoying, while on the filesystem we can easily use the session_id. With the service, ideally it'd run at most once, no matter how many serena sessions.

If we go down that path, we should look into to which extent the reminder mechanism can be implemented for other clients as well.

@opcode81 @Asher- FYI

[MischaPanch]

This is still not saying that we definitely should go down this road, just an exploration of what it would entail if we did

[MischaPanch]

Solved via serena-hooks