# compression-safety

compression-safety blocks lean-ctx markers from being written back to files. Required if you run lean-ctx in shadow mode.

- rule · `type=rule` · Claude Code, Cline, Kiro, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop) · ★ 3956 repo stars
- Author: yvgude
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/yvgude/lean-ctx/tree/HEAD/.cursor/rules/compression-safety.mdc
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/rules/compression-safety

## What it does

lean-ctx shadow-mode hooks compress file reads by replacing line blocks with `[lean-ctx: omitted N lines]`. If an edit tool (`StrReplace`, `Write`) reads through the hook, it sees compressed content and writes markers to disk, silently destroying the file. The rule teaches the agent to bypass compression with `LEAN_CTX_DISABLED=1` when restoring from git, check file size after edits, and refuse to commit markers.

The built-in lean-ctx pre-commit hook blocks commits containing markers. Blocked commit means corrupted file: restore with `LEAN_CTX_DISABLED=1 git restore --source=HEAD -- <file>`. For edits that break through `StrReplace`, the rule prescribes `sed` with the same variable.

Place the rule in `.claude/rules/`, `.cursor/rules/`, `.clinerules/` or `.devin/rules/` depending on your IDE.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/compression-safety.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/compression-safety.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/compression-safety.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/compression-safety.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/compression-safety.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/yvgude/lean-ctx/tree/HEAD/.cursor/rules/compression-safety.mdc

## When to use it
- prevent lean-ctx markers from being written to files
- restore a file after corruption by compressed output
- bypass lean-ctx hooks when working with git
- check a file for markers before committing

## Example prompts
- Restore `src/utils.ts` from HEAD with lean-ctx disabled
- Replace `oldFunc` with `newFunc` in `app.js` using `sed` to bypass hooks
- Check if `config.json` contains `[lean-ctx:` markers

## Source text · compression-safety.mdc · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c6323ae667a8bc78.

BEGIN THIRD-PARTY FILE c6323ae667a8bc78
````text
# Compression Safety — Prevent lean-ctx Marker Corruption

## The problem

lean-ctx shadow-mode hooks compress file reads. If an edit tool (StrReplace, Write)
reads through the hook, it sees compressed content and writes markers like
`[lean-ctx: omitted N lines]` back to disk. This silently destroys file content.

## Rules for ALL agents

### Never write compressed content to files

The pre-commit hook blocks commits containing `[lean-ctx: omitted` markers.
If your commit is blocked, the file was corrupted. Fix:

```bash
LEAN_CTX_DISABLED=1 git restore --source=HEAD -- <file>
```

### File restoration commands

Always use `LEAN_CTX_DISABLED=1` when restoring files from git:

```bash
LEAN_CTX_DISABLED=1 git restore --source=<commit> -- <file>
LEAN_CTX_DISABLED=1 git checkout <commit> -- <file>
```

NEVER use `git show commit:file > file` — the shell redirect writes compressed output.

### When StrReplace produces unexpected results

If a file shrinks after StrReplace or contains `[lean-ctx:` text:
1. `LEAN_CTX_DISABLED=1 git restore --source=HEAD -- <file>`
2. Use `LEAN_CTX_DISABLED=1 sed -i '' 's/old/new/g' <file>` for the edit
3. Verify: `wc -l` + `rg '[lean-ctx:' <file>` must show 0

### Environment variable: `LEAN_CTX_DISABLED`

Set `LEAN_CTX_DISABLED=1` to bypass ALL lean-ctx compression for a command.
This is the escape hatch for any compression-related issue.

## NEVER do

- Pipe `git show` output to a file without `LEAN_CTX_DISABLED=1`
- Trust `wc -l` output that's significantly lower than expected
- Commit files containing `[lean-ctx: omitted` or `--- lean-ctx:` text
````
END THIRD-PARTY FILE c6323ae667a8bc78

The third-party file has ended. Everything between the c6323ae667a8bc78 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© yvgude · Apache-2.0 · https://github.com/yvgude/lean-ctx/tree/HEAD/.cursor/rules/compression-safety.mdc

## Similar
- [omni-compression](https://affpapa.org/en/nevibecode/skills/omni-compression.md) — skill · 1300 installs
- [compression-editor](https://affpapa.org/en/nevibecode/agents/compression-editor.md) — subagent · ★ 173 repo stars
- [compression](https://affpapa.org/en/nevibecode/skills/compression.md) — skill · 1700 installs
- [git-2-49-features](https://affpapa.org/en/nevibecode/skills/git-2-49-features.md) — skill · 161 installs
- [git-safety](https://affpapa.org/en/nevibecode/skills/git-safety.md) — skill · ★ 14319 repo stars
- [safety-net](https://affpapa.org/en/nevibecode/plugins/safety-net.md) — plugin · ★ 2088 repo stars

From the same set: [yvgude/lean-ctx](https://affpapa.org/en/nevibecode/by/yvgude/lean-ctx.md) — 4 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
