Metadata-Version: 2.4
Name: rclm
Version: 0.1.25
Summary: Capture and upload LLM sessions from local hooks and proxy integrations
Project-URL: Homepage, https://reclaimllm.com
Author: ReclaimLLM
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,claude-code,codex,gemini,hooks,llm,proxy
Classifier: Development Status :: 3 - Alpha
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: certifi>=2026.2.25
Requires-Dist: mcp<2,>=1.0
Requires-Dist: tiktoken<1,>=0.8
Provides-Extra: dev
Requires-Dist: litellm[proxy]<1.82,>=1.40; extra == 'dev'
Requires-Dist: pillow<12,>=10.0; extra == 'dev'
Requires-Dist: pre-commit==4.5.1; extra == 'dev'
Requires-Dist: prisma<2.0,>=0.11; extra == 'dev'
Requires-Dist: pytest-aiohttp<2.0,>=1.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0,>=1.3.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=9.0.2; extra == 'dev'
Requires-Dist: ruff==0.15.9; extra == 'dev'
Provides-Extra: images
Requires-Dist: pillow<12,>=10.0; extra == 'images'
Provides-Extra: proxy
Requires-Dist: litellm[proxy]<1.82,>=1.40; extra == 'proxy'
Requires-Dist: prisma<2.0,>=0.11; extra == 'proxy'
Description-Content-Type: text/markdown

# RCLM — Data Capture for AI Tools

Every time you use an AI coding assistant, you produce valuable reasoning and code. **RCLM** (ReclaimLLM) ensures that data belongs to you. It is a lightweight capture layer that records your AI sessions from Claude Code, Gemini CLI, Codex CLI, and OpenClaw, shipping them to your personal ReclaimLLM account for search, analysis, and continuation.

## Key Features

- **Native Hooks:** Zero-config integration into Claude Code, Gemini CLI, Codex CLI, and OpenClaw.
- **Historical Sync:** One-command backfill for all your past AI sessions.
- **DLP & Privacy:** Automatic redaction of secrets from `.env` files before they reach the model.
- **Context Compression:** Read caching, result dedup, exec-output compaction, and automatic image downscaling cut token usage without losing information — see [Context Compression & DLP](#context-compression--dlp).
- **Context Conversion:** Export any captured session as a Markdown context document to continue work in a different tool.
- **Local Proxy:** Experimental LiteLLM-based proxy for OpenAI-compatible tools.

---

## Quick Start

### 1. Install
```bash
pip install rclm
# Or for proxy support: pip install 'rclm[proxy]'
```

### 2. Setup Hooks
```bash
# Integrates with Claude Code, Gemini CLI, Codex CLI, and OpenClaw
rclm-hooks-install
```
This will open a browser to `reclaimllm.com` to link your account. Once linked, every session is automatically captured.

### 3. Sync History
```bash
# Upload sessions that predated the installation
rclm-sync
```

---

## Session Conversion (New!)

`rclm convert-session` generates a compact context document for starting a new session in another tool. It does not restore the source tool's private runtime state.

```bash
# Export a session for Claude Code
rclm convert-session <session_id> claude -o CLAUDE.md

# Export for Gemini CLI
rclm convert-session <session_id> gemini -o .gemini

# Options
rclm convert-session <session_id> generic --no-diffs          # Omit file diffs
rclm convert-session <session_id> claude  --force-regenerate  # Use LLM for a fresh summary
```
*Supported targets:* `claude`, `gemini`, `codex`, `generic`.

---

## Agent Plugins

RCLM includes local plugin marketplace entries for Codex, Claude, and Cursor. Each plugin exposes ReclaimLLM as persistent memory for AI agents through the bundled `rclm-mcp` server.

```bash
codex plugin marketplace add /path/to/DC-hooks-proxy
codex plugin add reclaimllm@reclaimllm-plugins
```

For Claude and Cursor, add the matching marketplace file from this repo:

- `DC-hooks-proxy/.claude-plugin/marketplace.json`
- `DC-hooks-proxy/.cursor-plugin/marketplace.json`

Then authenticate the local MCP server if you have not already:

```bash
rclm-hooks-install --with-mcp
```

Start a new agent thread and confirm the `reclaimllm` plugin and MCP server are enabled.

### MCP Tools

| Tool | Description |
|---|---|
| `search_sessions` | Hybrid semantic + keyword search across captured sessions by topic, error, file, or date range. |
| `search_by_filename` | File/folder-scoped session history, e.g. "what changed in `auth.tsx`". |
| `get_session` | Summary metadata and a frontend link for one session ID. |
| `summarize_session` | Pull a specific session's summary in as working context, on explicit request. |
| `list_projects` | List available project filters. |
| `file_brief` | Recent-history brief for a file before making a non-trivial edit to it. |
| `handoff` | Generate a continuation document to start a fresh session without losing context. |
| `transfer_session` | Stream a complete captured session (messages, tool calls/results, file diffs) as a versioned JSON artifact. |
| `signals` | Up to 5 open workflow-efficiency signals (evidence + prescribed fix) for the current project. |
| `replay_eligibility` | Cheap, metadata-only check of whether replaying compression mechanisms is worth doing. |
| `replay_session` | Reproduce shipped compression mechanisms over one captured session and report the real tool-result token reduction. |
| `replay_corpus` | Same as `replay_session`, aggregated across a filtered window of sessions. |
| `replay_compare` | Replay the same corpus under multiple mechanism configurations in one call. |

All tools are read-only: none re-execute historical commands, call a model, or modify captured data.

When you need the complete captured session instead of a summary, ask the target agent to call `transfer_session` with the ReclaimLLM session ID. The tool streams a versioned JSON artifact containing every captured message, tool call/result, file diff, and metadata field into an owner-only temporary file. The target agent reads that file as historical context; recorded tool calls are never re-executed automatically.

`SESSION_TRANSFER_MAX_BYTES` controls the backend and local download ceiling and defaults to 100 MiB. Transfers are never silently truncated. `SESSION_TRANSFER_TTL_SECONDS` controls when local artifacts become eligible for bounded opportunistic cleanup and defaults to one hour.

### Replay: verifying token savings

`replay_eligibility`, `replay_session`, `replay_corpus`, and `replay_compare` reproduce RCLM's shipped compression mechanisms (`range_cache`, `shell_compaction`, `hash_dedupe`) over already-captured sessions and report the real tool-result token reduction, without calling a model or re-running any historical command:

- "Would compression help on my last 50 sessions?" → `replay_eligibility`
- "How much did compression save on session `<id>`?" → `replay_session`
- "What's the aggregate savings across my Codex sessions this month?" → `replay_corpus`
- "Compare shell compaction alone vs. combined with range cache" → `replay_compare`

Every result states sessions considered vs. eligible vs. excluded; a session or corpus below the turn/tool-call thresholds is refused with the specific failing constraint rather than given an unstable number.

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `rclm-hooks-install` | Install/configure native hooks for local LLM CLIs. |
| `rclm-sync` | Discover and upload historical transcripts. |
| `rclm convert-session` | Export a session to Markdown context for tool switching. |
| `rclm-proxy` | Start/setup a LiteLLM proxy for OpenAI-compatible capture. |
| `rclm-update` | Check for and apply updates to the `rclm` package. |

---

## Advanced Usage

### Context Compression & DLP
Enable advanced features during installation:
```bash
rclm-hooks-install --compress                          # Reduces tool-result tokens in Claude Code, Codex, and Cursor
rclm-hooks-install --dlp                                # Enables Data Loss Prevention for .env files
rclm-hooks-install --image-lifecycle                    # Downscales oversized screenshots/images before they reach the model
rclm-hooks-install --image-lifecycle --image-max-dim=1280  # Set the max image dimension in pixels (default 1280)
```

Image downscaling (`--image-lifecycle`) resizes and re-encodes oversized tool-result images — full-page screenshots, MCP screenshot-tool output — before they enter the model's context, and never upscales. It applies for real on Claude Code sessions; on Codex it currently reports measured before/after savings only, since Codex CLI does not yet apply hook-driven rewrites of MCP tool output. Requires the optional `images` extra: `pip install 'rclm[images]'`.

Text compression uses each coding client's native hooks; it does not require proxy or LLM-gateway traffic. Claude Code and Codex support recognized shell-output compaction. Cursor wraps recognized shell commands before execution and limits post-result replacement to structured MCP output. Unknown commands, failures, images, and ambiguous structured results pass through unchanged. Identical-result dedupe remains off by default (`--dedupe`).

### Folder Capture Filters
Limit uploads to specific project folders during installation:
```bash
rclm-hooks-install --include-folder=/path/to/project
rclm-hooks-install --include-folder=/work/app --include-folder=/work/infra
```

Use `--exclude-folder=/path/to/private` to skip specific folders when no include allowlist is configured.

### Proxy Capture (Experimental)
Point your tools at `http://localhost:4000` to capture raw API interactions:
```bash
rclm-proxy setup
rclm-proxy start
```

---

## Technical Details

For information on data models, hook internals, and the DLP engine, see [**architecture.md**](architecture.md).

## Development

```bash
uv sync --extra dev          # Install dev dependencies
uv run pre-commit install    # Setup linting/formatting hooks
uv run pytest rclm/tests     # Run the test suite
```

License: Apache-2.0
