Skip to content
This repository was archived by the owner on Nov 10, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 8 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ By default claudetm uses the global `~/.claude/.credentials.json` session. **Pro
There are two profile types:

- **`oauth`** — an isolated Claude Code config home. Each profile gets its own credentials directory under `~/.claudetm/profiles/<name>/`, so two subscriptions never clobber each other.
- **`api-key`** — a direct API key + base URL (e.g. z.ai / GLM via an Anthropic-compatible endpoint), injected as `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`. It can also carry **per-tier model and context-window overrides** so claudetm routes every complexity level to a model the endpoint actually serves.
- **`api-key`** — a direct API key + base URL (e.g. z.ai / GLM via an Anthropic-compatible endpoint), injected as `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`. It can also carry **per-tier model overrides** so claudetm routes every complexity level to a model the endpoint actually serves. Context-window values are also accepted, but are currently inert metadata: they do not control runtime compaction or grant context.

```bash
# Create an oauth profile and log into it (opens claude in its isolated dir)
Expand All @@ -95,8 +95,9 @@ CLAUDETM_API_KEY=sk-... claudetm profile add zai --type api-key \
--base-url https://api.z.ai/api/anthropic

# An api-key profile against a custom endpoint: name a model for each tier
# (and optionally its context size in tokens). Tiers you omit inherit from a
# family neighbour, so naming just opus/sonnet/haiku covers every task.
# and optionally record context-window metadata (currently inert). Model tiers
# you omit inherit from a family neighbour, so naming just opus/sonnet/haiku
# covers every task.
#
# --model-opus coding tasks (complex implementation) — the smart tier
# --model-sonnet general tasks (balanced)
Expand Down Expand Up @@ -312,7 +313,7 @@ claudetm --init-config
claudetm --show-config
```

This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defaults to **Claude Opus 5** (`claude-opus-5`), whose context window is **1M tokens natively** — so `context_windows.opus` defaults to `1000000`. (There is no `claude-opus-5[1m]` model ID; that suffix is a Claude Code CLI convention and 404s against the API.) Override the model by editing the `"opus"` key or setting `CLAUDETM_MODEL_OPUS`; drop `context_windows.opus` to `200000` if your account is capped at standard context. A separate opt-in `fable` tier defaults to **Claude Fable 5** (`claude-fable-5`, premium-priced at 2x Opus) — mirroring Claude Code's `ANTHROPIC_DEFAULT_FABLE_MODEL`; override via the `"fable"` key or `CLAUDETM_MODEL_FABLE`. No task routes to it by default; set `CLAUDETM_MODEL_OPUS=claude-fable-5` to run the smartest tier on Fable.
This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defaults to **Claude Opus 5** (`claude-opus-5`), whose context window is **1M tokens natively** — so `context_windows.opus` defaults to `1000000` as metadata only, with no runtime compaction effect. (There is no `claude-opus-5[1m]` model ID; that suffix is a Claude Code CLI convention and 404s against the API.) Override the model by editing the `"opus"` key or setting `CLAUDETM_MODEL_OPUS`; changing `context_windows.opus` does not change the context available to your account. A separate opt-in `fable` tier defaults to **Claude Fable 5** (`claude-fable-5`, premium-priced at 2x Opus) — mirroring Claude Code's `ANTHROPIC_DEFAULT_FABLE_MODEL`; override via the `"fable"` key or `CLAUDETM_MODEL_FABLE`. No task routes to it by default; set `CLAUDETM_MODEL_OPUS=claude-fable-5` to run the smartest tier on Fable.

```json
{
Expand Down Expand Up @@ -342,15 +343,9 @@ This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defau
}
```

> **Note:** `context_windows` only drives claudetm's **auto-compact threshold** — it does not grant a bigger window. Over-stating a window means compaction fires too late and the session overflows; under-stating it just compacts early, which is harmless. So the defaults are deliberately conservative, and only `opus` claims 1M:
> **Note:** `context_windows` and `CLAUDETM_CONTEXT_*` are **currently inert metadata** retained for compatibility. Values can still be loaded from configuration, emitted by profiles, and read by the context-window helper, but they do not drive runtime auto-compaction, prevent context overflow, or grant a larger context window. Actual context limits and compaction behavior depend on Claude Code/SDK and the provider, not these settings.
>
> | Tier | Default | Why |
> |---|---|---|
> | `opus` | 1000000 | Opus is upgraded to 1M automatically on Max/Team/Enterprise. **On Pro that upgrade is billed to usage credits** — set `200000` if you don't buy them. |
> | `sonnet` | 200000 | Conservative. On a subscription the 1M window is the paid extra, so this only goes to `1000000` once you've confirmed your account actually serves it. |
> | `haiku` | 200000 | Haiku 4.5's real window. |
>
> Two setups cap 1M-capable models at 200K regardless of plan, and want `200000` for every tier: an LLM gateway (`ANTHROPIC_BASE_URL` pointing somewhere Claude Code can't verify 1M support) and `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`.
> Existing configurations such as the following remain accepted, but changing these values for an account tier or gateway has no runtime compaction effect:
> ```json
> "context_windows": {
> "opus": 200000,
Expand All @@ -374,7 +369,7 @@ The config file sets these environment variables before Python starts:
| `models.fable` | `CLAUDETM_MODEL_FABLE` | Model for fable tier (opt-in, premium) |
| `models.haiku` | `CLAUDETM_MODEL_HAIKU` | Model for haiku tier |
| `models.sonnet_1m` | `CLAUDETM_MODEL_SONNET_1M` | Model for debugging/QA tier (big context) |
| `context_windows.*` | `CLAUDETM_CONTEXT_{OPUS,FABLE,SONNET,HAIKU,SONNET_1M}` | Context window per tier (tokens) |
| `context_windows.*` | `CLAUDETM_CONTEXT_{OPUS,FABLE,SONNET,HAIKU,SONNET_1M}` | Currently inert per-tier metadata (tokens); does not control runtime compaction or grant context |
| `git.target_branch` | `CLAUDETM_TARGET_BRANCH` | Target branch for PRs |

Precedence (highest first): real environment variables, then the **active profile** (api-key/oauth profiles supply these same keys), then the config file.
Expand Down
42 changes: 21 additions & 21 deletions src/claude_task_master/core/agent_models.py
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
"""Agent Models - Enums, constants, and utility functions for model configuration.

This module contains:
- ModelType: Available Claude models (Sonnet, Opus, Haiku, Sonnet 1M)
- ModelType: Available Claude models (Sonnet, Opus, Fable, Haiku, Sonnet 1M)
- TaskComplexity: Task complexity levels for dynamic model selection,
including get_model_name_for_complexity for name-based model routing
- ToolConfig: Tool configurations for different execution phases (now config-backed)
- MODEL_CONTEXT_WINDOWS: Model context window sizes
- MODEL_CONTEXT_WINDOWS: Retained context-window metadata defaults
- parse_task_complexity: Parse complexity tags from task descriptions
- get_tools_for_phase: Get tool list for a phase from global config
"""
Expand Down Expand Up @@ -104,27 +103,25 @@ def get_model_name_for_complexity(cls, complexity: TaskComplexity) -> ModelType:
# Constants
# =============================================================================

# Model context window sizes (tokens) for auto-compact threshold calculation.
# These are defaults; users can override via config.json "context_windows" section.
# Opus 5 and Sonnet 5 both report a 1M context window from the Models API.
# Note: The Agent SDK handles the `context-1m-2025-08-07` beta header internally.
# These values are only used to calculate when to trigger context compaction.
# See: https://platform.claude.com/docs/en/build-with-claude/context-windows
# Retained context-window metadata defaults (tokens) for get_context_window.
# The helper can read config.json "context_windows" overrides, but has no runtime
# compaction caller. These values do not set compaction thresholds or select a
# larger SDK window; they are retained for compatibility.
MODEL_CONTEXT_WINDOWS = {
ModelType.OPUS: 1_000_000, # Claude Opus 5: 1M context (native, per Models API)
ModelType.FABLE: 1_000_000, # Claude Fable 5: 1M context (default, no beta gate)
ModelType.SONNET: 1_000_000, # Claude Sonnet 5: 1M context (beta, tier 4+)
ModelType.HAIKU: 200_000, # Claude Haiku 4.5: 200K context
ModelType.SONNET_1M: 1_000_000, # Sonnet with 1M context (always 1M)
ModelType.OPUS: 1_000_000,
ModelType.FABLE: 1_000_000,
ModelType.SONNET: 1_000_000,
ModelType.HAIKU: 200_000,
ModelType.SONNET_1M: 1_000_000,
}

# Standard context windows (for users below tier 4)
# Legacy standard-window metadata, retained for compatibility; also inert at runtime.
MODEL_CONTEXT_WINDOWS_STANDARD = {
ModelType.OPUS: 200_000,
ModelType.FABLE: 1_000_000, # Fable 5's 1M window is the default, not tier-gated
ModelType.FABLE: 1_000_000,
ModelType.SONNET: 200_000,
ModelType.HAIKU: 200_000,
ModelType.SONNET_1M: 1_000_000, # Always 1M — that's the point
ModelType.SONNET_1M: 1_000_000,
}

# Fallback model mapping: if primary model unavailable, try fallback
Expand Down Expand Up @@ -190,14 +187,17 @@ def get_context_window(
model: ModelType,
config: ClaudeTaskMasterConfig | None = None,
) -> int:
"""Get context window size for a model, reading from config if available.
"""Read retained context-window metadata, using config when supplied.

This compatibility helper has no runtime compaction caller. Its return value
does not set a compaction threshold or select the SDK's context window.

Args:
model: The model type.
config: Optional config object. If None, uses hardcoded defaults.

Returns:
Context window size in tokens.
Context-window metadata in tokens, not a runtime capacity guarantee.
"""
if config is not None:
context_map = {
Expand All @@ -211,8 +211,8 @@ def get_context_window(
return MODEL_CONTEXT_WINDOWS[model]


# Default compact threshold as percentage of context window
DEFAULT_COMPACT_THRESHOLD_PERCENT = 0.85 # Compact at 85% usage
# Legacy compact-threshold constant, retained for compatibility and unused at runtime.
DEFAULT_COMPACT_THRESHOLD_PERCENT = 0.85


# =============================================================================
Expand Down
45 changes: 18 additions & 27 deletions src/claude_task_master/core/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,49 +117,39 @@ class GitConfig(BaseModel):


class ContextWindowsConfig(BaseModel):
"""Context window sizes per model (in tokens).
"""Retained context-window metadata per model (in tokens).

Controls the max context window size used for auto-compact threshold calculation.

These only drive *when claudetm compacts* -- they do not grant a larger window. So
the bias is deliberate: under-stating a window compacts early (harmless), over-stating
it compacts too late and overflows the session. Defaults track a Claude Code
subscription, the auth path claudetm runs on:

- ``opus`` -- 1M. Automatically upgraded on Max/Team/Enterprise with no extra
configuration. **On Pro this requires usage credits**; set 200000 there.
- ``sonnet`` -- 200K, the conservative default. Raise to 1000000 only once you have
confirmed your account actually serves Sonnet at 1M.
- ``haiku`` -- 200K, which is Haiku 4.5's real window.

Two setups budget 1M-capable models at 200K regardless of plan, and want 200000 for
every tier here: an LLM gateway (``ANTHROPIC_BASE_URL`` pointing somewhere Claude Code
cannot verify 1M support) and ``CLAUDE_CODE_DISABLE_1M_CONTEXT=1``.
Values remain loadable from configuration and ``CLAUDETM_CONTEXT_*`` environment
variables, including those emitted by profiles, and readable by ``get_context_window``.
They are currently inert for runtime compaction and window selection: changing them
does not set a compaction threshold, prevent context overflow, or grant a larger
SDK context window. Defaults and keys are retained for compatibility.
"""

opus: int = Field(
default=1_000_000,
description="Opus context window size in tokens. 1000000 matches the automatic "
"1M upgrade on Max/Team/Enterprise; set to 200000 on Pro (1M needs usage credits "
"there) or behind an LLM gateway.",
description="Opus context-window metadata in tokens; currently inert for runtime "
"compaction and SDK window selection.",
)
fable: int = Field(
default=1_000_000,
description="Fable context window size in tokens. Claude Fable 5 is 1M by default.",
description="Fable context-window metadata in tokens; currently inert for runtime "
"compaction and SDK window selection.",
)
sonnet: int = Field(
default=200_000,
description="Sonnet context window size in tokens. 200000 is the conservative "
"default (1M on a subscription is billed to usage credits); raise to 1000000 "
"only once you have confirmed your account serves Sonnet at 1M.",
description="Sonnet context-window metadata in tokens; currently inert for runtime "
"compaction and SDK window selection.",
)
haiku: int = Field(
default=200_000,
description="Haiku context window size in tokens.",
description="Haiku context-window metadata in tokens; currently inert for runtime "
"compaction and SDK window selection.",
)
sonnet_1m: int = Field(
default=1_000_000,
description="Sonnet 1M context window size in tokens. Always 1M.",
description="Sonnet 1M context-window metadata in tokens; currently inert for runtime "
"compaction and SDK window selection.",
)


Expand Down Expand Up @@ -251,7 +241,8 @@ class ClaudeTaskMasterConfig(BaseModel):
)
context_windows: ContextWindowsConfig = Field(
default_factory=ContextWindowsConfig,
description="Context window sizes per model (tokens). Set to 200000 if not on tier 4+.",
description="Retained context-window metadata per model (tokens); currently inert for "
"runtime compaction and SDK window selection.",
)
git: GitConfig = Field(
default_factory=GitConfig,
Expand Down
27 changes: 14 additions & 13 deletions src/claude_task_master/core/profiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,10 @@
- ``api-key`` - a direct API key + base URL injected as ``ANTHROPIC_API_KEY`` /
``ANTHROPIC_BASE_URL`` (e.g. z.ai / GLM via an Anthropic-compatible endpoint).
May also carry per-tier ``models`` (opus/sonnet/haiku/sonnet_1m/fable -> a
provider-valid model id) and ``context_windows`` overrides; tiers the profile
omits inherit from a family neighbour so a partial profile still routes every
complexity level to a model the endpoint actually serves.
provider-valid model id); omitted model tiers inherit from a family neighbour
so a partial profile still routes every complexity level to a model the
endpoint actually serves. ``context_windows`` metadata also supports family
fallback, but is currently inert for runtime compaction and window selection.

The registry lives in ``~/.claudetm/profiles.json`` (override the base directory
with the ``CLAUDETM_HOME`` env var). The active profile is a single pointer,
Expand Down Expand Up @@ -111,10 +112,11 @@ class Profile(BaseModel):
default=None,
description="Model name overrides (opus, sonnet, fable, haiku, sonnet_1m → custom IDs).",
)
# Optional context window overrides (in tokens)
# Optional context-window metadata (tokens), retained for compatibility.
context_windows: dict[str, int] | None = Field(
default=None,
description="Context window sizes per model (opus, sonnet, fable, haiku, sonnet_1m → tokens).",
description="Context-window metadata per model (tokens); currently inert for runtime "
"compaction and SDK window selection.",
)

def validate_for_type(self) -> None:
Expand Down Expand Up @@ -235,13 +237,11 @@ def env_for_profile(profile: Profile) -> dict[str, str]:
if value:
env[env_var] = value

# Context window overrides (tokens). Read by the config loader to size the
# auto-compact threshold per tier. As with models, a partial mapping still
# covers every tier via family fallback (sonnet_1m <- sonnet <- opus,
# fable <- opus <- sonnet). This matters for custom endpoints whose real
# context is far below the Claude defaults: without it claudetm assumes
# e.g. 1M for sonnet_1m and never compacts before the provider's smaller
# limit is hit ("The model has reached its context window limit").
# Context-window metadata (tokens) is emitted as CLAUDETM_CONTEXT_* and
# loaded into config. Missing sonnet_1m/fable values use family fallback
# (sonnet_1m <- sonnet <- opus, fable <- opus <- sonnet). These values are
# currently inert for runtime compaction and SDK window selection; emission
# and loading do not set a compaction threshold or prevent context overflow.
if profile.context_windows:
ctx = dict(profile.context_windows)
if not ctx.get("sonnet_1m"):
Expand Down Expand Up @@ -452,7 +452,8 @@ def add(
api_key: API key (required for ``api-key`` profiles).
base_url: Anthropic-compatible base URL (``api-key`` profiles).
models: Optional model name overrides (e.g., {"opus": "glm-5.2[1m]", "sonnet": "glm-4.7"}).
context_windows: Optional context window sizes per model (in tokens).
context_windows: Optional context-window metadata per model (tokens), currently
inert for runtime compaction and SDK window selection.

Returns:
The created profile.
Expand Down
9 changes: 5 additions & 4 deletions tests/core/test_profiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -253,10 +253,11 @@ def test_context_windows_emitted(self) -> None:
assert env["CLAUDETM_CONTEXT_SONNET"] == "128000"

def test_context_family_fallback_covers_all_tiers(self) -> None:
"""sonnet_1m/fable context inherit their family neighbour so claudetm
compacts in time on custom endpoints whose real context is below the
Claude defaults (otherwise it assumes 1M and never compacts before the
provider's smaller limit -> 'context window limit' crash)."""
"""sonnet_1m/fable context env values inherit from sonnet/opus respectively.

This asserts environment-value propagation, not overflow prevention:
context_windows remains currently inert for runtime compaction.
"""
p = Profile(
name="zai",
type="api-key",
Expand Down
Loading