kitty-bridge 1.11.0

Use your favorite coding agent with any LLM provider.

Claude Code with MiniMax. Codex with GLM. Gemini CLI with OpenRouter. One command.

Why Kitty Bridge?

Frontier models are expensive. Claude Opus 4.7 costs $25 per 1M output tokens. GPT-5.5 runs $30–45 per 1M output tokens. A single long coding session can burn through dollars in minutes. And if you hit your subscription rate limits mid-task, you're stuck waiting.

Meanwhile, there are coding plans from providers like Z.AI, Novita, Fireworks, MiniMax, and others that deliver capable coding models at a fraction of the cost — often 90% cheaper than the flagship models.

Kitty Bridge gives you three ways to save:

✅ Switch to a cheaper provider — Use Claude Code with MiniMax, Codex with GLM, or Gemini CLI with OpenRouter. One command, instant savings.

✅ Use your existing subscriptions — Already paying for ChatGPT Plus or Pro? Use it through Kitty instead of buying API credits separately.

✅ Mix models with balanced profiles — Combine a powerful model like GPT-5.5 with a smaller, cheaper one in a single session. Kitty randomly distributes requests across both, giving you the reasoning power of a frontier model at roughly 20–25% of the cost.

Agent (Claude Code / Codex / Gemini / Kilo) → Kitty Bridge → any LLM provider

Kitty sits between your coding agent and the upstream provider, translating each agent's native protocol in real time. Your agent keeps its workflow — you choose the model and the price.

Kitty is also intentionally minimal:

✅ Local — Kitty runs on your machine. It does not send your prompts, code, or files to any third-party service beyond the backend LLM provider you explicitly configure.

✅ Just a bridge — Kitty only proxies and translates traffic between the coding agent and the backend model API. It does not get filesystem access, shell access, or any other extra capabilities.

✅ No AI inside Kitty — Kitty does not use an LLM, embeddings, or any other AI system internally. It is a deterministic local bridge with advanced routing, balancing, and compatibility features.

In short: Kitty is a minimal, local, and safe bridge with advanced functionality.

If you like what we're building, please ⭐ star this repo – it's a huge motivation for us to keep going!

Before You Start

You need two things to use Kitty:

1. A coding agent installed on your machine — Claude Code, Codex CLI, Gemini CLI, or Kilo Code
2. An account with an LLM provider — either an API key (pay per token) or a subscription/coding plan

API key vs. subscription? Some providers offer regular API access where you pay per token. Others offer subscription plans (e.g. your ChatGPT Plus subscription) that include usage quota. Kitty supports both — the setup wizard will guide you based on which provider you pick.

Quick Start

1. Install

pip install kitty-bridge

Requires Python 3.10+.

Supported platforms. Linux, Windows and macOS. Every change is tested on all three before it can be merged or released: Linux on Python 3.10–3.13, Windows and macOS on Python 3.12. What that covers is the full unit and contract suite plus type checking on each platform — not an end-to-end run against a live provider, which is exercised on Linux only.

2. Set up a profile

kitty setup

An interactive wizard walks you through picking a provider, a model, and entering your API key. Takes 30 seconds.

New to this? The easiest way to start is with your existing ChatGPT Plus or Pro subscription — select "OpenAI ChatGPT Plan" during setup. No API key needed; Kitty authenticates through your browser. Alternatively, sign up at OpenRouter for a free API key that works with many models.

3. Launch your agent

kitty claude      # Claude Code → your provider
kitty codex       # Codex CLI → your provider
kitty gemini      # Gemini CLI → your provider
kitty kilo        # Kilo Code → your provider

That's it. Your coding agent now talks to the LLM you chose — not the one it was built for.

Example: Use GLM with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: openai
  ? Model: openai/gpt-5.4-pro
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

Example: Use Gemma 4 31B with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: Google AI Studio
  ? Model: gemma-4-31b-it
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

Example: Use your ChatGPT subscription with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: openai_subscription
  ? Model: gpt-5.4

  Opening browser for OpenAI authentication...

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

No API key required — kitty authenticates with your ChatGPT Plus or Pro account through a browser-based OAuth flow. Each profile gets its own independent session.

Example: Use MiMo V2 Pro with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: Xiaomi MiMo
  ? Model: mimo-v2-pro
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

Balanced Profiles

A balanced profile combines multiple providers into one. Each request is sent to a randomly chosen healthy provider. If one provider goes down, the others pick up the slack automatically. Members can also be marked as backup, so they only take traffic once the others are exhausted.

Why use it:

• Cost savings — spread requests across cheaper providers
• Rate limit resilience — never hit a single provider's limit
• Fault tolerance — if one provider is down, the others keep working

How to create one:

kitty profile
# → "Create balancing profile" → select 2+ member profiles

Example: Combine MiniMax, Novita, and Z.AI into one balanced profile called my-pool, then use it with any agent:

kitty my-pool claude
kitty my-pool codex

When you run this, each request goes to a random healthy member. If MiniMax returns an error, kitty silently retries on Novita or Z.AI — your agent never sees the failure.

Backup members

Sometimes you don't want a member to carry its share of the traffic — you want it held in reserve. Mark a profile as a backup and it is only used when every non-backup member of the pool is unavailable.

The typical setup is a set of subscription coding plans plus one pay-per-token API key:

kitty profile
# → "Edit profile" → pick your API-key profile → "Backup" → yes

Now all three plans share the traffic normally. When a plan hits its usage limit — or fails for any other reason — kitty puts it in a cooldown. Once every plan is in cooldown, requests move to the API key instead of failing. As soon as a plan's cooldown expires it is picked up again on the next request, so you drift back onto your subscriptions automatically without restarting anything.

Anything that makes a member unavailable counts: rate limits, exhausted quotas, expired credentials, upstream 5xx, and connection failures.

A dropped connection is given the benefit of the doubt first. For up to 30 seconds kitty retries the same member instead of cooling it down, so a brief network interruption between kitty and a provider costs a short pause rather than five minutes of that plan. Only a connection that keeps failing past that window counts as a failure. The same applies in the other direction: if your agent disconnects mid-answer — you close the terminal, hit Ctrl+C, or your network blips — that is charged to the agent, never to the provider, so the next request still finds every plan healthy.

One caveat: a member that cannot handle streaming is skipped for streaming requests regardless of tier, so a streaming request can reach a backup member while a non-streaming primary is still healthy. This only affects providers without streaming support, and matches how balanced profiles already behaved.

You are asked about this when creating a profile (the default is no), and you can change it any time via kitty profile → Edit profile → Backup. The profile table shows a Backup column so you can see the split at a glance. The flag only matters inside a balanced profile — launching a backup profile directly works exactly as normal.

If every member of a pool is marked backup, the pool behaves like an ordinary balanced profile.

Static Egress

By default each machine running kitty talks to the LLM provider from its own IP, so ten workers look like ten different clients. A static egress gateway puts them all behind one address: point every kitty install at the same HTTP proxy, and every provider sees a single, stable source IP.

VM 1  kitty claude ─┐
VM 2  kitty claude ─┼──► egress gateway ──► 185.123.45.67 ──► LLM provider
VM 3  kitty codex  ─┘

You do not need a cloud NAT gateway. Any authenticated HTTP proxy with a dedicated static IPv4 works, including the $1–3/month dedicated datacenter proxies sold by providers like IPRoyal, Proxy-Cheap and Proxy-Seller. Avoid rotating or residential proxies — you want exactly one address that never changes.

Set it up:

kitty egress
# → "Configure gateway" → address, username, password → test

The setup ends by fetching your public IP through the proxy and showing it, so you can confirm the address providers will actually see before relying on it:

$ kitty egress test
┌──────────────┬────────────────────────────────┐
│ Proxy        │ http://proxy.iproyal.com:12323 │
│ Username     │ myuser                         │
│ Password     │ ****                           │
│ Connectivity │ OK                             │
│ Public IP    │ 185.123.45.67                  │
│ Latency      │ 41 ms                          │
└──────────────┴────────────────────────────────┘

Repeat on each machine, and they all share that IP. kitty doctor reports the gateway too.

For scripted or containerised installs there are two non-interactive overrides, taking precedence over the stored gateway:

export KITTY_EGRESS_PROXY="http://user:pass@proxy.iproyal.com:12323"
kitty claude

# or per invocation
kitty claude --egress-proxy http://user:pass@proxy.iproyal.com:12323

Things worth knowing:

• Your prompts and API keys stay private from the proxy. kitty uses HTTP CONNECT, so TLS runs end-to-end between kitty and the provider. The gateway only moves encrypted bytes — it never sees your API key or your conversations.
• Local endpoints are never tunnelled. Loopback and private addresses — a local Ollama on localhost:11434, a custom provider on your LAN, cloud instance metadata — connect directly, because a rented proxy cannot reach your own network. That traffic never leaves the machine, so it is not a leak.
• It fails closed. If a profile uses a transport that cannot honour the proxy, kitty refuses to start and tells you which profile, rather than quietly connecting from the machine's own IP. AWS Bedrock in SSO mode is the current example: botocore resolves those credentials outside the proxied client.
• Your password is not stored in a config file. It goes to the same credential store as your API keys, referenced by an opaque id, and is masked wherever kitty prints the gateway.
• Use a CONNECT proxy, not a TLS-terminating one. A proxy that intercepts TLS breaks the OpenAI subscription provider, which relies on a browser TLS fingerprint. Ordinary datacenter proxies are fine.

To stop using a gateway, run kitty egress → "Remove gateway".

Bridge Mode

Bridge mode starts a standalone OpenAI-compatible API server on your machine. Use it when you want to connect tools that speak the OpenAI API — IDEs, custom scripts, anything that accepts a base URL.

kitty bridge          # use default profile
kitty my-profile bridge   # use a specific profile

Point your tool at http://localhost:<port> and it just works.

Available endpoints:

Background bridges: kitty bridge start, stop, restart, and status manage a bridge running in the background, tracked in bridge_state.json.

If status reports "Running under another user account", a bridge is serving at the recorded address but was started by a different user (via sudo, a service account, or another session). kitty will not stop or restart it, and will not start a second one beside it — signalling a process it does not own is unsafe, because the operating system may have recycled that process ID onto something unrelated. Stop it from the account that started it, or from an administrator shell. If you are sure that process is not a kitty bridge, delete bridge_state.json — kitty prints its full path in the message.

Knowing which model actually served you

kitty replaces the model name your agent asks for with the one its profile configures — that is the point of the product. The agent's own cost and error records therefore name the alias, not the model that ran. Three surfaces tell you the truth.

Per response. Every proxied response carries:

These name the backend selected when the response headers were sent. A stream never switches backend once content has reached the client, so on /v1/messages, whose headers go out with the first content, they name the backend that produced the response. The other endpoints send headers before the first upstream attempt, so a request that failed over before any content can name a backend that produced nothing. /stats is authoritative for the session.

Live. GET /stats returns JSON for the running bridge: per-backend request counts, the real models served with their token totals, how many times a request switched backend (failovers), and whether the pool was ever exhausted (all_backends_unhealthy). Like /healthz, it is readable without credentials unless a keys file is configured — and kitty claude deliberately runs without one.

malformed_tool_use counts responses where an upstream returned 200 OK with a tool_use whose input contradicts the schema the client declared for that tool — the shape a client-side validator then rejects. It is reported per backend and as a session total, so a pool member returning well-formed-looking garbage is visible without re-running under --debug. It is a diagnostic only: it never marks a backend unhealthy or triggers failover. Run with --debug and grep 'tool_use audit:' for the offending payloads.

After the run. --session-summary PATH (or KITTY_SESSION_SUMMARY) writes the same document to a file when the bridge shuts down — a small artifact CI can upload, instead of a multi-megabyte debug log:

kitty --session-summary "$RUNNER_TEMP/kitty-session.json" claude -p "review this diff"

The summary is written on graceful shutdown. If the bridge is killed (job cancelled, step timeout, SIGKILL) there is no file, so poll /stats before teardown if you need a record from those runs.

Two things the numbers do not mean: attempts counts backend selections, so it reads lower than the upstream POST count in the debug log (retries against the same backend are not re-selections); and in single-profile mode failovers is always 0 because there is nowhere to fail over to — check mode first.

Supported Agents

Supported Providers

Regular API Key — sign up, get an API key, pay per token:

Coding Plans / Subscriptions — use your existing subscription or coding plan, no API key needed:

Local LLMs:

Generic:

Custom OpenAI-Compatible Provider

Use the custom_openai provider to connect to any service that exposes an OpenAI-compatible Chat Completions API. This works with DeepSeek, Together AI, Groq, vLLM, LM Studio, and any other service that accepts POST /v1/chat/completions with Bearer auth and SSE streaming.

The base URL ends at the API root — Kitty appends /chat/completions itself. Give it https://api.mistral.ai/v1, not https://api.mistral.ai/v1/chat/completions.

Pasting the full endpoint works anyway: Kitty drops the duplicate path instead of failing. That holds for an endpoint carrying a query string too, and the query is kept and sent with every request — so Azure OpenAI works through this provider with the endpoint Microsoft's own documentation shows, pasted verbatim:

https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-02-01

$ kitty setup
  ? Provider: Custom OpenAI-Compatible
  ? API base URL: https://api.deepseek.com/v1
  ? Model: deepseek-chat
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched

Common endpoints:

Both HTTPS and HTTP (local) endpoints are supported.

Commands

Updating

pip install --upgrade kitty-bridge

Technical Details

How it works

Kitty sits between your coding agent and the upstream LLM provider. The high-level flow is the same as shown above:

Agent (Claude Code / Codex / Gemini / Kilo) → kitty bridge → upstream provider

When you run kitty claude:

1. kitty reads your profile (provider, model, API key)
2. Starts a local HTTP bridge on a random port
3. Configures the agent to send requests to the bridge instead of its default endpoint
4. The bridge translates each request to the provider's format and forwards it
5. Responses are translated back to the agent's native format
6. When the agent exits, kitty restores the agent's config files

Profiles

A profile binds a provider, model, and API key together. Stored in ~/.config/kitty/profiles.json.

kitty setup        # create a profile interactively
kitty profile      # manage existing profiles
kitty my-profile claude  # use a specific profile

Profile names must be 1-32 characters, lowercase letters, numbers, dashes, or underscores. Reserved words like setup, claude, codex, gemini, kilo, profile, bridge cannot be used as profile names.

Things to know about profile management:

• Deleting a regular profile automatically removes it from all balancing profiles. If a balancing profile drops below 2 members, it is deleted entirely.
• Deleting the default profile automatically promotes the first remaining profile as the new default.
• Editing a profile's API key creates a new credential entry. Other profiles sharing the old key are not affected.
• The backup flag lives on the profile, not on the membership — a profile that belongs to two balanced profiles is a reserve member in both. See Backup members.

Pre-flight validation

Before launching, kitty checks that your profile configuration is valid and that your credentials can be resolved. If something is wrong, you get a clear error immediately — not a cryptic failure inside the agent.

kitty --no-validate my-profile claude  # skip validation (e.g. air-gapped/offline environments)

Logging

kitty has two independent logging streams, each with its own flag and optional custom path.

Token usage logs — records prompt/completion token counts per request:

# Default location: ~/.cache/kitty/usage.log
kitty --logging claude

# Custom location
kitty --log-file /tmp/my-usage.log claude

Debug logs — verbose tracing of requests, responses, and protocol translation:

# Default location: ~/.cache/kitty/bridge.log
kitty --debug claude

# Custom location
kitty --debug-file /tmp/my-debug.log claude

Both flags work in launch mode and bridge mode:

kitty --debug --log-file /tmp/usage.log my-profile bridge
kitty --debug-file /tmp/debug.log --logging my-profile codex

Cleanup

kitty restores agent config files after the agent exits. Three layers of cleanup:

1. Normal exit — finally block
2. Crash / SIGTERM — atexit handler
3. SIGKILL / kernel OOM — run kitty cleanup manually

If your agent shows connection errors after a crash, run kitty cleanup to restore its configuration files.

Troubleshooting

Run kitty doctor to check your installation. It verifies that:

• Agent binaries are installed and discoverable
• A default profile exists
• All profile credentials can be resolved

For deeper issues, use the logging flags:

kitty --debug my-profile claude          # trace requests/responses to ~/.cache/kitty/bridge.log
kitty --logging my-profile claude        # log token usage to ~/.cache/kitty/usage.log
kitty --debug --log-file /tmp/usage.log my-profile claude  # both, with custom paths

Project structure

src/kitty/
├── bridge/          # HTTP bridge + protocol translation
├── cli/             # Command-line interface
├── credentials/     # API key storage
├── launchers/       # Agent-specific adapters
├── profiles/        # Profile management
├── providers/       # Upstream provider adapters
├── tui/             # Terminal UI components
└── types.py         # Shared types

FAQ

"API Error: Unable to connect to API (ConnectionRefused)"

The agent is trying to connect to a bridge that isn't running. Usually caused by a stale config from a previous crashed session:

kitty cleanup

"API Error: 401" or "token expired or incorrect"

Your API key has expired or been revoked. Run setup again:

kitty setup

"Prompt exceeds max length" (Z.AI error 1261)

The conversation has grown beyond the model's context window. Use /clear in the agent to reset.

"Kitty Bridge could not reduce this conversation to something the model can accept"

Compaction ran and found nothing left to send, so the bridge refused the request instead of forwarding it. Nothing was sent to the provider.

Almost always this means the conversation contains a tool result whose matching tool call was lost — usually after an empty or truncated response from the provider left a half-recorded turn behind. The conversation cannot be repaired, so a larger context window does not help:

/clear

If it recurs immediately on a fresh conversation, the system prompt and tool definitions are likely too large for the model you have configured — trim CLAUDE.md or the number of MCP servers, or switch to a model with a larger context window.

The response is a normal 400 in your agent's own error format, carrying "reason": "compaction_failed" so it is distinguishable in logs from the ordinary "request too large" rejection.

"Kitty Bridge received an empty reply from the upstream provider on every attempt"

Applies to providers kitty talks to in Anthropic's own format: anthropic, custom_anthropic, zai_coding, minimax_token, and opencode_go for the models it serves on Anthropic's format. Kitty holds back the start of each streamed reply until it carries text or a tool call, so a reply with nothing in it — or only thinking, up to 10 MiB of it — can be retried before your agent sees it. This error means every attempt kitty made came back empty. Nothing reached the agent, so simply resend; if it persists, the provider or model is misbehaving.

The response is a 502 carrying "reason": "empty_response". One visible cost of the hold: on reasoning models the agent shows its spinner, not live thinking, until the first text or tool call arrives.

"Kitty Bridge received a reply from the upstream provider that stopped (max_tokens) before producing any content"

Same providers. The model used its whole output budget — typically all of it on thinking — or filled its context window (model_context_window_exceeded) before writing anything. A retry cannot fix that, so kitty fails the request at once with a 400 carrying "reason": "max_tokens_before_content" (or "model_context_window_exceeded_before_content"). Raise the output token limit, lower the thinking effort, or /clear a very long conversation.

Mouse wheel scrolls through previous prompts instead of the conversation (Claude Code)

The wheel steps backwards through your prompt history while the transcript stays put. This is Claude Code's renderer setting, not the bridge. Kitty prints its startup banner and then hands the terminal straight to the agent: it sets no terminal modes — no mouse tracking, no alternate screen — and writes nothing to your terminal while the agent runs.

Claude Code's classic renderer keeps the conversation in your terminal's own scrollback and does not request mouse events. Many terminals then translate the wheel into Up/Down arrow keys, which the prompt box reads as history navigation. The fullscreen renderer requests mouse events and scrolls the conversation itself. Reported from PowerShell on Windows over SSH to a Linux host.

Switch renderer from inside the session:

/tui fullscreen

Claude Code saves the choice and relaunches with your conversation intact, so it applies to later sessions too. Run /tui default to switch back, or /tui with no argument to print which renderer is active. In fullscreen, PgUp / PgDn scroll and Ctrl+End jumps back to the latest message.

One trade-off: fullscreen captures the mouse, so your terminal's own copy-on-select stops working. Hold Shift while dragging (Option in iTerm2, Fn in Terminal.app) when you want a native selection.

Can my Claude Code session survive an SSH disconnect?

Yes, with Claude Code's own tmux flag:

kitty claude -w mike --tmux=classic

Kitty sees --tmux and starts a tmux session running itself, so kitty, its bridge and Claude Code all keep running when the SSH connection drops. Without this, only Claude Code would survive, talking to a bridge that died with your terminal. Reconnect with the command kitty prints before it starts:

tmux attach -t <repo>_worktree-mike

Running the same command again reattaches too. Notes:

• It needs tmux 3.2 or newer and a worktree flag (-w/--worktree), as Claude Code's --tmux does.
• Already inside tmux, kitty just removes --tmux and runs in the current pane.
• If a session with that name exists but kitty did not start it, kitty stops and tells you how to attach to it or remove it.
• If kitty fails inside the session, the pane stays open with the error until you press Enter.
• The command's exit code is tmux's, not kitty's: a launch that fails inside the session still exits 0 once the pane closes. Scripts should not branch on it; read the pane instead.
• Kitty runs as it always did, with no tmux session and no protection, when there is no terminal (a script or CI job), on Windows, or outside a git repository: --tmux reaches Claude Code unchanged.
• On macOS with iTerm2, --tmux under kitty gives a plain tmux session rather than iTerm2's native panes.

Can I use kitty with Cursor, Windsurf, or other IDEs?

Yes, but with caveats. Cursor uses a proprietary protocol that Kitty cannot integrate with automatically. However, you can start Kitty in bridge mode and point your IDE's "OpenAI base URL" setting at the bridge endpoint:

kitty bridge
# Then configure your IDE to use http://localhost:<port>/v1/chat/completions

This is a manual, best-effort configuration. Some IDE-specific features may not work.

Can I use my Anthropic (Claude Pro/Team) subscription with Kitty?

No. Anthropic's Terms of Service prohibit accessing their subscription APIs from third-party software. You can use Kitty with Anthropic's API directly — sign up at console.anthropic.com, create an API key, and use the anthropic provider. You will be billed per token, not through your subscription.

What is the difference between "OpenAI" and "OpenAI ChatGPT Plan"?

• OpenAI — standard developer API. You create an API key at platform.openai.com and pay per token.
• OpenAI ChatGPT Plan — uses your existing ChatGPT Plus or Pro subscription through a browser-based OAuth login. No API key needed; you use your subscription's included quota.

What is a "coding plan"?

Some providers offer subscription plans specifically designed for coding agents. Instead of a traditional API key with per-token billing, these plans typically authenticate via OAuth or a dedicated session and include usage quotas. Examples include Z.AI Coding Plan, Fireworks FirePass, Novita AI, and Kimi Code.

Can I run a local model?

Yes. Install Ollama, pull a model, then create a profile with provider ollama:

kitty setup
# Provider: ollama
# Base URL: http://localhost:11434/v1
# Model: llama3

What is the difference between Ollama and Ollama Cloud?

• Ollama — connects to a local or remote Ollama instance using its OpenAI-compatible endpoint. No API key needed for local deployments.
• Ollama Cloud — connects to ollama.com cloud models using an API key. No local GPU required. Some models require a paid subscription.

Does Kitty record my prompts or send data anywhere?

No. Kitty runs entirely on your machine. All prompts and responses pass directly between your coding agent and the upstream provider. Kitty does not send data to third parties, store conversations, or collect telemetry.

Something is broken. How do I debug it?

1. Run kitty doctor to check your installation and credentials
2. Run kitty cleanup if you see connection errors after a crash
3. Use kitty --debug <profile> <agent> to trace all requests and responses to ~/.cache/kitty/bridge.log

Development

pip install -e ".[dev]"
pytest
ruff check .
mypy src/kitty

The suite also needs openssl on your PATH — a few tests generate a throwaway TLS certificate with it. A missing openssl fails those tests rather than skipping them, deliberately: a test that removes itself when a resource is absent lets CI report success without having run it. That is a different treatment from the deselected categories described below, and the difference is the granularity: a resource needed by a whole layer is excluded by selection, while a resource needed by a handful of tests inside a layer CI gates on has to be present.

Running a subset of the tests

Every test carries exactly one layer marker, so you can ask for the part you need:

pytest -m l1          # component and property tests -- the fast majority
pytest -m l2          # contract tests: two artifacts that must agree
pytest -m "l1 or l2"  # what CI gates every pull request on
pytest -m ""          # everything, including the categories excluded below

A bare pytest runs everything except the categories that need a resource your machine may not have -- a pinned agent binary, live provider credentials, a load rig. Those are excluded by selection, not skipped, so the run tells you they were deselected rather than pretending to have considered them. To run them, name them:

pytest -m agent_live  # launches real agent CLIs against live credentials

The marker is assigned automatically from the file's path; a test only declares its own layer where that default is wrong. .system_design/TEST_SUITE.md §8 has the full matrix.

Exempting a known-failing assertion

A guard sometimes covers a class of check broader than the one defect it happens to expose, so it would land red on a single assertion. tests/exemptions.py exempts that one assertion and nothing else:

from exemptions import ratchet

with ratchet("tr-1c-header-subset"):
    assert bridge_headers <= native_headers

Every other assertion in the test, and all of its setup, still gates. A broken fixture inside the block still fails. And when the assertion starts passing, the run fails and tells you to delete the row -- so an exemption cannot outlive the defect it describes. Each row names the assertion, the condition it is expected to fail under, and its Jira key; the registry is one file and is meant to trend towards empty. .system_design/TEST_SUITE.md §8.3 has the reasoning.

License

MIT