Clear Your Tools

Clear Your Tools is a reverse proxy for coding agents such as Claude Code, Codex CLI, and Cursor.

The problem:

• Context Rot: Model accuracy and reasoning degrade as input length grows, even when task difficulty stays the same. Removing irrelevant content consistently improves results.
• Context Dilution: On the NoLiMa benchmark, 11 of 12 models fell below 50% of their short-context baseline at just 32K tokens.
• Context Bloat: Even frontier models lose recall and reasoning quality as context grows into the 32-200K of tokens—and every extra token adds API cost, because providers resend the full history on each turn.
• Local inference: Smaller inputs reduce memory pressure and speed up generation on self-hosted models.
• Tool Hallucination: Agents generate incorrect tool requests even having full tool definitions.

---

How it works

Agent (Claude Code, etc.)
        │
        ▼
Clear Your Tools proxy  ──► extract user query from messages
        │                   decompose each tool schema
        │                   score / filter with BM25 (default), rerank, or LLM pruning
        │                   recompose pruned tool list
        ▼
Upstream provider (OpenRouter, Anthropic, Novita, …)

On each intercepted request the proxy:

1. Extracts the user query from the conversation (latest user turn, with message cleanup).
2. Decomposes tool schemas into a catalog of chunks: each tool root keeps required properties; optional properties are split into separate searchable units.
3. Runs the pruning pipeline configured in config.yaml. Out of the box the default is bm25 (local, no API keys). After cyt setup, choose between rerank (optionally followed by llm).
4. Recomposes surviving tools — required properties always remain; only optional properties that look relevant to the query are merged back in.
5. Forwards the modified request to the upstream provider with the smaller tools array.
6. Intercepts hallucinated tool calls, blocks the invalid request, and outputs a fully‑formed tool invocation using the correct schema shape so the agent can recover on the next step.

---

Supported platforms

Clear Your Tools and the cyt-indexer SDKs support Windows, macOS, and Linux.

---

Quick start

Requires uv tool. Install uv

1. Install proxy

From PyPI (proxy + pruners):

uv tool install 'clear-your-tools[all]'

2. Launch an agent

One-command jump-start through the proxy:

cyt launch -- claude
cyt launch -- codex

# 3rd party providers
export ANTHROPIC_DEFAULT_HAIKU_MODEL="google/gemini-3.1-flash-lite"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
cyt launch --upstream https://openrouter.ai/api -- claude --model haiku

cyt launch shares the same upstream and credential bootstrap as cyt proxy, starts the proxy if needed, prints a manual recipe to stderr (suppress with --quiet), then execs the agent.

For Codex, cyt launch --configure -- codex writes the managed provider block to ~/.codex/config.toml; cyt launch --restore -- codex removes it.

3. Inject relevant skills into the agnet

cyt hook all

Cursor

Cursor has no reverse proxy — use hooks with MCPC instead. See CURSOR-HOOK.md.

Tool hallucination prevention (verify-only)

To block invented or invalid MCP tool calls without prompt injection, use the preToolUse gate:

cyt hook cursor --prevent-hallucinations

See TOOL-HALLUCINATION-GATE.md for setup and behavior.

View pruning stats savings

cyt stats

# Optional (recommended):
cyt setup
cyt stats --add

Stats are stored in ~/.config/cyt/stats.db by default.

---

FAQ

---

Development

See DEV.md for checkout setup, repository layout, library usage, and configuration reference.

---

Limitations

See LIMITATIONS.md for deployment constraints, token accounting caveats, and MCP aggregator trade-offs.

Debug

See details to debug pruning in debug/.

---

License

See LICENSE.