Skip to content

[BUG] Claude Code plugin hooks never get bytecode under the Claude desktop app, so SessionStart compiles ~2,200 modules each run and exceeds its 20 s timeout #2101

Closed

Description

@Jonny-boy9000

Bug Description

The Claude Code plugin's hooks run in a uv run --script environment that never gets Python bytecode. The Claude desktop app (Code tab) launches Claude Code with PYTHONDONTWRITEBYTECODE=1. Hook processes inherit it, so Python never writes __pycache__. uv doesn't compile at install by default, so nothing else does either.

The result: every SessionStart compiles the whole import graph (~2,200 modules: FastAPI, FastMCP, the basic_memory.mcp.tools stack) from source. On a slower Windows machine the hook takes 21–26 s warm. That's over the 20 s timeout in plugins/claude-code/hooks/hooks.json, so the session silently gets no brief. The lifecycle envelope is still written, because capture runs before the brief.

Related but different from #886: that one was about eager embedding imports. Here the embedding stack isn't involved. The cost is plain source compilation plus import of the tool stack.

Steps To Reproduce

  1. Install basic-memory 1.0.0 (uv tool install basic-memory==1.0.0) and the plugin (basic-memory install claude-code --yes). The plugin is 1.0.0, from main @ 370ae9d.
  2. Open sessions from the Claude desktop app's Code tab, so SessionStart runs a few times.
  3. Look at the hook env: %LOCALAPPDATA%\uv\cache\environments-v2\session-start-<hash>\Lib\site-packages.
  4. Time the hook by hand: echo {"session_id":"x","hook_event_name":"SessionStart","source":"startup","cwd":"..."} | uv run --quiet --script <plugin>/hooks/session_start.py, with PYTHONDONTWRITEBYTECODE=1 set as the desktop app sets it.

Expected Behavior

After the first run, SessionStart is warm and finishes well inside its 20 s timeout.

Actual Behavior

  • The hook env holds 0 .pyc files against 10,081 .py, after several desktop-launched sessions. A uv tool install --compile-bytecode of the same version has 10,111 .pyc.

  • PYTHONDONTWRITEBYTECODE=1 is in the Claude Code environment. The desktop app's bundle sets PYTHONDONTWRITEBYTECODE:"1" in the env it passes to Claude Code, with the note "pycache folders appear where tools run Python".

  • Warm timings (same machine, same config, interleaved runs):

    Env Run 1 Run 2 Run 3 Average
    hook env as built by the plugin (no .pyc) 23.5 s 25.8 s 21.1 s 23.5 s
    identical script, env built with UV_COMPILE_BYTECODE=1 18.1 s 15.4 s 14.0 s 15.8 s (−33%)

    The brief output was identical between the two.

  • cProfile of the no-.pyc run (26.3 s under the profiler):

    • import machinery: 21.3 s cumulative;
    • builtins.compile: 6.1 s over 6,797 calls (2,164 modules compiled from source);
    • basic_memory.mcp.tools import: 9.3 s;
    • basic_memory.cli.main import: 5.2 s;
    • the actual bm_search calls: ~1.5 s.
  • uv's own overhead is ~0.4 s. All requirements satisfied means it reuses the env without resolving.

Environment

  • OS: Windows 11 Pro (build 26300), Intel i5-8250U (4C/8T, 2017 laptop CPU). On-access antivirus is active, which makes per-file stat/open slow (~0.3 ms each). That magnifies the problem, but the bytecode gap is the same on any machine.
  • Python: 3.13.17 (hook env base). uv 0.13.7.
  • Basic Memory: 1.0.0 (uv tool), plugin basic-memory@basicmachines-co 1.0.0.
  • Claude desktop app 5.1231.2.0, Claude Code 2.1.321 (Code tab).

Possible Solution

Have uv compile bytecode when it builds the hook env. Both options below were tested with uv 0.13.7; each produced .pyc where the control env got none.

  1. In each hook script's inline metadata (hooks/session_start.py, hooks/pre_compact.py):
    # [tool.uv]
    # compile-bytecode = true
    # override-dependencies = ["fastmcp==4.1.3"]
  2. Or add the flag to the commands in hooks/hooks.json: uv run --quiet --compile-bytecode --script ....

Note: uv doesn't compile an env that already satisfies its requirements. But a plugin release changes ${CLAUDE_PLUGIN_ROOT}, and with it the env path, so the fix takes effect for everyone on the next plugin update.

Lower priority:

  • The SessionStart path imports the full basic_memory.mcp.tools stack, which builds the FastAPI app, to run four filter-only searches. A lighter import path would cut the remaining ~13 s further.
  • A timed-out brief is invisible to the user. A one-line stderr note, or a marker the next bm-status can report, would make this easier to spot.

Activity

  1. Jonny-boy9000 commented on Nov 12, 2026

    @Jonny-boy9000
    Author

    Follow-up with data after applying the bytecode workaround locally. Bytecode helps, but 20 s is still too tight on slower machines, and users have no way to raise it.

    After rebuilding both hook envs with bytecode (same machine as above: i5-8250U, on-access antivirus):

    Condition SessionStart (warm, real hook path)
    Quiet machine (CPU 0–7%) 12.4 / 12.6 / 12.4 s
    Normal working load (CPU ~30%) 13.4 / 16.6 / 21.1 / 26.8 s

    So even with .pyc in place, a busy moment still pushes the brief past the 20 s timeout. The session then silently starts without it. The time is the same whichever project is mapped as primaryProject; it's import cost, not query cost.

    Why this needs a plugin-side change: Claude Code has no user setting to override the timeout of a hook that a plugin defines (the hooks docs only allow adding separate handlers). The only local fix is editing hooks/hooks.json in the plugin cache, and the next plugin update reverts it.

    Request (any one of these would do):

    1. Raise the SessionStart timeout in plugins/claude-code/hooks/hooks.json to 30 s or more. SessionStart runs in the background for startup/resume, so a longer ceiling only matters on slow runs.
    2. Or make the SessionStart path cheaper to import (it currently loads the full basic_memory.mcp.tools / FastAPI stack to run filter-only searches). That would fix it at the root.
    3. Or, at least, leave a marker when the brief was cut off (for example, something bm-status can report), so a missing brief isn't invisible.

    Environment unchanged from the original report: Basic Memory 1.0.0, plugin 1.0.0, uv 0.13.7, Python 3.13, Windows 11, Claude Code under the Claude desktop app.

  2. phernandez commented on Nov 13, 2026

    @phernandez
    Member

    @Jonny-boy9000 thanks for the detailed report and measurements. We filed the root cause upstream as anthropics/claude-code#109426: the desktop app could set PYTHONPYCACHEPREFIX instead of disabling bytecode, which keeps __pycache__ out of projects and still lets hooks cache.

    We are not waiting on that. #2109 sets compile-bytecode = true in the hook scripts, so uv compiles the hook environment when it builds it, and Python reads those files even with PYTHONDONTWRITEBYTECODE=1. It also raises the SessionStart timeout to 45 s. It reaches you on the next plugin update, which builds a fresh environment.

    The remaining import cost you profiled (the MCP tool stack loading for a few searches) is a separate change we are working on now.

  3. added a commit that references this issue on Nov 13, 2026
    e10f001
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions