How Optimization Handlers in free-claude-code Mock Specific Request Types

Optimization handlers in free-claude-code intercept API requests before they reach the LLM provider by detecting specific patterns in api/detection.py and returning fabricated MessagesResponse objects when feature flags in config/settings.py are enabled.

The free-claude-code repository implements a fast-path optimization system that eliminates unnecessary external API calls for common housekeeping and UI-driven requests. By analyzing incoming request payloads against predefined heuristics, the application can return instantaneous mock responses for specific request types, dramatically reducing latency and conserving API quota.

The Handler Pipeline in api/optimization_handlers.py

The optimization system centers on OPTIMIZATION_HANDLERS, a prioritized list defined at module level in api/optimization_handlers.py (source):

# api/optimization_handlers.py

OPTIMIZATION_HANDLERS = [
    try_quota_mock,
    try_prefix_detection,
    try_title_skip,
    try_suggestion_skip,
    try_filepath_mock,
]

The try_optimizations() function orchestrates execution by iterating through this list and returning the first non-None response. As implemented in lines 39-47:

def try_optimizations(request_data, settings):
    for handler in OPTIMIZATION_HANDLERS:
        result = handler(request_data, settings)
        if result is not None:
            return result
    return None

This short-circuit evaluation ensures that only the first matching handler executes, preventing redundant processing and maintaining deterministic behavior.

Detection Heuristics in api/detection.py

Each optimization handler delegates pattern recognition to api/detection.py, which exposes specialized functions to identify request intents without invoking the LLM:

• is_quota_check_request (lines 12-26): Detects quota probes by checking for max_tokens == 1 combined with the word "quota" in the message content.
• is_title_generation_request (lines 29-38): Identifies title generation requests when the system prompt contains "new conversation topic" and "title" with no tools enabled.
• is_prefix_detection_request (lines 41-62): Recognizes prefix extraction requests via <policy_spec> tags and Command: blocks in single user messages.
• is_suggestion_mode_request (lines 65-76): Flags suggestion mode when any user message contains the literal string [SUGGESTION MODE:.
• is_filepath_extraction_request (lines 79-131): Detects file-path extraction requests through the presence of Command:, Output: sections, and file-path hints in user messages.

These detection functions return boolean values that determine whether a handler should construct a mock response.

Individual Optimization Handlers and Their Mocks

Each handler in the pipeline corresponds to a specific request type and produces a tailored MessagesResponse containing minimal but valid metadata (id, model, role, content, stop_reason, and realistic usage statistics).

try_quota_mock

• Setting flag: enable_network_probe_mock (default True)
• Detection: Calls is_quota_check_request
• Mock behavior: Returns a MessagesResponse with text content "Quota check passed."
• Purpose: Replaces the network probe that merely verifies API quota availability

try_prefix_detection

• Setting flag: fast_prefix_detection (default True)
• Detection: Calls is_prefix_detection_request
• Mock behavior: Extracts the command prefix using extract_command_prefix from command_utils and returns it as the response text
• Purpose: Skips a full LLM call used only to strip shell-command prefixes from policy-wrapped inputs

try_title_skip

• Setting flag: enable_title_generation_skip (default True)
• Detection: Calls is_title_generation_request
• Mock behavior: Returns the static title "Conversation"
• Purpose: Bypasses the model call that generates conversational titles for UI display

try_suggestion_skip

• Setting flag: enable_suggestion_mode_skip (default True)
• Detection: Calls is_suggestion_mode_request
• Mock behavior: Returns an empty text payload (indicating suggestion mode disabled)
• Purpose: Avoids LLM requests that would produce auto-suggestions

try_filepath_mock

• Setting flag: enable_filepath_extraction_mock (default True)
• Detection: Calls is_filepath_extraction_request
• Mock behavior: Returns file paths extracted by extract_filepaths_from_command as newline-delimited text
• Purpose: Replaces potentially heavy LLM runs that parse command output for file listings

The implementation of these handlers spans lines 25-136 in optimization_handlers.py, with each function following a consistent pattern: check settings, detect pattern, build MessagesResponse, return mock.

Configuration Flags in config/settings.py

All optimization toggles reside in config/settings.py (lines 57-65) as boolean fields with sensible defaults:

enable_network_probe_mock: bool = True
fast_prefix_detection: bool = True
enable_title_generation_skip: bool = True
enable_suggestion_mode_skip: bool = True
enable_filepath_extraction_mock: bool = True

These settings can be disabled via environment variables (e.g., FAST_PREFIX_DETECTION=0) to force real LLM processing for debugging or specific use cases.

Request Flow and Execution Order

The optimization pipeline executes early in the request lifecycle, before any provider delegation occurs:

1. An incoming HTTP request parses into a MessagesRequest object (Anthropic-style schema defined in api/models/anthropic.py)
2. try_optimizations(request, settings) invokes the handler chain
3. If any handler returns a MessagesResponse, the server returns it immediately
4. If all handlers return None, normal provider logic processes the request

This architecture ensures instantaneous responses for housekeeping or UI-only calls while maintaining compatibility with legitimate LLM workloads.

Practical Examples: Triggering Each Mock

Triggering the Quota Probe Mock

from api.models.anthropic import MessagesRequest, Message
from api.optimization_handlers import try_optimizations
from config.settings import get_settings

req = MessagesRequest(
    model="any-model",
    max_tokens=1,
    messages=[Message(role="user", content="quota?")],
)

resp = try_optimizations(req, get_settings())
print(resp.content[0]["text"])  # Output: "Quota check passed."

Fast Prefix Detection

req = MessagesRequest(
    model="any-model",
    max_tokens=256,
    messages=[
        Message(
            role="user",
            content="""
<policy_spec>
...
Command: git commit -m "Add feature"
"""
        )
    ],
)

resp = try_optimizations(req, get_settings())
print(resp.content[0]["text"])  # Output: "git commit"

Skipping Title Generation

req = MessagesRequest(
    model="any-model",
    system="""
You are a helpful assistant. New conversation topic: generate a title.
""",
    messages=[Message(role="user", content="Hello!")]
)

resp = try_optimizations(req, get_settings())
print(resp.content[0]["text"])  # Output: "Conversation"

Mocking File-Path Extraction

req = MessagesRequest(
    model="any-model",
    messages=[
        Message(
            role="user",
            content="""
Command: ls -R /
Output:
<filepaths>
/etc/passwd
/home/user/.bashrc
</filepaths>
"""
        )
    ],
)

resp = try_optimizations(req, get_settings())
print(resp.content[0]["text"])

# Output:

# /etc/passwd

# /home/user/.bashrc

Summary

• Optimization handlers in api/optimization_handlers.py form a sequential pipeline that intercepts API requests before they reach LLM providers.
• Pattern detection occurs in api/detection.py via specialized heuristics that identify quota checks, title generation, prefix extraction, suggestion modes, and file-path requests.
• Mock responses are fabricated as MessagesResponse objects containing realistic metadata but static or extracted content, eliminating external API latency.
• Feature flags in config/settings.py (lines 57-65) control each handler independently, allowing selective disabling via environment variables.
• Execution order follows the OPTIMIZATION_HANDLERS list, returning the first matching mock to optimize response time for predictable request types.

Frequently Asked Questions

How do I disable a specific optimization handler?

Set the corresponding environment variable to 0 or False before starting the application. For example, to disable prefix detection, set FAST_PREFIX_DETECTION=0. The settings loader in config/settings.py reads these values to populate boolean flags that handlers check before executing.

What happens if multiple handlers match a single request?

The try_optimizations() function iterates through OPTIMIZATION_HANDLERS in the order defined (quota, prefix, title, suggestion, filepath) and returns the first non-None response. Subsequent handlers do not execute, ensuring only one mock response applies per request.

Are the mock responses compatible with the Anthropic Messages API format?

Yes. Every handler constructs a MessagesResponse object defined in api/models/anthropic.py containing standard fields: id, model, role, content, stop_reason, and usage statistics. These objects match the Anthropic API schema, allowing downstream components to process mocks identically to real LLM responses.

How does the quota check detection differentiate from legitimate single-token requests?

The is_quota_check_request function in api/detection.py (lines 12-26) requires both max_tokens == 1 and the presence of the word "quota" in the message content. This dual requirement minimizes false positives while reliably identifying the specific network probe pattern used to verify API availability.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}