Skip to content
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
60 changes: 60 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 27 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A local-first, air-gapped context optimization engine that eliminates token waste in LLM interactions while maintaining zero network footprint. Built in Rust for restrictive firewall and DLP environments.

> **🚀 Version 0.1.6** — Zero-touch workflow (`provide_code_context`), SQLite persistence layer, Angular HTML parsing (XHTML self-closing + inline template), IR-level delta compression, text-level delta transport, cross-file dependency graph, modern Angular 17–21 syntax support, Anthropic prompt-cache proxy, and 1,035 tests all passing.
> **🚀 Version 0.1.7** — Zero-touch workflow (`provide_code_context`), SQLite persistence layer, Angular HTML parsing (XHTML self-closing + inline template), IR-level delta compression, text-level delta transport, cross-file dependency graph, modern Angular 17–21 syntax support, multi-platform proxy (Anthropic/OpenAI/Generic), **26 built-in tool output filters**, secret scrubbing, and 243 proxy tests all passing.

---

Expand Down Expand Up @@ -126,16 +126,36 @@ For Angular projects, Clean-CTX automatically detects framework decorators and e

**Non-Angular files pay zero overhead** — no markers, no extra parsing, no newlines.

### Anthropic Prompt-Cache Proxy
### Multi-Platform Proxy

Clean-CTX ships with an optional **local HTTP proxy** that sits between your LLM client and the Anthropic API, automatically injecting `cache_control` breakpoints to achieve ~90% API cost savings on cached turns:
Clean-CTX ships with an optional **local HTTP proxy** that sits between your LLM client and any AI API (Anthropic, OpenAI, DeepSeek, etc.), automatically injecting `cache_control` breakpoints to achieve ~90% API cost savings on cached turns:

```bash
AUTO_CACHE=1 cargo run -p clean-ctx-proxy
AUTO_CACHE=1 TOOL_FILTERS=1 SCRUB_SECRETS=1 cargo run -p clean-ctx-proxy
```

Works with Cline, Cursor, Aider, Continue.dev, and GitHub Copilot (BYOK). See [`docs/PROXY.md`](docs/PROXY.md) for full documentation.

### Tool Output Filtering

The proxy includes **26 built-in TOML filters** that compress verbose tool output by 70–90%:

| Category | Filters |
|----------|---------|
| **Build** | cargo, make, mvn, node-build, dotnet-build, go |
| **Lint** | eslint, ruff, biome, mypy, pyright, golangci-lint, shellcheck, hadolint, yamllint |
| **Test** | pytest, dotnet-test, ng |
| **Package Mgr** | npm, pip, apt, brew |
| **DevOps** | docker, docker-logs, kubectl |
| **Git** | gh, git-diff, pre-commit |
| **System** | curl, ssh, systemctl, tsc |

Enable with `TOOL_FILTERS=1`. Filters auto-detect the command from tool input and apply program-specific compression (e.g., collapsing a successful `cargo build` to `"cargo: ok"`). Custom filters can be added as TOML files in `.clean-ctx/filters/`.

### Secret Scrubbing

The proxy detects and redacts secrets (AWS keys, GitHub tokens, JWTs, PEM keys, etc.) in tool results before they reach the LLM. Enable with `SCRUB_SECRETS=1`.

### Security

- **Zero network transport** — stdio-only via MCP, no HTTP/WS/RPC servers
Expand Down Expand Up @@ -458,9 +478,10 @@ The binary is output as `clean-ctx.exe` (Windows) or `clean-ctx` (Linux/Mac).
|--------|-------|
| Build | ✅ `cargo check` clean |
| Linting | ✅ `cargo clippy --all-targets -- -D warnings` — 0 warnings |
| Tests | ✅ 1,035 passing (960+ unit + 70 integration + 5 E2E + proxy tests) |
| Tests | ✅ 243 proxy tests passing (112 unit + 18 regression + 1 integration) + 1,035 core tests |
| Audit | ✅ FAANG-level audit — all 41 findings resolved |
| Proxy | ✅ Anthropic prompt-cache proxy — see [`docs/PROXY.md`](docs/PROXY.md) |
| Proxy | ✅ Multi-platform proxy (Anthropic/OpenAI/Generic) — see [`docs/PROXY.md`](docs/PROXY.md) |
| Filters | ✅ 26 built-in TOML filters — cargo, npm, eslint, docker, go, and more |
| Largest file | ~170 lines (down from 913) |
| Unsafe code | 0 blocks |
| Meta-Layer | ✅ Phases 1–3 complete (decorators, bundling, graph) |
Expand Down
67 changes: 67 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,73 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
## [0.1.7] — Unreleased

### Added

#### Multi-Platform Proxy Support
- **Platform-agnostic proxy**: The proxy now supports any AI provider (Anthropic, OpenAI, DeepSeek, etc.) via the `PlatformAdapter` trait.
- `proxy/src/platform/mod.rs` — `PlatformAdapter` trait with `is_tool_result()`, `extract_tool_result()`, `intercept_path()`, `platform_headers()`, `is_platform_model()`, `platform_name()` methods
- `proxy/src/platform/anthropic.rs` — Anthropic API adapter (`type: "tool_result"` blocks, `cache_control`, `anthropic-beta` header)
- `proxy/src/platform/openai.rs` — OpenAI API adapter (`role: "tool"` messages, `tool_call_id`)
- `proxy/src/platform/generic.rs` — Generic fallback adapter (heuristic detection, multiple content field locations)
- `platform::detect_platform()` — Auto-detection from model name in request body
- `PLATFORM` env var — Manual override (`anthropic`, `openai`, `generic`)
- Server now intercepts `/v1/messages` (Anthropic), `/v1/chat/completions` (OpenAI), and `/chat` (Generic)

#### Tool Output Filtering (R-38)
- **TOML-based filter engine**: 7 built-in filters that compress verbose tool output by 70-90%.
- `proxy/src/filters.rs` — 7-step filter pipeline: `replace → match_output → strip/keep_lines → group_by → head/tail → max_lines → on_empty`
- `proxy/src/filter_rules.rs` — TOML parsing, `CompiledFilter` struct, `compile_filter_file()` with regex validation
- `proxy/src/filter_registry.rs` — Most-specific-match-wins filter selection with priority tiebreaker
- `proxy/src/filter_loader.rs` — Built-in filter loading from `filters/` directory at startup
- `proxy/src/filter_stats.rs` — Per-program token/line savings tracking with dashboard summary
- `proxy/src/community_filters.rs` — Community filter loading from `.clean-ctx/filters/`
- `filters/cargo.toml` — Compact cargo build/test/check/clippy output
- `filters/npm.toml` — Compact npm/yarn/pnpm/bun install/build output
- `filters/git-diff.toml` — Compact git diff/show output
- `filters/pytest.toml` — Compact pytest output
- `filters/tsc.toml` — Compact TypeScript compiler output
- `filters/dotnet.toml` — Compact dotnet build/test/run output
- `filters/ng.toml` — Compact Angular CLI build/test/lint output
- `TOOL_FILTERS` env var — Enable/disable tool output filtering

#### Secret Scrubbing (R-37)
- **Platform-agnostic secret scrubbing**: Detects and redacts secrets in tool results before they reach the LLM.
- `proxy/src/scrub.rs` — `scrub_secrets()` engine with `ScrubResult`, `ScrubHit`, `ScrubFailClosed` semantics
- `proxy/src/scrub_patterns.rs` — Compiled `OnceLock<Regex>` statics for AWS keys, GitHub tokens, JWTs, PEM keys, etc.
- `might_contain_secret()` pre-filter — Cheap literal-substring check before expensive regex passes
- `SCRUB_SECRETS` env var — Enable/disable secret scrubbing
- Now uses `PlatformAdapter::is_tool_result()` for cross-platform detection

#### Pluggable Transform Pipeline
- **`Pipeline` abstraction**: Makes the transform chain pluggable and testable (OCP compliance).
- `proxy/src/pipeline.rs` — `Pipeline::build()` returns composed transforms, `Pipeline::run()` executes all
- New transforms added via closure without modifying existing code
- Each transform receives `&dyn PlatformAdapter` for format-aware operations

#### FAANG Audit & Regression Tests
- **Comprehensive code audit**: 243 total tests (112 lib + 112 bin + 18 audit regression + 1 integration)
- `proxy/tests/audit_regression.rs` — 18 regression tests covering all audit findings
- Critical bugs fixed: hardcoded Anthropic `tool_result` detection in `strip_ansi` and `scrub_secrets`
- Security fix: exact path matching instead of `ends_with` for intercept routing
- All transforms now platform-agnostic via `PlatformAdapter`

### Changed
- `ANTHROPIC_BASE_URL` env var renamed to `UPSTREAM_URL` conceptually (backward-compatible)
- `server.rs` now uses `Pipeline::build()` and `Pipeline::run()` instead of inline transform calls
- `transform::strip_ansi()` now takes `&dyn PlatformAdapter` parameter
- `transform::scrub_secrets()` now takes `&dyn PlatformAdapter` parameter
- `transform::apply_tool_filters()` now uses `PlatformAdapter::is_tool_result()` for cross-platform detection
- All filter modules (filters, filter_rules, filter_registry, filter_loader, filter_stats, community_filters) exported from `lib.rs`
- Documentation updated at `docs/PROXY.md` with multi-platform, filtering, scrubbing, and IDE integration details

### Test count
- 243/243 tests pass (112 proxy lib unit + 112 proxy bin unit + 18 audit regression + 1 integration)
- 0 new clippy warnings (pre-existing warnings only: dead-code on API surface types)

## [0.1.6] — 2026-06-10

### Added

#### Zero-Touch Workflow
- **Prompt Cache Optimization**: Anthropic API cache breakpoint injection via `_meta.cache_hints` in MCP responses.
- `CacheConfig` struct with 7 fields (`enabled`, `system_prompt_ttl`, `tools_ttl`, `baseline_ttl`, `tail_ttl`, `vocab_version`, `tool_defs_version`) in `.clean-ctx.json`
- Cache hints module (`src/mcp/cache_hints.rs`) with `CacheMetrics`, `CacheHints`, `CacheBreakpoint` types and `inject_cache_breakpoints()` function
Expand Down
Loading
Loading