Rlm

🚀 RLM Hooks

RLM Hooks is a set of tools designed to intercept Read tool calls and suggest using RLM tools when files exceed configurable thresholds, helping users avoid hitting token limits when working with large files.

✨ Features

• Threshold-based Suggestion: Intercepts Read tool calls and suggests RLM tools when files exceed either size or token thresholds.
• Configurable Thresholds: Allows users to customize size and token thresholds via environment variables.
• Non-blocking: Suggests RLM tools without blocking the read operation.
• JSON Output: Provides JSON output with decision: "approve" and an optional reason message.

📦 Installation

There is no specific installation process described in the original document. If you need to use these hooks, you can follow the configuration steps in the "Configuration" section.

💻 Usage Examples

Basic Usage

The Large File Suggester Hook is implemented in the check-file-size.sh script. It is configured in the .claude/settings.json file as follows:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/check-file-size.sh"
          }
        ]
      }
    ]
  }
}

Advanced Usage

Manual Testing

1. Create a large test file (>25KB):

python3 -c "print('x' * 150000)" > /tmp/large_file.txt

2. Test the hook directly:

# Test with large file (should show suggestion)
echo '{"tool_input": {"file_path": "/tmp/large_file.txt"}}' | .claude/hooks/check-file-size.sh

# Expected output:
# {
#   "decision": "approve",
#   "reason": "This file is 146.48 KB ..."
# }

3. Test with small file (should NOT show suggestion):

echo '{"tool_input": {"file_path": "/Users/richard/projects/fun/rlm/README.md"}}' | .claude/hooks/check-file-size.sh

# Expected output:
# {"decision": "approve"}

4. Test edge cases:

# Non-existent file
echo '{"tool_input": {"file_path": "/nonexistent.txt"}}' | .claude/hooks/check-file-size.sh
# Output: {"decision": "approve"}

# No file_path
echo '{"tool_input": {}}' | .claude/hooks/check-file-size.sh
# Output: {"decision": "approve"}

Customizing Thresholds

Size threshold (RLM_SIZE_THRESHOLD in bytes):

# Use 50KB size threshold
RLM_SIZE_THRESHOLD=51200 echo '{"tool_input": {"file_path": "somefile.txt"}}' | .claude/hooks/check-file-size.sh

# Use 1MB size threshold
RLM_SIZE_THRESHOLD=1048576 echo '{"tool_input": {"file_path": "somefile.txt"}}' | .claude/hooks/check-file-size.sh

Token threshold (RLM_TOKEN_THRESHOLD in tokens):

# Use 5K token threshold (more aggressive, catches smaller files)
RLM_TOKEN_THRESHOLD=5000 echo '{"tool_input": {"file_path": "somefile.txt"}}' | .claude/hooks/check-file-size.sh

# Use 20K token threshold (closer to hard limit)
RLM_TOKEN_THRESHOLD=20000 echo '{"tool_input": {"file_path": "somefile.txt"}}' | .claude/hooks/check-file-size.sh

Both thresholds together:

# Custom size (100KB) and token (15K) thresholds
RLM_SIZE_THRESHOLD=102400 RLM_TOKEN_THRESHOLD=15000 .claude/hooks/check-file-size.sh

Integration Testing with Claude Code

1. Start Claude Code in the RLM project directory.
2. Ask Claude to read a large file (>25KB).
3. Observe the suggestion message before the file is read.
4. The read will still proceed (not blocked).

📚 Documentation

Behavior

The hook triggers when EITHER threshold is exceeded:

• Size threshold: 25KB (configurable via RLM_SIZE_THRESHOLD env var).
• Token threshold: 10K tokens (configurable via RLM_TOKEN_THRESHOLD env var).

Token estimation uses ~4 characters per token (conservative estimate). The 10K token threshold warns early because Claude's Read tool hard-fails at 25K tokens.

The hook suggests RLM tools but does NOT block the read. It outputs JSON with decision: "approve" and an optional reason message.

File Structure

.claude/
  hooks/
    check-file-size.sh     # Hook script
    rlm-suggest.json       # Hook metadata (optional, for documentation)
    README.md              # This file
  settings.json            # Hook configuration

Suggested RLM Workflow

When the hook fires, it suggests the following RLM functions:

1. rlm_load_context(name, content) - Load as external variable.
2. rlm_inspect_context(name) - Get structure without full content.
3. rlm_chunk_context(name, 'paragraphs') - Split strategically.
4. rlm_sub_query_batch(query, name, indices) - Process in parallel.

This pattern prevents context bloat and enables processing files that exceed token limits.