Downshift documentation

Guide

• Install Downshift: Claude Code, Codex and Cursor hook setup

  Install Downshift and wire its PreToolUse hook into Claude Code, Codex, Cursor and other harnesses: install.sh, setup --dry-run, doctor checks and manual setup.

• Downshift configuration: state directory and local settings

  Where Downshift keeps its local state, how the state directory is resolved, and how downshift config prints each effective setting and its source.

• Downshift and Claude Code subagents: when routing can act

  A Claude Code subagent is routable only when its model is not pinned. How the frontmatter model field decides whether Downshift may rewrite that spawn.

• Downshift session view: subagent tree, reasons and pause

  downshift session shows what Downshift did in one session: a subagent tree with model and observed tokens where available, why each spawn was routed, and pause and resume.

• Downshift report: routed versus control tokens per completed task

  How downshift report compares tokens per completed task between routed spawns and a small unrouted control group; it prints no dollar amounts.

• Downshift evidence ladder: what each saving figure means

  Different evidence levels cover catalog list prices, token telemetry, benchmarks, routed-versus-control comparisons and task outcomes.

• Downshift companions: Headroom and Claude Code mods to pair

  Tools that work next to Downshift, such as the Headroom compression proxy and Claude Code mods: what Downshift detects, records and never does for them.

• Downshift offline simulation: routing without model calls

  An offline simulation replays synthetic spawns through the real hook path of four harnesses and fails CI when a savings accounting rule breaks.

Reference

• Downshift capability matrix: status and evidence per feature

  Every Downshift capability with one status word and its evidence, read from code, tests and dated files: routing, guardrails, harnesses, telemetry and cost.

• Downshift capability matrix, part 2: context and packaging

  Part 2 of the Downshift capability matrix: context optimization, project policy, shadow learning, benchmarks, packaging, overclaims and hidden capabilities.

• Downshift harness matrix: Claude Code, Codex, Cursor status

  Which harnesses honor Downshift's model rewrite: status per harness, plan limits, and child end and usage observation for Claude Code, Codex and Cursor.

• Downshift value per harness: observed tokens vs list price

  How much of what routing did is observed per harness and how much is list-price arithmetic: tokens by tier, tokens rerouted, usage sources and catalog prices.

• Downshift spawn state: switched, held or only observed

  Every subagent spawn gets one state, switched, held, observed, paused, control or blocked, shown on stderr, in session watch, the statusline and a live panel.

• Downshift session models: which model IDs a hook may write

  Downshift writes only a model id that exists in the current harness session. How session lists, metadata and catalog fallback work, and Claude Code inference.

• Downshift complexity weights: how a task becomes a model

  How Downshift scores a task with weighted signals into TRIVIAL, SIMPLE, MEDIUM or COMPLEX, when the score is confident, and how a tier maps to a model.

Design

• Downshift architecture: deterministic hook and offline CLI

  Downshift is one Go binary that runs as a harness hook and an offline CLI: how it classifies delegated tasks, rewrites the subagent model and records results.

Evidence

• Downshift routed vs control: first Claude Code A/B results

  The first controlled Downshift measurement: routed versus control runs on real and mechanical Claude Code tasks, with cost, pass rates and their limits.

• Downshift real usage: a Claude Code day and the last 30 days

  What Downshift did on one real Claude Code working day and over 30 days for one operator: decisions, downshifts, guardrail holds and what can be claimed.

• Downshift Code Intelligence MVP: evidence for Claude Code

  Downshift Code Intelligence v0.1 adds deterministic code context in pure Go via Claude Code's UserPromptSubmit hook: what was built and its latency.

Looking for articles instead? Read the Claude Code guides