# Free-Claude-Code Request Optimization: How It Intercepts Trivial API Calls Locally

> Discover how free-claude-code optimizes requests by intercepting trivial API calls locally, fabricating responses for common queries to cut latency and costs.

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

---

**Free-Claude-Code implements a fast-path optimization layer that inspects incoming `MessagesRequest` payloads locally before they reach external providers, returning fabricated responses for repetitive queries like quota checks and command prefixes to eliminate network latency and API costs.**

Free-Claude-Code is an open-source proxy that mimics the Anthropic API while adding intelligent shortcuts to reduce operational overhead. Its **request optimization** system acts as a gatekeeper on the `/v1/messages` endpoint, evaluating each payload against a series of pattern detectors before allowing network access to upstream providers like OpenRouter or NVIDIA NIM.

## The Optimization Pipeline Architecture

### Entry Point at the API Route

The interception begins at the edge of the application. In [`api/routes.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/routes.py) (lines 83‑86), the message route calls `try_optimizations(request_data, settings)` immediately after basic request validation. If this function returns a `MessagesResponse`, the route returns that response immediately, bypassing any external API call entirely.

### The Handler Dispatch Loop

The orchestration logic resides in [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py). Here, the `OPTIMIZATION_HANDLERS` list (lines 29‑36) defines an ordered pipeline of checker functions arranged from cheapest to most expensive. The dispatcher iterates through this list and returns the first non-`None` result, ensuring minimal CPU overhead for simple pattern matches.

## Local Interception Strategies

Each optimization handler follows a consistent three-step pattern: verify its settings flag is enabled, run a detection function against the request content, and return a locally fabricated `MessagesResponse` if matched. The following handlers implement the core **request optimization** logic:

### Quota Check Mocking

The `try_quota_mock` handler intercepts token-balance inquiries detected by `is_quota_check_request`. When `enable_network_probe_mock` is active in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py), this handler returns a minimal response with the text *"Quota check passed."* without querying the provider. Source: [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) (lines 46‑63).

### Prefix Detection

For local command shortcuts, `try_prefix_detection` catches requests beginning with known prefixes (e.g., `/reset`) using `is_prefix_detection_request`. With `fast_prefix_detection` enabled, it extracts the command via [`api/command_utils.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/command_utils.py) and returns it as plain text, eliminating the need for LLM parsing. Source: [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) (lines 25‑44).

### Title Generation Shortcuts

The `try_title_skip` handler recognizes Claude-specific title generation requests via `is_title_generation_request`. When `enable_title_generation_skip` is true, it returns the fixed string *"Conversation"* instead of consuming tokens on a creative generation task. Source: [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) (lines 66‑84).

### Suggestion Mode Bypass

`try_suggestion_skip` handles auto-complete style queries identified by `is_suggestion_mode_request`. If `enable_suggestion_mode_skip` is configured, it returns an empty text response to fast-forward these intermittent UI polling requests. Source: [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) (lines 86‑104).

### Filepath Extraction

The `try_filepath_mock` handler intercepts requests asking the model to extract filepaths from commands. Using `is_filepath_extraction_request` and local parsing via `extract_filepaths_from_command` in [`api/command_utils.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/command_utils.py), it returns extracted paths directly when `enable_filepath_extraction_mock` is enabled. Source: [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) (lines 106‑126).

## Configuration and Toggles

All optimization handlers are controlled via boolean fields in the `Settings` class defined in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) (lines 57‑65). By default, these flags are set to `True`, but you can disable specific interceptors via environment variables or a custom `.env` file. Key toggles include:

- **`fast_prefix_detection`** – enables prefix command shortcuts
- **`enable_network_probe_mock`** – mocks quota verification requests
- **`enable_title_generation_skip`** – returns static titles
- **`enable_suggestion_mode_skip`** – bypasses suggestion queries
- **`enable_filepath_extraction_mock`** – local filepath parsing

## Practical Implementation Examples

### Triggering Fast Prefix Detection

Send a command that starts with a known prefix to trigger local handling:

```python
import httpx

payload = {
    "model": "claude-3-opus-20240229",
    "messages": [{"role": "user", "content": "/reset conversation"}]
}

resp = httpx.post(
    "http://localhost:8082/v1/messages",
    json=payload,
    headers={"Authorization": "Bearer dummy"}
)

print(resp.json())

# Returns extracted "reset" command without external API call

```

Because `try_prefix_detection` matches the `/reset` pattern, it returns a fabricated `MessagesResponse` locally.

### Mocking a Quota Probe

Force a quota check interception with a targeted prompt:

```python
payload = {
    "model": "claude-3-opus-20240229",
    "messages": [{"role": "user", "content": "How many tokens can I use?"}]
}
resp = httpx.post("http://localhost:8082/v1/messages", json=payload)
print(resp.json()["content"][0]["text"])

# Output: "Quota check passed."

```

The `is_quota_check_request` detection logic recognizes this pattern and short-circuits the request via `try_quota_mock`.

### Disabling Optimizations per Handler

To force a specific request type through to the provider, disable its handler before starting the server:

```bash
export FAST_PREFIX_DETECTION=false
export ENABLE_TITLE_GENERATION_SKIP=false
uv run python -m free_claude_code.main.server

```

With these flags disabled, the optimization layer will return `None` for these patterns, allowing the normal provider flow to handle the requests.

## Summary

- **Free-Claude-Code** adds a pre-provider optimization layer in [`api/routes.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/routes.py) that intercepts `MessagesRequest` objects before external API calls occur.
- The system uses an ordered pipeline of handlers defined in [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py), checking patterns from cheapest to most expensive and returning the first match.
- Five specific handlers cover quota checks, prefix commands, title generation, suggestion mode, and filepath extraction, each controlled by independent boolean flags in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py).
- When a pattern matches, the system returns a locally fabricated `MessagesResponse`, eliminating network latency and token costs for trivial operations.

## Frequently Asked Questions

### What happens if multiple optimization patterns match a single request?

The dispatcher iterates through `OPTIMIZATION_HANDLERS` in the order defined in [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) (lines 29‑36), which is arranged from cheapest to most expensive checks. The first handler that returns a non-`None` result wins, and subsequent handlers are skipped. This ensures the most efficient response path is always taken.

### How do I completely disable the request optimization layer?

While you cannot disable the entire layer with a single flag, you can set all individual optimization toggles to `false` in your environment. Set `FAST_PREFIX_DETECTION=false`, `ENABLE_NETWORK_PROBE_MOCK=false`, `ENABLE_TITLE_GENERATION_SKIP=false`, `ENABLE_SUGGESTION_MODE_SKIP=false`, and `ENABLE_FILEPATH_EXTRACTION_MOCK=false` before starting the server.

### Where does the pattern detection logic live?

The detection helpers are separated into focused modules for maintainability. [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py) contains the `is_*_request` functions that analyze message content, while [`api/command_utils.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/command_utils.py) provides the `extract_filepaths_from_command` utility used by the filepath mock handler.

### Does the optimization layer affect streaming responses?

No, the optimization layer specifically targets the standard request-response cycle at `/v1/messages`. Because trivial requests like quota checks or prefix commands return static, immediate responses, they do not require streaming. If a request passes through the optimization layer without matching any handler, it proceeds to the normal streaming or non-streaming provider flow as appropriate.