# How to Configure Claude Code Optimization with Context Scaling in oMLX

> Configure Claude Code optimization with context scaling in oMLX. Learn how to auto-compact prompts against a larger virtual context window for better performance.

- Repository: [Jun Kim/omlx](https://github.com/jundot/omlx)
- Tags: how-to-guide
- Published: 2026-05-11

---

**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`](https://github.com/jundot/omlx/blob/main/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.

```python

# 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`](https://github.com/jundot/omlx/blob/main/omlx/server.py). This function implements the scaling formula:

```python

# 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`](https://github.com/jundot/omlx/blob/main/omlx/admin/routes.py) exposes runtime configuration through `PATCH /admin/settings`. The endpoint accepts optional parameters to toggle scaling and adjust the target size:

```python

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

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

```bash
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:

```python
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`](https://github.com/jundot/omlx/blob/main/omlx/server.py):

```python
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`](https://github.com/jundot/omlx/blob/main/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`](https://github.com/jundot/omlx/blob/main/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`](https://github.com/jundot/omlx/blob/main/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`](https://github.com/jundot/omlx/blob/main/omlx/settings.py) (lines 602-607), consumed by the scaling function in [`omlx/server.py`](https://github.com/jundot/omlx/blob/main/omlx/server.py) (lines 20-49), and exposed via HTTP in [`omlx/admin/routes.py`](https://github.com/jundot/omlx/blob/main/omlx/admin/routes.py) (lines 242-300). The actual implementation uses these three files to bridge configuration persistence, calculation logic, and the administrative API.