How free-claude-code Handles FastAPI Request Detection and Routing: A Complete Technical Guide

The free-claude-code FastAPI application inspects every incoming /v1/messages request using pure-Python detection helpers in api/detection.py to determine whether it can be answered instantly via fast-path optimizations or must be streamed from an external LLM provider.

The free-claude-code repository implements a high-performance proxy service built with FastAPI that minimizes latency for common Claude client operations. Understanding how this FastAPI application handles request detection and routing reveals an elegant three-layer architecture that prioritizes sub-millisecond responses for probe requests while seamlessly falling back to external providers for genuine LLM queries.

Receiving Requests at the /v1/messages Endpoint

All client traffic enters through the create_message function defined in api/routes.py (lines 70-78). This async endpoint accepts a MessagesRequest Pydantic model and validates authentication via the require_api_key dependency.

async def create_message(
    request_data: MessagesRequest,
    raw_request: Request,
    settings: Settings = Depends(get_settings),
    _auth=Depends(require_api_key),
):

Once the request payload is parsed and validated, the function immediately delegates to the optimization layer. If no fast-path handler matches, it proceeds to resolve the appropriate LLM provider and stream the response.

The Detection Layer: Pattern Matching in api/detection.py

Before any external API calls occur, the service attempts to classify the request using five specialized detection helpers located in api/detection.py. These pure-Python functions inspect the MessagesRequest payload for specific patterns that indicate the client is performing metadata operations rather than seeking LLM-generated content.

is_quota_check_request (lines 12-26) identifies single-message requests where max_tokens equals 1 and the content contains the string "quota". This pattern indicates the Claude client is performing a network probe to verify API access.

is_title_generation_request (lines 29-38) detects system prompts mentioning "new conversation topic" and "title", which triggers when the client auto-generates conversation titles.

is_prefix_detection_request (lines 41-62) extracts command strings from user messages containing <policy_spec> tags followed by a Command: block, returning the command for instant echo responses.

is_suggestion_mode_request (lines 65-77) scans for the marker [SUGGESTION MODE: in user messages, identifying a specific Claude client interaction pattern that can be short-circuited.

is_filepath_extraction_request (lines 79-110) parses messages containing both Command: and Output: sections with file-path cues, extracting the command and output strings for mock responses.

The Optimization Layer: Fast-Path Handlers

When the endpoint receives a request, it calls try_optimizations from api/optimization_handlers.py before hitting any external provider. This function iterates over a static ordered list of handler functions (lines 29-36), executing the cheapest and most common checks first to enable early short-circuiting.

Each handler follows a consistent three-step pattern:

1. Verify the corresponding feature flag from config/settings.py (such as settings.fast_prefix_detection or settings.enable_network_probe_mock) is enabled.
2. Invoke the appropriate detection helper from api/detection.py.
3. If a match exists, construct and return a pre-crafted MessagesResponse object.

The handler list includes:

• try_prefix_detection (lines 25-44): Returns an echo response containing the extracted command prefix.
• try_quota_mock (lines 46-64): Returns "Quota check passed." for probe requests.
• try_title_skip (lines 66-84): Returns a generic title response to avoid LLM overhead.
• try_suggestion_skip (lines 86-104): Returns an empty suggestion response.
• try_filepath_mock (lines 66-76): Returns the extracted file path as the response content.

If any handler returns a MessagesResponse object, the endpoint immediately sends it as the HTTP response, achieving sub-millisecond latency for these common probe operations.

Routing to External Providers

When try_optimizations returns None, indicating no fast-path pattern matched, the endpoint proceeds to the provider routing logic in api/routes.py (lines 88-102).

provider_type = Settings.parse_provider_type(
    request_data.resolved_provider_model or settings.model
)
provider = get_provider_for_type(provider_type)

The parse_provider_type method converts model names like claude-3-opus-20240229 into internal provider enums, while get_provider_for_type (defined in api/dependencies.py) returns a provider instance implementing the stream_response interface.

The request is then wrapped in a StreamingResponse:

return StreamingResponse(
    provider.stream_response(
        request_data,
        input_tokens=input_tokens,
        request_id=request_id,
    ),
    media_type="text/event-stream",
)

This streams Server-Sent Events from the external LLM provider back to the client, maintaining full compatibility with the Claude API specification.

Application Bootstrap and Lifecycle

The FastAPI application factory resides in api/app.py, where the lifespan context manager initializes optional messaging platforms (Telegram, Discord) and stores them in app.state. The core routing is attached via:

app.include_router(router)  # Lines 104-106

This wires the detection-to-optimization-to-provider flow into the FastAPI lifecycle at application startup.

Practical Implementation Examples

The following examples demonstrate how the detection and routing logic processes different request types.

Example 1: Quota Probe (Instant Response)

curl -X POST https://my-proxy/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-3-opus-20240229",
        "max_tokens": 1,
        "messages": [{"role":"user","content":"quota"}]
      }'

Because max_tokens equals 1 and the message contains "quota", is_quota_check_request returns True. The try_quota_mock handler creates an instant response with "Quota check passed.", bypassing the external provider entirely.

Example 2: Prefix Detection (Fast-Path)

curl -X POST https://my-proxy/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-3-sonnet-20241022",
        "messages": [{
          "role":"user",
          "content":"<policy_spec>…</policy_spec>\nCommand: echo hello"
        }]
      }'

The is_prefix_detection_request helper extracts echo hello, triggering try_prefix_detection to return a response where content[0]["text"] contains the command prefix. No LLM provider is contacted.

Example 3: Normal LLM Query (Provider Stream)

curl -X POST https://my-proxy/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-3-opus-20240229",
        "messages": [{"role":"user","content":"Explain quantum entanglement"}]
      }'

No detection rule matches this generic query. The request routes to the configured provider (OpenRouter, OpenAI-compatible, or LMStudio) and streams back via StreamingResponse.

Summary

• The create_message endpoint in api/routes.py serves as the entry point, delegating to the optimization layer before attempting provider routing.
• api/detection.py contains five pure-Python helpers that classify requests into patterns like quota checks, title generation, and command extraction.
• api/optimization_handlers.py implements try_optimizations, which runs an ordered list of fast-path handlers gated by feature flags from config/settings.py.
• Fast-path responses achieve sub-millisecond latency by returning pre-crafted MessagesResponse objects without external API calls.
• Unmatched requests flow through Settings.parse_provider_type and get_provider_for_type to stream responses from external LLM providers as Server-Sent Events.

Frequently Asked Questions

What triggers the fast-path optimization in free-claude-code?

Fast-path optimization triggers when a request matches one of five detection patterns implemented in api/detection.py. The system checks for quota probes (max_tokens=1 with "quota" content), title generation prompts, prefix detection with <policy_spec> tags, suggestion mode markers, or filepath extraction blocks. If the corresponding feature flag in config/settings.py is enabled and the pattern matches, the optimization handler returns an instant response.

How does the detection layer identify quota check requests?

The is_quota_check_request function (lines 12-26 in api/detection.py) identifies quota checks by verifying two conditions: the request contains exactly one message, and that message has max_tokens set to 1 with content including the string "quota". This pattern indicates the Claude client is performing a network connectivity probe rather than requesting generated content.

What happens when no optimization pattern matches?

When try_optimizations returns None, the endpoint resolves the provider using Settings.parse_provider_type and retrieves the provider instance via get_provider_for_type from api/dependencies.py. The request is then wrapped in a StreamingResponse with media_type="text/event-stream", which streams the LLM response from the external provider back to the client using Server-Sent Events.

Where are the feature flags for optimizations configured?

Feature flags such as fast_prefix_detection, enable_network_probe_mock, and others are defined in config/settings.py. Each optimization handler in api/optimization_handlers.py checks its corresponding flag before executing the detection logic, allowing operators to enable or disable specific fast-path behaviors via environment variables or configuration files.

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