Module claude_md_integration 

Claude Code CLAUDE.md prompt-level guidance installer.

The PreToolUse hook (.claude/settings.local.json) only intercepts Bash-tool commands. Claude Code’s built-in Read/Grep/Glob tools bypass shell hooks entirely — confirmed in github.com/anthropics/claude-code/issues/4544. That means a heavy session (file reads, searches, directory listings) can pass through Claude Code without sqz ever seeing a single byte.

Reported in issue #12 by @JCKodel:

Running claude on a long session don’t show anything in the dashboard […] In practice, both Cursor and claude cli shows 0.

This module installs prompt-level guidance into the project’s CLAUDE.md file. Claude Code reads CLAUDE.md at session start, so the agent sees the instructions on every turn.

The guidance block:

• recommends sqz_read_file / sqz_grep / sqz_list_dir MCP tools (registered via sqz init’s MCP config merge) for any file I/O larger than ~2KB or that might be repeated;
• keeps the built-in Read available for tiny configs and byte-exact needs (lockfiles, signatures);
• documents the §ref:HASH§ escape hatch so the agent doesn’t thrash on a token it can’t parse.

Same install/uninstall semantics as codex_integration::install_agents_md_guidance:

• If CLAUDE.md doesn’t exist → create it with sqz’s block.
• If it exists without the sqz block → append with a blank-line separator.
• If it exists with an outdated sqz block → replace the block in place; with the current one → no-op (idempotent).

The block is wrapped in HTML comment sentinels so uninstall can excise it byte-exact.

Functions

claude_mcp_config_managed

Whether ~/.claude.json holds the mcpServers.sqz entry sqz installed.

claude_md_block_outdated

Whether sqz init would replace the sqz block in CLAUDE.md for sqz_path.

claude_md_guidance_block

Build the markdown block that sqz appends to CLAUDE.md.

claude_md_guidance_state

Compare the CLAUDE.md block against what this version writes for the same binary.

claude_md_has_guidance

Whether the project’s CLAUDE.md holds a sqz block uninstall can remove.

claude_md_path

Compute the path where CLAUDE.md lives for the given project.

claude_user_json_path

Compute the path of the user-level ~/.claude.json config.

install_claude_mcp_config

Register sqz-mcp as an MCP server in ~/.claude.json.

install_claude_md_guidance

Install sqz’s guidance block into CLAUDE.md at project_dir.

refresh_claude_md_guidance

Rewrite a stale CLAUDE.md block in place, keeping its sqz binary while that resolves.

remove_claude_mcp_config

Remove sqz’s mcpServers.sqz entry from ~/.claude.json if we installed it (detected by the _sqz_managed sentinel). Leaves user-customised entries alone.

remove_claude_md_guidance

Remove sqz’s guidance block from CLAUDE.md if present.