pare
# `pare` — Lean Context & Honesty Harness for Coding Agents
**Pare down context noise, code bloat, and dishonest AI tests.**
Pure Python 3.10+ standard library · **Zero external dependencies** · Built-in CLI + `stdio` MCP server + Agent Skill.
中文文档见 `README.zh-CN.md`。
## Why `pare`?
Coding agents fail in three predictable ways: they burn context windows reading repetitive logs/JSON/CSV dumps, pass CI by writing dishonest tests (`sleep()`, retry decorators, `except: pass`, `assert True`), and over-engineer simple changes.
`pare` stitches the sharpest ideas from four lightweight projects trending on GitHub into a single ~1,000-line, zero-dependency micro-tool:
| Capability | Subcommand | Upstream Inspiration | What `pare` Does |
| :--- | :--- | :--- | :--- |
| Lossless Output Compression | `pare shrink` / `pare run` / `pare recall` | [JuliusBrussee/caveman](https://github.com/juliusbrussee/caveman) | Compresses JSON arrays, CSV/TSV tables, and test/server logs by 95%–99% while archiving byte-exact originals by SHA-256 ID for instant slice/regex recall |
| AI Code Honesty Guard | `pare check` | [interfere-inc/landmines](https://github.com/interfere-inc/landmines) | AST + structural linter for Python and JS/TS blocking fixed test sleeps, retry flake-masking, silent `except: pass` / `catch {}`, and tautological tests, with a downward-only `.pare.json` ratchet |
| YAGNI Debt Ledger & Rules | `pare debt` / `pare init` | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | Harvests inline `# shortcut(trigger): reason` markers into an auditable debt ledger and generates minimal `AGENTS.md` / `SKILL.md` templates |
| Self-Producing MCP Contract | `pare contract` / `pare mcp` | [kajisho5/ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill) | Derives JSON Schema tool contracts directly from `argparse` definitions at runtime and serves all tools over a zero-dependency `stdio` JSON-RPC 2.0 MCP server |
## Quick Start
Requires only Python 3.10+ (`uv`, `pipx`, or direct `python3 -m pare` with zero packages to download):
```bash
# Install globally as an isolated CLI tool (or run `python3 -m pare` directly from the repo)
uv tool install .
# 1. Run any noisy test suite or command; errors stay verbatim, noise shrinks, exit code is preserved
pare run -- pytest -v
# 2. Recover exact raw lines or regex hits from any compressed block
pare recall <12-char-id> --lines 1:60
pare recall <12-char-id> --grep "AssertionError"
# 3. Catch dishonest AI test patterns and silent error swallowing
pare check .
# 4. Audit deliberate `shortcut:` trade-offs across git-tracked code
pare debt .
# 5. Bootstrap AGENTS.md, .claude/skills/pare/SKILL.md, and MCP config
pare init .
```
## Connect to Claude Code, Antigravity, Codex, or Gemini CLI
Add `pare` to `.mcp.json` (or your agent's MCP settings):
```json
{
"mcpServers": {
"pare": {
"command": "python3",
"args": ["-m", "pare", "mcp"]
}
}
}
```
Every MCP tool schema (`pare_shrink`, `pare_recall`, `pare_check`, `pare_debt`) is generated directly from `pare/cli.py`'s `argparse` definitions (`pare contract`), guaranteeing zero drift between CLI flags and MCP tool schemas.
## Measured Compression Ratios
Measured locally with `pare shrink` on representative outputs (100% of raw bytes remain recoverable via `pare recall <id>`):
| Workload | Raw Size | `pare` Summary | Bytes Saved | Preserved Automatically |
| :--- | ---: | ---: | ---: | :--- |
| JSON API response (250 objects) | 49,642 B | 599 B | **98.8%** | Schema fields, numeric `min..max` ranges, HTTP `>=400` anomalies, head/tail items |
| Training metrics CSV (300 rows) | 6,817 B | 320 B | **95.3%** | Column names, numeric column bounds, flagged error rows, head/tail rows |
| Test + server log stream (331 lines) | 16,871 B | 249 B | **98.5%** | Exact `FAIL` / `AssertionError` lines, `[collapsed N passing]` count, `[×N]` log deduplication |
## Honesty Rules (`pare check`)
Every violation includes an actionable `instead:` remediation instruction so coding agents fix the root cause in the same turn:
- **`no-fixed-sleep`**: Flags `time.sleep(N)` / `asyncio.sleep(N)` / `setTimeout(..., N)` in test files. *Instead: await a readiness signal, event, or fake clock.*
- **`no-flake-masking`**: Flags `@pytest.mark.flaky`, `reruns=`, non-strict `xfail`, `.retry(N)`, and `jest.retryTimes(N)`. *Instead: fix the underlying race condition.*
- **`no-hollow-catch`**: Flags Python `except ...: pass` and JS/TS empty `catch {}` blocks. *Instead: catch the specific exception type and handle, log, or re-raise.*
- **`no-tautology-assert`**: Flags `assert True`, `expect(true).toBe(true)`, and `test_*` functions with zero assertions. *Instead: assert concrete outputs or expected exceptions.*
- **`ratchet-stale`**: Optional `.pare.json` allowlist (`{"allow": {"tests/legacy_test.py": {"no-fixed-sleep": 1}}}`) suppresses legacy debt and fails as soon as actual violations drop below the allowance so debt only moves downward.
## Repository Layout
```text
pare/
├── pare/
│ ├── shrink.py # JSON/CSV/log lossless-recoverable compressor + SHA-256 vault
│ ├── landmines.py # Python AST + JS/TS honesty scanner & downward ratchet
│ ├── debt.py # `shortcut:` debt ledger & AGENTS.md / SKILL.md bootstrapper
│ ├── contract.py # argparse -> JSON Schema SPEC builder & stdio MCP server
│ └── cli.py # Unified CLI entrypoint (`pare`)
├── tests/
│ └── test_pare.py # Hermetic stdlib unittest suite + self-dogfooding check
├── SKILL.md # Cross-agent skill specification
├── CREDITS.md # Upstream attribution & license provenance
└── pyproject.toml # Zero-dependency PEP 621 package metadata
```
## Credits & License
MIT License. Built from scratch on the Python standard library, inspired by [JuliusBrussee/caveman](https://github.com/juliusbrussee/caveman), [interfere-inc/landmines](https://github.com/interfere-inc/landmines), [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail), and [kajisho5/ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill).
TDQS
Scored across 4 tools
pare_shrink and pare_recall form a clear compress/recover pair with distinct roles. pare_check and pare_debt are both repository/file scanners, but their targets (test landmines/hollow error handling vs `shortcut:` markers) are described clearly enough to avoid misselection, though 'check' alone is a fairly vague name.
All tools share a consistent `pare_` prefix and short, readable suffixes. Minor deviation: shrink/recall/check are verbs while debt is a noun, but the overall pattern holds.
Four tools is well-scoped for a focused output-compression-plus-scan utility. Each tool maps to a distinct capability (compress, recall, two targeted scans) with no filler.
The shrink/recall lifecycle is fully covered for the compression side, and the server covers two scan types. Minor gaps: no way to list or clear previously stored recall IDs, no options on scans (severity/filtering), and no action on findings such as exporting or resolving the debt ledger.