xnip

English | 中文

Precise text edits with less repeated context. Give your coding agent a known old block and its replacement. xnip changes that block, preserves untouched bytes, and returns a compact receipt.

• Send the change. Reuse known context instead of repeating unchanged files or long lines.
• Edit precisely. Missing or ambiguous blocks fail before writing; exact edits preserve CRLF and final-newline bytes.
• Use it across agents. The CLI and stdio MCP server share exact edits, batches, previews and file lifecycle operations.

Install

Use the standalone installer for your platform:

# macOS / Linux
curl -fsSL https://github.com/SeaLoong/xnip/releases/latest/download/install.sh | sh

# Windows
Invoke-RestMethod https://github.com/SeaLoong/xnip/releases/latest/download/install.ps1 | Invoke-Expression

Or use release downloads or the npm package, xnip-cli. See installation for PATH setup, checksums and all options.

Standalone binaries support silent updates. Set XNIP_AUTO_UPDATE=0 to disable them; npm installations update through npm. See update behavior.

Make an edit

Preview a change, then apply it:

xnip edit config.env --old 'PORT=8080' --text 'PORT=3000' --dry-run
xnip edit config.env --old 'PORT=8080' --text 'PORT=3000'

The old block must be nonempty and unique. Extend it with context when ambiguous; use --all for an intentional global replacement. --check validates without writing.

For an explicit complete-file rewrite, use xnip edit generated.txt --write --text-file content.txt. For multiline content, payload files or stdin avoid shell-escaping mistakes.

Save several edits as edits.json:

{
  "config.env": [["PORT=8080", "PORT=3000"]],
  "src/settings.py": [["DEBUG = True", "DEBUG = False"]]
}

xnip apply edits.json --format compact --dry-run
xnip apply edits.json --format compact

Pairs within a file run in order. Use peek and find when context is missing. See CLI usage, editing examples and batch formats for insertion, line edits, patches, create, rename and delete.

Connect your agent

Use the CLI from your agent's shell, or add the stdio MCP server. For clients with a mcpServers configuration:

{
  "mcpServers": {
    "xnip": {
      "command": "xnip",
      "args": ["mcp", "--receipts", "text"]
    }
  }
}

The five default tools cover editing, batches, reading, search and recovery. --toolset full adds specialized tools; omit --receipts text when the client needs structured change metadata. Relative paths use the server's working directory. See MCP setup for client-specific details.

Agent / client	Setup
Codex	Instructions and editing guide
Claude Code	Skill
Cursor	Project rule
GitHub Copilot	Project instructions
aider	Conventions
DeepSeek Harness	DSH bundle and MCP plugin
Pi	Extension
Goose	MCP extension
Other agents	Generic skill

Prefer a short project instruction? Use the AGENTS snippet. The operation guide helps agents choose an edit and load details only when needed.

Why it saves editing context

The benchmark compares real editors across 13 tasks. Only results that produce the expected file bytes in every repetition qualify.

Ratios are equal-task geometric means of best observed native input / best observed xnip input; above 1x means less xnip input. Guarded pools retain old-content checks. Snapshot-enabled pools allow both guarded edits and whole-file writes on both sides.

xnip interface / allowed operations	Native best / xnip best	xnip shorter / tied / native shorter
MCP · guarded	1.23x	13 / 0 / 0
MCP · snapshot-enabled	1.26x	12 / 1 / 0
CLI stdin · guarded	1.55x	13 / 0 / 0
CLI stdin · snapshot-enabled	1.80x	13 / 0 / 0

With complete file context, the long-line edit takes 11 MCP input tokens, versus 18 for the best observed native input (Goose) and 10,037 for Codex's unique-context patch.

Compared with structured receipts, text receipts reduce captured full JSON-RPC reply tokens by about 56%. The five-tool discovery catalog is 23.8% smaller, with identical edit inputs and file outcomes.

These are captured editing payload costs, not complete agent usage or billing. CLI invocation costs are separate. DSH's policy-specific results include required reads and are reported outside this pooled table.

Full results and charts · Method and reproduction

Know the limits

• Preconditions check current bytes; they do not lock out external writers. Keep Git or backups for exact recovery.
• Batches validate before committing files individually. After a commit/rollback failure, inspect the recovery journal before retrying.
• Reads and previews have explicit output limits. Narrow the request or adjust the applicable limit when truncated.
• MCP runs with the launching user's permissions and working directory. Use trusted local clients.

Installation · CLI · Edit reference · MCP · Exit codes · Changelog · Contributing

MIT licensed. See LICENSE and third-party notices.