Skip to main content
Glama
README.md
# `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

A3.5/5.0

Scored across 4 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues