How to Configure Claude Code Optimization with Context Scaling in oMLX

Enable context_scaling_enabled and set your desired target_context_size in the global configuration to make Claude Code auto-compact prompts against a virtual context window larger than the model's actual limit.

The oMLX repository provides a Claude Code integration that rescales token counts to trick the optimizer into treating smaller models as if they had massive context windows. This configuration lives in the ClaudeCodeSettings dataclass and is applied at runtime through the Admin API, allowing you to optimize prompt compression behavior without switching underlying models.

Understanding Context Scaling for Claude Code

The Core Settings

Configuration is stored in the ClaudeCodeSettings dataclass defined in omlx/settings.py. Two fields control the scaling behavior:

• context_scaling_enabled (bool, default False): Toggles the rescaling logic on or off.
• target_context_size (int, default 200000): The virtual context window size you want Claude Code to assume.

# omlx/settings.py

@dataclass
class ClaudeCodeSettings:
    """Claude Code integration settings."""
    context_scaling_enabled: bool = False
    target_context_size: int = 200000  # Claude Code default (200k)

How Token Scaling Works

When processing requests, oMLX calls scale_anthropic_tokens in omlx/server.py. This function implements the scaling formula:

# omlx/server.py

def scale_anthropic_tokens(token_count: int, model_id: str | None = None) -> int:
    cc = global_settings.claude_code
    if not cc.context_scaling_enabled:
        return token_count
    actual = get_max_context_window(model_id)
    if not actual or actual >= cc.target_context_size:
        return token_count
    return int(token_count * cc.target_context_size / actual)

The logic follows three steps:

1. Return unchanged if scaling is disabled or the actual model window exceeds the target.
2. Calculate the ratio between your target and the actual window size.
3. Return inflated counts using scaled = int(token_count × target / actual).

This causes Claude Code's auto-compact logic to fire earlier, keeping prompts within your defined virtual window even when using models with smaller native limits.

Configuring Context Scaling via the Admin API

Updating Settings via HTTP PATCH

The admin route in omlx/admin/routes.py exposes runtime configuration through PATCH /admin/settings. The endpoint accepts optional parameters to toggle scaling and adjust the target size:

# omlx/admin/routes.py

claude_code_context_scaling_enabled: Optional[bool] = None
claude_code_target_context_size: Optional[int] = None

When present in the request payload, the server updates the global settings object:

if request.claude_code_target_context_size is not None:
    global_settings.claude_code.target_context_size = request.claude_code_target_context_size

Using the Python Client

You can also configure scaling programmatically using the oMLX Python client instead of raw HTTP requests.

Practical Implementation Examples

Enable Scaling from the Command Line

Send a PATCH request to the admin endpoint to activate context scaling and set a 300,000-token virtual window:

curl -X PATCH http://localhost:8000/admin/settings \
  -H "Content-Type: application/json" \
  -d '{
    "claude_code_context_scaling_enabled": true,
    "claude_code_target_context_size": 300000
  }'

Configure via Python Client

Use the OMLXClient to update settings and verify the configuration:

from omlx.client import OMLXClient

client = OMLXClient(base_url="http://localhost:8000")

# Enable context scaling

client.patch_settings({
    "claude_code_context_scaling_enabled": True,
    "claude_code_target_context_size": 300000,
})

# Verify effective settings

settings = client.get_settings()
print(settings["claude_code"])

# Output: {'context_scaling_enabled': True, 'target_context_size': 300000, ...}

Manual Scaling for Custom Tooling

If you need to calculate the scaling factor outside the server—for example, in preprocessing scripts—replicate the formula from omlx/server.py:

def scaled_token_count(token_count: int, actual_window: int, target_window: int) -> int:
    if actual_window >= target_window:
        return token_count
    return int(token_count * target_window / actual_window)

# Example: Scale 5,000 tokens from 8k actual to 300k target

scaled = scaled_token_count(5000, actual_window=8192, target_window=300_000)
print(scaled)  # 183105

Summary

• context_scaling_enabled toggles the virtual context window feature in omlx/settings.py.
• target_context_size defines the virtual window size (default 200,000) used in the scaling calculation.
• scale_anthropic_tokens in omlx/server.py applies the formula token_count × (target / actual) when the actual model window is smaller than the target.
• Admin API endpoints in omlx/admin/routes.py allow runtime updates via PATCH requests without restarting the server.
• Python Client provides a programmatic interface to configure and verify settings.

Frequently Asked Questions

What happens if the actual model context is larger than my target size?

If the model's native context window equals or exceeds target_context_size, scale_anthropic_tokens returns the original token count unchanged. The scaling logic only activates when the actual window is strictly smaller than your target, as implemented in the guard clause: if not actual or actual >= cc.target_context_size: return token_count.

Can I disable context scaling after enabling it?

Yes. Send a PATCH request to /admin/settings with "claude_code_context_scaling_enabled": false, or call client.patch_settings({"claude_code_context_scaling_enabled": False}) using the Python client. The server updates the global ClaudeCodeSettings object immediately, and subsequent requests will report unscaled token counts to Claude Code.

Why would I set a target larger than 200,000 tokens?

The default 200k target matches Claude Code's native expectation, but increasing it to 300k or 500k forces the optimizer to compress prompts more aggressively. This is useful when working with very large codebases where you want Claude Code to make tougher optimization decisions about what context to retain, even if the underlying Anthropic model has a smaller native window (such as 4k or 8k variants).

Where are the context scaling settings stored in the codebase?

The settings are defined in the ClaudeCodeSettings dataclass at omlx/settings.py (lines 602-607), consumed by the scaling function in omlx/server.py (lines 20-49), and exposed via HTTP in omlx/admin/routes.py (lines 242-300). The actual implementation uses these three files to bridge configuration persistence, calculation logic, and the administrative API.

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