Repository navigation
Description
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
- 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, frommain@ 370ae9d. - Open sessions from the Claude desktop app's Code tab, so SessionStart runs a few times.
- Look at the hook env:
%LOCALAPPDATA%\uv\cache\environments-v2\session-start-<hash>\Lib\site-packages. - 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, withPYTHONDONTWRITEBYTECODE=1set 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
.pycfiles against 10,081.py, after several desktop-launched sessions. Auv tool install --compile-bytecodeof the same version has 10,111.pyc. -
PYTHONDONTWRITEBYTECODE=1is in the Claude Code environment. The desktop app's bundle setsPYTHONDONTWRITEBYTECODE:"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=118.1 s 15.4 s 14.0 s 15.8 s (−33%) The brief output was identical between the two.
-
cProfile of the no-
.pycrun (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.toolsimport: 9.3 s;basic_memory.cli.mainimport: 5.2 s;- the actual
bm_searchcalls: ~1.5 s.
-
uv's own overhead is ~0.4 s.
All requirements satisfiedmeans 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-co1.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.
- 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"]
- 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.toolsstack, 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-statuscan report, would make this easier to spot.
Activity
Jonny-boy9000 commentedon Nov 12, 2026
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):
So even with
.pycin 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 asprimaryProject; it's import cost, not query cost.Why this needs a plugin-side change: Claude Code has no user setting to override the
timeoutof a hook that a plugin defines (the hooks docs only allow adding separate handlers). The only local fix is editinghooks/hooks.jsonin the plugin cache, and the next plugin update reverts it.Request (any one of these would do):
timeoutinplugins/claude-code/hooks/hooks.jsonto 30 s or more. SessionStart runs in the background for startup/resume, so a longer ceiling only matters on slow runs.basic_memory.mcp.tools/ FastAPI stack to run filter-only searches). That would fix it at the root.bm-statuscan 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.
phernandez commentedon Nov 13, 2026
@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
PYTHONPYCACHEPREFIXinstead of disabling bytecode, which keeps__pycache__out of projects and still lets hooks cache.We are not waiting on that. #2109 sets
compile-bytecode = truein the hook scripts, so uv compiles the hook environment when it builds it, and Python reads those files even withPYTHONDONTWRITEBYTECODE=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.
fix(plugins): compile hook envs to bytecode and give SessionStart 45 s (
perf(cli): keep the MCP tool stack out of the SessionStart brief (#2113)