Skip to content

fix(plugins): compile hook envs to bytecode and give SessionStart 45 s - #2109

Merged
phernandez merged 1 commit into
mainfrom
fix/2101-hook-bytecode
Nov 13, 2026
Merged

phernandez merged 1 commit into
mainfrom
fix/2101-hook-bytecode

Conversation

@phernandez

@phernandez phernandez commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Fixes #2101.

Problem

The Claude desktop app launches Claude Code with PYTHONDONTWRITEBYTECODE=1, and hook processes inherit it. Python never writes __pycache__, and uv does not compile at install by default, so the uv run --script hook environment has no .pyc files. Every SessionStart compiles about 2,200 modules from source. On the reporter's Windows laptop that took 21–26 s, over the 20 s timeout, and the session started without a brief.

Change

  • Each hook script (Claude Code and Codex, SessionStart and PreCompact) sets compile-bytecode = true in its PEP 723 [tool.uv] block, so uv compiles the environment when it installs it. Compiled files are read even when PYTHONDONTWRITEBYTECODE is set.
  • The Claude Code SessionStart timeout goes from 20 s to 45 s. The reporter's follow-up shows that compiled environments still reach 21–27 s under normal CPU load on that machine. Plugin users cannot override a plugin hook's timeout. The Codex SessionStart timeout is already 30 s and is unchanged.
  • scripts/validate_claude_plugin.py rejects a Claude Code hook script without the setting. The Codex package test checks for it too.

Existing hook environments that already satisfy their requirements are not recompiled. The fix reaches users on the next plugin update, which changes the plugin path and so the environment.

The other cost the reporter measured, SessionStart importing the full MCP tool stack to run a few searches, is the same family as #1731 and is not addressed here.

Verification

  • Built the real session_start.py environment with a fresh UV_CACHE_DIR and PYTHONDONTWRITEBYTECODE=1: 9,585 .pyc for 9,586 .py. A small test script under the same conditions produced 0 .pyc without the setting and compiled files with it.
  • just package-check and just fast-check pass.
  • New test_claude_validator_requires_hook_bytecode_compilation passes, and the validator fails when the line is removed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CMYVL1rjJwNnrvxniz1dDD

The Claude desktop app runs Claude Code with PYTHONDONTWRITEBYTECODE=1, so
the uv hook env never got .pyc files and every SessionStart compiled ~2,200
modules from source, past its 20 s timeout on slower machines. Set
compile-bytecode = true in each hook script's [tool.uv] block (Claude Code
and Codex), check it in the validator, and raise the Claude Code
SessionStart timeout to 45 s.

Fixes #2101

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CMYVL1rjJwNnrvxniz1dDD
Signed-off-by: phernandez <paul@basicmachines.co>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T21:14:20.117237Z 1a2743a PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@phernandez
phernandez merged commit e10f001 into main Nov 13, 2026
50 checks passed
@phernandez
phernandez deleted the fix/2101-hook-bytecode branch November 13, 2026 01:11
phernandez added a commit that referenced this pull request Nov 15, 2026
Follow-up to #2101 and #2109.

## Problem

#2109 makes the hook environment compile bytecode, but the reporter's
compiled SessionStart still took 14–18 s. Their profile showed `import
basic_memory.mcp.tools` at 9.3 s. The brief only runs a few filtered
searches, yet it loaded every tool, FastMCP's server and the MCP server.

Two things pulled that in:

- The brief called the `bm_search` tool.
- The HTTP helpers every typed client uses (`call_get`, `call_query`,
...) lived in `mcp/tools/utils.py`. Importing any of them ran
`tools/__init__.py`, which registers every tool. So even the plain
`SearchClient` loaded the whole tool stack.

## Change

- `mcp/tools/utils.py` moves to `mcp/api_calls.py`, outside the `tools`
package. Every reference uses the new path; there is no alias.
- The brief's search is now `_search_notes` in `cli/commands/hook.py`.
It resolves the project with `get_project_client` and sends the same
`SearchQuery` that `bm_search` sends for those arguments (note types,
frontmatter filters, `since`, note rows only), through `SearchClient`.
`_query` keeps the timeout and treats any failure as no data, as before.

## Results

On macOS with bytecode compiled, `bm hook session-start` against my real
config:

| | main | this branch |
|---|---|---|
| import time | 2.24 s | 1.75 s |
| `basic_memory.mcp.tools`, `basic_memory.mcp.server`, `fastmcp.server`
loaded | yes | no |
| brief output | | identical |

Without bytecode the import cost is several times larger, so the saving
on the reporter's machine should be several seconds. What still loads is
needed: the local API app (~380 ms, local projects only), the database
layer, and `fastmcp.exceptions` (~275 ms), because the helpers raise
`ToolError`.

## Tests

- `test_brief_search_matches_bm_search_for_the_same_filters`: on a real
project, the brief's search and `bm_search` return the same notes for
the same filters.
- `test_brief_search_reads_an_unknown_project_as_no_data`
- `test_session_start_never_imports_the_mcp_tool_stack`: runs the
brief's search in a subprocess with a temporary home and asserts the
tool stack and MCP server never load. It fails on main's hook code.
- `just fast-check` passes. `just fast-test`: 1242 passed.
- Existing hook tests that patched `basic_memory.mcp.tools.bm_search`
now patch `hook._search_notes`, which takes the same keyword arguments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01CMYVL1rjJwNnrvxniz1dDD

Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant