Metadata-Version: 2.4
Name: furl-ctx
Version: 0.27.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: furl-ctx[mcp] ; extra == 'all'
Requires-Dist: tree-sitter>=0.23.0 ; extra == 'code'
Requires-Dist: tree-sitter-language-pack>=0.7.0 ; extra == 'code'
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0 ; extra == 'dev'
Requires-Dist: ruff>=0.15.19 ; extra == 'dev'
Requires-Dist: mypy>=1.14.1 ; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0 ; extra == 'dev'
Requires-Dist: numpy>=1.24.0 ; extra == 'dev'
Requires-Dist: mcp>=1.0.0 ; extra == 'mcp'
Provides-Extra: all
Provides-Extra: code
Provides-Extra: dev
Provides-Extra: mcp
License-File: LICENSE
License-File: NOTICE
Summary: The context compression layer for AI agents - 60-95% fewer tokens on redundant workloads, reversible via CCR
Keywords: llm,openai,anthropic,claude,gpt,context,token,optimization,compression,caching,ai,machine-learning
Author-email: "Omar Y. Abdi" <omar19970423@gmail.com>
Maintainer-email: "Omar Y. Abdi" <omar19970423@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/omar-y-abdi/furl
Project-URL: Issues, https://github.com/omar-y-abdi/furl/issues
Project-URL: Repository, https://github.com/omar-y-abdi/furl

<div align="center"><pre>
  ███████╗ ██╗   ██╗ ██████╗  ██╗
  ██╔════╝ ██║   ██║ ██╔══██╗ ██║
  █████╗   ██║   ██║ ██████╔╝ ██║
  ██╔══╝   ██║   ██║ ██╔══██╗ ██║
   ██║      ╚██████╔╝ ██║  ██║ ███████╗
   ╚═╝       ╚═════╝  ╚═╝  ╚═╝ ╚══════╝
 The context compression layer for AI agents
  <img src="typing.svg" width="42" />
</pre></div>


<p align="center"><strong>60–95% fewer tokens on redundant workloads · a Claude Code plugin · local-first · reversible</strong></p>

<p align="center">
  <a href="https://github.com/omar-y-abdi/furl/releases/latest"><img src="https://img.shields.io/github/v/release/omar-y-abdi/furl?sort=semver&color=blue" alt="Release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
</p>

<p align="center">
  <a href="#install">Install</a> ·
  <a href="#proof">Proof</a> ·
  <a href="LIBRARY.md">Library</a> ·
  <a href="https://discord.gg/yRmaUNpsPJ">Discord</a>
</p>

---

Furl compresses everything your Claude Code agent reads — tool outputs, logs, web fetches, RAG chunks — before it reaches the model. Same answers, a fraction of the tokens. Every dropped byte stays retrievable on demand.

<p align="center">
  <img src="FurlDemo-Fast.gif" alt="Furl in action" width="820">
</p>

## Install

Two commands inside Claude Code:

```
/plugin marketplace add omar-y-abdi/furl
/plugin install furl@furl
```

That's it — this installs the compression hook, the MCP tools, and the skill. No `pip install`, no setup: Furl fetches itself on first use. Requires [`uv`](https://docs.astral.sh/uv/) on your PATH (same as the official [serena](https://github.com/oraios/serena) plugin).

**What you get**

- **Auto-compression hook** — shrinks large `Bash` / `WebFetch` / `WebSearch` / `Task` outputs before they enter context. Fail-open: never breaks a tool call.
- **MCP tools** — `furl_compress`, `furl_retrieve`, `furl_stats`.
- **Skill** — explains the `<<ccr:HASH>>` retrieval flow and how to tune or disable it.

Tuning, disabling (`FURL_HOOK_ENABLED=0`), and the full reference: [`plugins/furl/README.md`](plugins/furl/README.md).

## Proof

Token reduction on real captured data — reproducible, inputs committed under `benchmarks/data/`. Every number uses the engine's own tokenizer; needle recall is 100% (a known unique row is always recoverable, in the output or via CCR):

| Dataset       | Items | Before | After  | Reduction | Info retention |
|---------------|------:|-------:|-------:|----------:|---------------:|
| code          |     7 | 41,025 |    471 |       99% |           100% |
| multiturn     |   135 | 14,866 |  2,073 |       86% |           100% |
| logs          |    90 |  8,595 |    619 |       93% |           100% |
| search        |    90 |  4,102 |    318 |       92% |           100% |
| repeated logs |    90 |  3,621 |    120 |       97% |           100% |
| disk          |     9 |    694 |    347 |       50% |           100% |

Across the corpus: **94% fewer tokens** (72,903 → 4,016) at 100% information retention. Full methodology and the 6-seed adversarial sweep: [BENCHMARKS.md](BENCHMARKS.md).

## Also a Python library

The same engine drops into any Python app or MCP host: `from furl_ctx import compress`. Install, usage, pipeline internals, prompt-caching contract, and the full `FURL_*` config reference live in [LIBRARY.md](LIBRARY.md).

## License

Apache 2.0 — see [LICENSE](LICENSE).

