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

pip install rclm
# Or for proxy support: pip install 'rclm[proxy]'

2. Setup Hooks

# 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

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

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

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:

rclm-hooks-install --with-mcp

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

MCP Tools

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

Advanced Usage

Context Compression & DLP

Env-file DLP is enabled on fresh installs and preserves an explicit saved opt-out:

rclm-hooks-install --compress                          # Reduces tool-result tokens in Claude Code, Codex, and Cursor
rclm-hooks-install --dlp                                # Explicitly enable or re-enable DLP
rclm-hooks-install --no-dlp                             # Explicitly disable DLP
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:

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:

rclm-proxy setup
rclm-proxy start

Technical Details

For information on data models, hook internals, and the DLP engine, see architecture.md.

Development

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