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

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 (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. 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, this handler returns a minimal response with the text "Quota check passed." without querying the provider. Source: 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 and returns it as plain text, eliminating the need for LLM parsing. Source: 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 (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 (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, it returns extracted paths directly when enable_filepath_extraction_mock is enabled. Source: 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 (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:

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:

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:

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 that intercepts MessagesRequest objects before external API calls occur.
• The system uses an ordered pipeline of handlers defined in 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.
• 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 (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 contains the is_*_request functions that analyze message content, while 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.

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