moesniper

Escape-proof precision file editor for LLM agents. Hex-encoded content, line-range splicing, atomic writes, metabolic pacing.

Quick Start

cargo install moesniper

# Replace line 5
sniper file.rs 5 5 68656c6c6f

# Undo
sniper file.rs --undo

Features

Usage

sniper <file> <start> <end> <hex>                Replace lines with hex content
sniper <file> <start> <end> --delete             Delete line range
sniper <file> <start> <end> --stdin              Read content from stdin
sniper <file> <start> <end> <hex> --context <h>  Replace with context verification
sniper <file> --manifest <path>                  Batch operations (JSON)
sniper <file> --undo                             Restore from backup
sniper encode [--stdin|--file <path>|<text>]      Hex-encode content
sniper context <file> <start> <end>              Compute context hash for a given line range

Flags

Context Verification

The --context <hash> flag allows rejecting an edit if the file has changed around the edit site. The hash is the first 16 hex characters of the SHA-256 of the concatenated raw bytes (including all newlines) of exactly 3 lines before the <start> line, and exactly 3 lines after the <end> line. Line numbers are not part of the hash.

You can generate the context hash using the command:

sniper context file.rs <start> <end>

Encoding

Content must be hex-encoded to prevent shell corruption:

echo -n 'fn main() {}' | sniper encode --stdin
# 666e206d61696e2829207b7d

Manifest Format

[
  {"start": 42, "end": 45, "hex": "6e6577"},
  {"start": 10, "delete": true}
]

Operations apply bottom-up (highest line first, so earlier edits don't shift later targets). Line numbers are 1-indexed.

Examples

# Replace a function
sniper src/main.rs 42 42 $(echo 'new_call()' | sniper encode --stdin)

# Delete a block
sniper src/lib.rs 100 150 --delete

# Safe workflow (preview first)
sniper file.rs 1 5 7878 --dry-run && sniper file.rs 1 5 7878

# Batch edit via manifest
echo '[{"start":1,"end":1,"hex":"78"}]' | sniper file.rs --manifest /dev/stdin

# Insert at end of file
sniper file.rs 4 3 $(echo 'new_line' | sniper encode --stdin)

# Context-verified edit (rejects if surrounding code changed)
sniper file.rs 10 10 7878 --context 1a2b3c4d5e6f7a8b

Configuration

How It Works

1. Path validation — normalize_path() rejects .. traversal and canonicalizes
2. File size check — rejects files exceeding SNIPER_MAX_FILE_SIZE
3. Lock acquisition — PID file lock with configurable timeout; stale PID detection recovers from crashed processes
4. Context verification — optional --context <sha256> flag hashes 3 lines before and 3 lines after the edit target; if the context changed since the agent computed line numbers, the edit is rejected with a "context mismatch" error
5. Backup — file copied to .sniper/ with hash+timestamp name
6. Splice — lines loaded into memory, range replaced, result written atomically (temp file + rename)
7. Metabolic pacing — llmosafe checks RSS, IO wait, load average; sleeps if system is under pressure
8. Purge — old backups pruned by count and age per retention policy

JSON Output

The --json flag produces a CliResult object with these fields:

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.