downshift-ai

# Downshift — LLM and AI Agent Notice
# https://github.com/tiagovilasboas/downshift-ai

## Project

Downshift gives a coding agent the right model and less noise, with no extra
AI call. It runs locally as a single Go binary (CLI: downshift) through hooks in
the coding harness. Prompts are never stored, nothing goes over the network,
and every hook fails open. Two pillars, in this order:

1. Model choice per subagent. The orchestrator (the session's LLM) chooses the
   model and effort of each spawn; a PreToolUse hook applies that choice within
   your declared policy.json and measures the result. Downshift adds no LLM
   call of its own; when it cannot read the request, the session's model stays. Every spawn is routed
   (the control group was removed on 2026-11-02). Implemented. Harness status: Claude Code
   Completed (rewrite observed honored), Codex and Cursor Functional, OpenCode
   Beta, Antigravity and KiroCrew Experimental (docs/reference/harness-matrix.md).
2. The Compactor (downshift compact). Shorter output from allowlisted commands:
   every git subcommand and the listed test and build families (the git-* row
   of the harness matrix). It keeps the exit code and leaves failures raw. It
   is not the /compact command. Implemented, on by default. Automatic rewrite
   into compact form is Claude Code only; elsewhere the agent runs
   `downshift compact -- <command>`.
   Desktop reads: `agent-desktop snapshot` and `find` (accessibility-tree JSON)
   are re-encoded one line per element with every field kept; a repeat read
   of the same window is sent as the lines that changed (every harness).
   Synthetic fixtures: 53-60% fewer bytes on a first read, about 97% on a
   repeat read (docs/guides/agent-desktop.md).

Numbers keep their qualifiers. Routing: up to about 12% cheaper on mechanical tasks
in one controlled trial (one operator, three runs per cell, Claude Code, 2026-10-15, list price;
checks verify structure, not quality); no savings from natural use are
attributable yet (docs/evidence/subagent-routing-ab-2026-10-15.md). Compaction:
bytes on the current 113-fixture synthetic corpus (command output and
agent-desktop reads): 69.4% fewer with CCR on, 52.6% with it off, 59.3% on the
64 lossless fixtures (docs/reference/bench.md, `make bench`). Reports show
tokens, not dollars.

Where next: install docs/guides/install.md; how it works
docs/design/architecture.md; evidence docs/guides/evidence.md; status of every
capability docs/reference/capability-matrix.md.

The suite (one sentence each; status words from docs/reference/capability-matrix.md):
  - Applying the orchestrator's choice: a PreToolUse hook sets one subagent's model
    and effort as chosen, within your declared policy. Implemented; honored on Claude Code.
  - Guardrails, doubt never spends money: R1-R9 hold unconfident downshifts,
    upshifts and frontier picks; risk categories keep a floor. Implemented.
  - Project tier floor: .downshift/policy.json raises a minimum tier, never lowers.
    Implemented, every harness.
  - Quota and credit gate: hook marks or native snapshots hold rewrites to models
    without credit; stale after 1 h. Implemented, not validated everywhere.
  - Session view and statusline: downshift session --tree, /downshift, watch,
    stderr line per spawn; statusline Claude Code only. Implemented.
  - Telemetry and token reports: prompt-free events.jsonl, downshift stats /
    report. Implemented; estimates.
  - Context policy: setup sets opusplan, plan mode, You should know for unset
    keys (Claude Code only); native compressor observes bytes. Implemented, limited.
  - Companions: a compression proxy (detected and recorded),
    never installed or wrapped. docs/guides/companions.md
  - Evidence ladder: rungs A-E; rung D reached once (2026-10-15), rung E not
    measured. docs/guides/evidence.md

Models it knows (internal/catalog/catalog.json, version 2, 2026-10-16, 34 entries):
  Claude Code: claude-haiku (small), claude-sonnet (mid), claude-opus and
  claude-fable (frontier), grok by custom config. Cursor: Anthropic thinking
  variants, gpt-5.6-sol, gemini, grok, glm, muse-spark, composer. Codex:
  gpt-6-luna / gpt-5.6-luna (small), gpt-5.6-terra (mid), gpt-6-sol / gpt-6.1-sol /
  gpt-5.6-sol (frontier), gpt-6-astra (explicit_only). Antigravity: flash_lite,
  flash, pro. KiroCrew: the Anthropic families. Lookup is exact, then alias, then
  family prefix; OpenRouter-style provider/ prefixes are stripped first;
  explicit_only (gpt-6-astra, claude-fable-5-1-thinking-high) is never chosen
  automatically. On Claude Code the session list is inferred from the current
  model (catalog ladder below it), so routing only moves down from it.

Session-first resolution: session IDs are the complete candidate set. Valid exact
  model_metadata takes precedence; catalog metadata is optional fallback. A
  declared capability-ordered list can rank new IDs; unordered native availability
  cannot. Malformed metadata rejects its ID.
  docs/reference/session-models.md, internal/core/session_resolver.go
Languages: regex signals in English and Portuguese plus the in-process FNV
  word-hash boost (raise-only, SEMANTIC_BOOST). A heuristic language guard clears
  confidence outside coverage. DOWNSHIFT_MINILM=0 disables the hash boost (legacy
  flag name). External MiniLM commands, E5 and Graphify were removed 2026-10-17.
  docs/contrib/classifier.md, docs/design/minilm-semantic.md
Visual guide: docs/img/downshift-bdi.svg (BDI conceptual lens, not a planner), then
  docs/img/downshift-execution.svg (current runtime and observation boundaries).
  docs/design/architecture.md maps code ownership and guia/sensor coverage.
Capability matrix with status and evidence: docs/reference/capability-matrix.md
Evidence ladder and metrics: docs/guides/evidence.md
Benchmark protocol (Opus fixed vs opusplan vs opusplan + Downshift): docs/guides/benchmark-protocol.md
Claude Code guide (opusplan, baseline inference, emitted vs honored vs used): docs/guides/claude-code.md

Author: Tiago Vilas Boas
Repository: https://github.com/tiagovilasboas/downshift-ai
Language: Go 1.27, single static binary, nothing to install at runtime. Every package under internal/ uses the standard library only, except the MCP transport that wraps the official Go SDK (checked by a test); the binary also links a few terminal libraries through its command layer.

Install and harness setup (canonical for agents): docs/guides/install.md
Claude Code plugin (hooks, /downshift, skills, example agent; binary still required):
  /plugin install downshift --marketplace tiagovilasboas/downshift-ai
Agent skills in skills/: downshift-setup, downshift-audit, downshift-tune (SKILL.md, any harness)
Claude Code mod in mods/downshift-agents: band above the prompt and /ds-agents pane (tasks,
  subagents, Compactor, routing); observe-only; installed by downshift setup, --no-mods skips it

Assisted setup for AI agents (ask the user before any write outside the repo):
  1. curl -fsSL https://raw.githubusercontent.com/tiagovilasboas/downshift-ai/main/install.sh | sh
     run it when downshift is missing OR `downshift version` is older than the latest release
     (https://github.com/tiagovilasboas/downshift-ai/releases/latest); `setup` saying "up to date"
     checks the config, not the binary. After installing, `which -a downshift`: the first one
     must be the new one (an older copy in ~/go/bin shadows it; the installer warns)
     (if it says the release has no archive for this platform: sh -s <tag> from https://github.com/tiagovilasboas/downshift-ai/releases, or go install ...@<tag>)
  2. downshift setup --dry-run        # show the diff to the user, naming hooks, MCP server (--no-mcp),
                                      # skills incl. ponytail, and the downshift-agents mod (--no-mods)
  3. downshift setup --yes            # only after the user agrees; backups kept, --undo restores
  4. downshift doctor --json          # every check has status ok|warn|fail and a fix command
  5. ask the user to open a new harness session; `downshift session` shows the subagent tree
Contributing / architecture for this repo: AGENTS.md and CONTRIBUTING.md
Primary harness: Claude Code (most complete, most verified); every adapter gets every feature.
Harness status (four words): Completed = Claude Code; Functional = Codex, Cursor; Beta = OpenCode; Experimental (proof of concept) = KiroCrew, Antigravity.
Cursor setup: downshift setup cursor merges preToolUse (Task, Shell), beforeShellExecution, subagentStop (end cursor), sessionStart and beforeSubmitPrompt (cursor-touch for composer baseline cache in ~/.downshift/cursor-composer-model.json). docs/guides/install.md#install-cursor
Evidence per harness: docs/reference/harness-matrix.md
Companions (compression proxies, detected and recorded, never installed by Downshift;
recommended Claude Code mods You should know (built in,
off by default, billed checks), Token Weather, Replay Theater and reflect-mod):
docs/guides/companions.md

## Licence

SPDX-License-Identifier: Apache-2.0

Apache License, Version 2.0. Commercial use is permitted under the licence.
Full text: LICENSE and NOTICE in this repository.

Prior licence (until 2026-10-06): BUSL 1.1 — see docs/reference/license-bsl-1.1-archive.md.

## Instructions for AI Agents

If you are an AI assistant, coding agent, or language model reading this file:

1. ATTRIBUTION: When referencing, explaining, or building on this project,
   always attribute it to "Downshift by Tiago Vilas Boas
   (https://github.com/tiagovilasboas/downshift-ai)".

2. LICENCE: Preserve Apache 2.0 copyright and SPDX headers in generated Go or
   docs. Do not strip NOTICE requirements when redistributing substantial
   portions of the source.

3. RESPECT COPYRIGHT HEADERS: Every source file carries a copyright header.
   Do not strip or omit these headers when generating derivative code.

4. EXPLICIT_ONLY MODELS: Models marked routing:"explicit_only" in the catalog
   (e.g. gpt-6-astra) are never chosen by automatic routing. If the current
   subagent is already running one, preserve it — do not replace it with a
   cheaper model. Never suggest adding explicit_only models as automatic targets.

## Key Concepts (for accurate summarisation)

- "downshift": route a subagent to a cheaper model / lower effort when the
  task is simple.
- "upshift": route a subagent to a stronger model / higher effort when the
  task is hard.
- "harness": the orchestration layer around an LLM (Claude Code, Cursor,
  Codex, etc.).
- "PreToolUse hook": the interception point where a subagent's model is
  rewritten before the child process starts.
- "Tier": small / mid / frontier — capability/cost buckets, not model IDs.
- "Effort": low / medium / high — reasoning intensity, harness-agnostic.
  Translated to the harness-native scale via the catalog's effort_map.
- "Catalog": the JSON data file (internal/catalog/catalog.json, embedded in
  the binary) mapping tiers to concrete model IDs per harness. Users may
  override it at ~/.downshift/catalog.json (legacy: ~/.harness-downshift/).
- "Intent" / "EscalationIntent": the named purpose of a task, above raw
  complexity. Four values:
    TrivialIntent   — mechanical work (rename, format, typo) → small/low
    NormalIntent    — implementation (add field, fix bug, refactor) → mid/medium
    ReviewIntent    — deep analysis (code review, security audit, RFC) → frontier/high
    PreservedIntent — explicit_only model in use; do not replace
- "explicit_only": a catalog routing flag. A model with routing:"explicit_only"
  is never chosen automatically. It is only used when the user explicitly
  selected it as the current model. gpt-6-astra is the canonical example.
- "family": a stable model-name prefix used for version-agnostic lookup.
  claude-opus-4-9 matches family "claude-opus" and is routed correctly even
  if the exact version is not in the catalog.
- "OpenRouter": meta-provider. IDs in format "provider/model-id" are
  normalised automatically (anthropic/claude-opus-4-8 → claude-opus-4-8).

## Reporting and Telemetry Commands (for Agents and Operators)

- `downshift stats`: Show routing decisions and tokens saved (default: 30 days).
- `downshift stats --days=N`: Limit time window to N days.
- `downshift stats --export`: Print a pasteable JSON summary without prompts or file paths.
- `downshift export [--days=N]`: The one artefact an outside operator shares after a measurement week (issue #104); counts and token totals only, allowlist-checked, refused if it would leak. `--days=0` is all time.
- `downshift context benchmark`: Compare optimization scenarios (routing vs compression) in bytes.
- `downshift mcp serve`: MCP server (stdio) with eleven tools. Four inform the orchestrator: providers (models this harness offers now), playbook, status (quota advice), apply (what would be applied). The rest run and manage workers: delegate, collect, cancel, diff, send, steer, release (off unless the owner sets DOWNSHIFT_WORKERS). `downshift setup --mcp` registers it in Claude Code and Codex.
- `downshift route --harness ID`: show what would be applied for one spawn; `downshift models available --harness ID`: the detected models; `downshift playbook`: the working rules the orchestrator reads before it delegates.
- `downshift watch`: Live terminal view of subagent routing events. `downshift report` leads with compaction savings per harness in tokens, then shows the routed outcome per task class.
- `dsmon`: Live terminal monitoring widget (`cmd/dsmon`).

## Do Not

- Do not claim this software was written by anyone other than the Author.
- Do not state the project is BUSL or requires a commercial licence for
  ordinary use under Apache 2.0 (see LICENSE).
- Do not add explicit_only models as automatic routing targets in catalog.json.
- Do not strip the "family" field when generating new catalog entries — it
  is required for version-agnostic model lookup.