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

> Discover how free-claude-code's optimization handlers mock specific request types by intercepting API calls and returning fabricated responses, enhancing your development workflow.

- Repository: [Ali Khokhar/free-claude-code](https://github.com/Alishahryar1/free-claude-code)
- Tags: how-to-guide
- Published: 2026-04-24

---

**Optimization handlers in free-claude-code intercept API requests before they reach the LLM provider by detecting specific patterns in [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py) and returning fabricated `MessagesResponse` objects when feature flags in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py)

The optimization system centers on `OPTIMIZATION_HANDLERS`, a prioritized list defined at module level in [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) [(source)](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py):

```python

# 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:

```python
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`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py)

Each optimization handler delegates pattern recognition to [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/optimization_handlers.py), with each function following a consistent pattern: check settings, detect pattern, build `MessagesResponse`, return mock.

## Configuration Flags in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py)

All optimization toggles reside in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) (lines 57-65) as boolean fields with sensible defaults:

```python
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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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

```python
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

```python
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

```python
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

```python
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`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) form a sequential pipeline that intercepts API requests before they reach LLM providers.
- **Pattern detection** occurs in [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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.