Skip to main content
Glama

parecode

An MCP server that gives coding agents context-window-aware search and safe, atomic multi-file edits — built to cut token usage on large codebases without giving up correctness.

parecode MCP server


Requirements

  • Node.js 20 or newer (ESM, native test runner, stable fetch-free runtime).

  • ripgrep on PATH (rg on Linux/macOS, rg.exe on Windows). Install via your package manager:

    • macOS: brew install ripgrep

    • Debian/Ubuntu: apt install ripgrep

    • Windows: winget install BurntSushi.ripgrep.MSVC or choco install ripgrep

  • A supported MCP client (Claude Code is the reference target).

Parecode does not bundle ripgrep — it shells out to the system binary so you stay on a single, audited version.


Related MCP server: rlm-tools

Install

npm install -g parecode

Pure JavaScript — no native dependencies, no C/C++ toolchain required.


Quick start

Register the server with Claude Code:

parecode init                       # user scope; installs MCP + SessionStart hook + parecode-explore plugin (defaults)
parecode init --scope project       # commit MCP config + hook to the repo
parecode init --no-hook             # register MCP only; skip the SessionStart hook
parecode init --no-plugin           # skip the parecode-explore Claude Code plugin
parecode init --print               # print the equivalent command without running it
parecode init --remove-hook         # remove the SessionStart hook (MCP stays registered)
parecode init --remove-plugin       # uninstall the parecode-explore Claude Code plugin

The SessionStart hook injects a short directive at the start of each session telling Claude to prefer ParecodeSearch / ParecodeEdit over the equivalent native tools. Without it, Claude's first-party Grep / Read / Edit tools typically win by default and Parecode's token savings never land. The hook payload is a static string; parecode hook session-start prints it. Pass --no-hook if you would rather opt in explicitly per session via your own tooling.

The bundled parecode-explore Claude Code plugin adds a read-only subagent (pinned to Haiku, given only ParecodeSearch) and a matching skill, so exploration-style questions ("where is X?", "how does Y work?", "find all usages of Z") get answered in a cheap, isolated context window instead of burning tokens in your main session. init registers a local marketplace pointing at the npm-installed copy and runs claude plugin install parecode-explore@parecode. If your Claude Code build doesn't support the plugin subcommand the step soft-fails with a warning and the rest of init still succeeds; pass --no-plugin to skip it entirely, or --with-plugin to make any plugin-step failure hard-fail.

Then in any session, the ParecodeSearch, ParecodeExpand, and ParecodeEdit tools become available. Run parecode doctor to confirm registration, hook status, and .codegraph/ pairing if present.


What it does

  • ParecodeSearch — ripgrep-backed search that returns matches with surrounding context windows in a single call, with per-file byte chunking so large result sets do not blow up your context.

    • pattern accepts a single string or an array of strings; arrays dispatch parallel ripgrep runs sharing the same paths / contextLines, and each match carries a patterns: string[] field listing which input patterns contributed. One call replaces N back-to-back greps for related-keyword flow tracing.

    • Overlapping or adjacent windows within the same file are merged automatically (gap ≤ contextLines), with bridging lines loaded from disk.

    • Per-match and response-level estimatedTokens are returned so the agent can self-budget before consuming results.

    • Opt-in relatedSymbols: true surfaces likely event-flow neighbours (Handle<X>, On<X>, <X>Handler/Listener/Closed/Completed/Started) discovered in each match, capped at 10.

    • Omitted line ranges are reported so the agent can widen with ParecodeExpand without re-reading the whole file.

  • ParecodeExpand — widen a known (file, startLine, endLine) range with optional contextBefore / contextAfter padding. Designed as the natural follow-up to a ParecodeSearch match. Returns the same estimatedTokens shape so the same self-budgeting heuristic applies. Prefer this over a full-file Read after locating a line.

  • ParecodeEdit — batched multi-file edits with whitespace-tolerant fuzzy matching (and an opt-in Unicode-lookalike mode), pre/post stat conflict detection, and atomic same-directory rename writes. Cross-file edits run in parallel.

  • parecode stats — local JSONL session log with token-saved estimates. Zero network. Zero telemetry.


Measured savings

On search-and-edit tasks — finding call sites, multi-file refactors, "do X to every Y" — Parecode cut cost ~40% and assistant turns ~75–83% in matched A/B tests:

repo

task

cost

turns

TypeScript

find every call site of a symbol, edit each (17 sites, 8 files)

−43%

−83%

Unity / C#

find every call site of a symbol, edit each (11 sites, 5 files)

−41%

−76%

Method: the identical task run with Parecode on vs off, a fresh session per run, n=3 per arm with alternated order, Sonnet 4.6. Savings come from collapsing many Grep / Read / Edit round-trips into single ParecodeSearch / ParecodeEdit calls — so the win scales with how much searching and multi-file fan-out a task involves, and shrinks toward zero on single-file or reasoning-heavy tasks. These are measured per-session token and cost numbers, not the estimates in the scan below.


Retroactive Savings Scan

Curious how much Parecode would have saved you if you had installed it earlier? You can scan your past Claude Code sessions:

parecode stats --retroactive --since 30d

Sample output:

Parecode — last 30d (retroactive scan)
─────────────────────
Sessions:                   42
Tool calls:                156
Calls batched (est):        89
Tokens saved (est):  1,200,000

* Note: Retroactive savings are estimated, not measured.

Privacy disclaimer: This scan runs entirely locally against Claude Code's session transcripts (~/.claude/projects/**). By default, it parses only structured fields (tool names, paths, patterns, and token counts). It does not send any data over the network. The --include-content flag (which allows reading tool input/output) is strictly opt-in and loudly flagged if used.


Privacy

Parecode performs no network calls at runtime. Session logs are written to your OS data directory (resolved via env-paths) with 0600 permissions on Unix. Logs are self-maintaining: each server start prunes session data older than 30 days and caps the envelope log at 5 MB. Prune earlier with parecode prune <days> or wipe the data dir. Update to the latest release (and refresh hooks/plugin) with parecode update.


License

MIT

Available Tools

3 tools
ParecodeEditA

Apply many edits across many files in one call — the edit counterpart to ParecodeSearch/ParecodeExpand. Prefer over native Edit/MultiEdit for 2+ edits to one file, edits across files (files apply in parallel), or one logical revision that should land together. Each item is a line-range op (replaceLines or insertAfter, guarded by an expect anchor) or a string-patch op (oldString/newString; fuzzy:true tolerates whitespace drift, 'aggressive' also normalizes Unicode look-alikes). Strongly prefer line-range ops when you know the target lines — e.g. the line numbers ParecodeSearch returned: a line number plus a short expect anchor skips constructing exact-match snippets, so recurring text (a repeated call) can't trigger the multiple-match errors and retries an oldString needs extra context to avoid. Reserve oldString for edits with no known lines. Atomicity is per file, NOT cross-file: within a file all ops apply or none, other files commit independently — check each result's status. Writes are atomic with mtime conflict detection; fuzzy fails closed on low confidence or ambiguity.

Inputs: edits (required).

ParecodeExpandA

Read a specific line range of a file — the natural follow-up to a ParecodeSearch match or an omittedLineRanges entry it returned. Use instead of a full-file Read (or Read with offset/limit) when you already know roughly where the code lives and just need more lines around it. Give the known (file, startLine, endLine) and optionally pad with contextBefore/contextAfter; out-of-range lines are clamped silently and the returned lineRange reflects the actual slice. Reports estimatedTokens in the same form as ParecodeSearch so you can budget before consuming. Read-only — to change code use ParecodeEdit.

Inputs: file (required), startLine (required), endLine (required), contextBefore, +1 more.

ParecodeSearchA

Search the codebase with ripgrep and get matches plus surrounding context in ONE call — use instead of Grep/Glob-then-Read, a raw rg/grep in the shell, or re-reading the same file at different line ranges. Pass pattern as an array to run several regexes in parallel for flow tracing; each match lists which patterns hit it. Overlapping or adjacent windows in a file are merged (gap ≤ contextLines), and the result carries one envelope-level estimatedTokens so you can budget before consuming. Read-only: widen a match with ParecodeExpand, change code with ParecodeEdit. Per-file content over ~2KB is dropped (lines listed in omittedLineRanges) — widen those via ParecodeExpand rather than re-reading. Repeated calls in a session are token-efficient: previously-returned windows come back as kind: 'reference' placeholders. Only need WHERE, not surrounding code? Add mode: 'locate' for hits-only results (file + line + matched line, no content windows), then ParecodeExpand what matters. Watch warnings — a pattern_directory_collision usually means narrow the pattern first. Needs ripgrep on PATH (run parecode doctor if missing). In CodeGraph repos (.codegraph/), prefer codegraph_explore for broad 'how does X work?' questions; best for targeted multi-pattern lookups.

Inputs: pattern (required), paths, contextLines, maxBytesPerFile, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct purpose: search, expand, and edit. Descriptions clearly differentiate them, with no overlap.

    Naming Consistency5/5

    All tools follow a consistent 'Parecode' prefix with a verb in CamelCase (Search, Expand, Edit).

    Tool Count5/5

    Three tools is appropriate for a focused code manipulation server, covering the core search, read, and edit operations.

    Completeness5/5

    The set provides a complete workflow: search for code, expand to see context, and edit. No obvious gaps for the intended use.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for semantic code search & navigation that helps AI agents work efficiently without burning through costly tokens. Instead of reading entire files, agents can search conceptually and jump directly to the specific functions, classes, and code chunks they need.
      122
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides a persistent sandbox for AI coding agents to explore codebases server-side, returning only compact summaries to reduce context consumption.
      3
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that reduces AI coding agent token usage by 80-99% through a queryable knowledge graph of code, change tracking, and persistent memory across sessions.
      59 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that reduces AI agent token usage by up to 90% through intelligent context compression. Enables efficient code exploration, multi-file refactoring, and debugging by providing tools for smart reading, searching, and managing code context.
      4
      MIT