Metadata-Version: 2.4
Name: rclm
Version: 0.1.23
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
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.

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.

---

## 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 token usage for Claude Code
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]'`.

### 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
