Parecode is a context-window-aware code search and editing MCP server that reduces token usage on large codebases while maintaining correctness. All processing is local with no network calls.
ParecodeSearch — Ripgrep-backed regex searches returning matches with surrounding context in a single call:
Pass an array of patterns for parallel searches (e.g., tracing event flows like ['HandleX', 'OnX', 'XClosed'])
Automatically merges overlapping/adjacent match windows within the same file
Returns estimatedTokens at match and response level for agent self-budgeting
Optionally surfaces related symbols via relatedSymbols: true
Reports omitted line ranges when per-file content exceeds the byte cap
Deduplicates repeated windows across calls using lightweight kind: 'reference' placeholders
ParecodeExpand — Read a specific line range without loading the whole file:
Natural follow-up to a ParecodeSearch match or omittedLineRanges entry
Supports optional contextBefore / contextAfter padding
Returns estimatedTokens consistent with ParecodeSearch
ParecodeEdit — Batch atomic edits across multiple files in a single call:
Cross-file operations run in parallel
Supports line-range operations (replaceLines, insertAfter) anchored by an expect guard to detect drift
Supports string-patch operations (oldString / newString) with optional fuzzy matching
Fuzzy modes: whitespace-tolerant (fuzzy: true) or Unicode normalization (fuzzy: 'aggressive'); matches below 0.85 confidence are rejected
Atomic writes per file (temp + rename) with mtime-based conflict detection
Claude Code Integration — Registers a SessionStart hook to prefer Parecode tools over native ones, plus a parecode-explore plugin for cost-effective exploration via a dedicated read-only subagent.
Usage Statistics (parecode stats) — Local JSONL session log estimating tokens saved, with retroactive scanning of past Claude Code sessions (e.g., parecode stats --retroactive --since 30d). Zero network calls, zero telemetry.
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.
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
npm install -g parecodePure JavaScript — no native dependencies, no C/C++ toolchain required.
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 pluginThe 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.
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.
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.
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 30dSample 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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| edits | Yes | List of edit operations to perform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: per-file atomicity, conflict detection, error statuses (snippet_mismatch, fuzzy_match_failed), anchor relocation, fuzzy matching tolerance, and indentation adoption. It covers safety and failure modes comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the core purpose, but it is long. Every sentence adds value, though some could be more succinct. Overall well-structured but slightly verbose for the amount of information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, no annotations, and no output schema, the description is remarkably complete. It covers purpose, usage guidelines, detailed parameter semantics, behavioral traits, and error handling. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds substantial meaning beyond the schema by explaining the trade-offs between line-range and string-patch ops, the details of expect anchor behavior, fuzzy matching nuances, and per-file atomicity. It provides context that the schema alone does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it applies many edits across many files, identifies itself as the edit counterpart to ParecodeSearch/ParecodeExpand, and lists specific use cases (2+ edits to one file, edits across files, one logical revision). This distinguishes it from siblings and provides a clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives when to prefer this tool over alternatives (native Edit/MultiEdit) and provides detailed guidance on choosing between line-range ops and string-patch ops, including when to use each and the behavior of expect anchors and fuzzy matching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the file to read (typically the `file` from a ParecodeSearch match). | |
| startLine | Yes | Starting line (1-based, inclusive) | |
| endLine | Yes | Ending line (1-based, inclusive) | |
| contextBefore | No | Additional lines to include before startLine. Default 0. | |
| contextAfter | No | Additional lines to include after endLine. Default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully covers behaviors: silent clamping of out-of-range lines, returned lineRange reflects actual slice, reports estimatedTokens, and read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-sentence description that is front-loaded with purpose and efficiently covers all key aspects without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description mentions returned values (lineRange, estimatedTokens) and behavior. Could be slightly more detailed on return structure, but sufficient given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds context above schema by explaining how parameters relate to search matches and padding behavior, though some parameter details are already clear from schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a specific line range of a file and positions it as a follow-up to ParecodeSearch, distinguishing it from siblings like ParecodeEdit and full-file reads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use (as follow-up to ParecodeSearch) and when not (instead of full-file Read), and mentions alternative ParecodeEdit for changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | Ripgrep regex pattern, or an array of patterns to dispatch in parallel. Each match reports which input pattern(s) contributed via 'patterns'. | |
| paths | No | Directory or file paths to restrict the search. Defaults to the current working directory. | |
| contextLines | No | Number of context lines to include around matches. Defaults to 2. Also controls window-merge threshold within a file. | |
| maxBytesPerFile | No | Soft cap on bytes returned per file; above it, output is chunked around match centers and the trimmed lines are reported in omittedLineRanges (widen them with ParecodeExpand). | |
| relatedSymbols | No | Opt-in: scan each match's content for likely related symbols (Handle<X>, On<X>, <X>Handler, <X>Listener, <X>Closed/Completed/Started). Returns deduped, lexically sorted, capped at 10 per match. | |
| mode | No | Set to 'locate' to return only hit locations (file + line + matched line) with no content windows — the lean option for broad fan-out searches across many files. Follow up with ParecodeExpand on the locations you care about. Omit for the default windowed result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behaviors: read-only operation, estimatedTokens for budgeting, per-file content truncation with omittedLineRanges, deduplication via 'reference' placeholders, warning about pattern_directory_collision, and dependency on ripgrep. This fully covers what an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the primary purpose and alternatives. Every sentence provides value, but it is relatively long; slight reduction could improve conciseness without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no output schema), the description is complete. It covers behavior, output structure (estimatedTokens, omittedLineRanges, reference placeholders), error warnings, dependencies, and alternatives. Compensates well for the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has 100% coverage, the description adds significant meaning beyond the schema: explains pattern array for parallel flow tracing, contextLines also controls window-merge threshold, mode 'locate' for lean results, and relatedSymbols scans for specific symbol patterns. This greatly aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the codebase with ripgrep and returns matches with context in one call. It explicitly distinguishes from alternatives like Grep/Glob-then-Read, raw rg/grep, and re-reading files, using specific verbs like 'Search' and 'use instead of'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool and when to use alternatives: ParecodeExpand for widening matches, ParecodeEdit for code changes, and codegraph_explore for broad questions. Also explains the 'locate' mode for lean searches and mentions 'doctor' for troubleshooting missing ripgrep.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.9.1ParecodeEdit3 fields changedInput schema / properties / edits / items / properties / expect / descriptionPrevious value: -"Anchor verifying the target before any write: the trimmed first line, or first and last line joined by `\\n…\\n` for ranges. If the lines drifted it is re-located by fuzzy match within ±20 lines at ≥0.85 confidence; if not found, the op returns snippet_mismatch and nothing in that file is written."New value: +"Anchor verifying the target before any write: the trimmed first line, or first and last line joined by `\\n…\\n` for ranges. If the lines drifted, the first-line anchor is re-located within ±20 lines, the range keeps its original length, and the last-line anchor is re-verified at the new position. Relocating a multi-line replaceLines range requires the two-ended (`\\n…\\n`) form — a single-line anchor that has drifted returns snippet_mismatch rather than overwriting an unverified range. If the anchor is missing or matches more than one nearby location, the op returns snippet_mismatch and nothing in that file is written."Input schema / properties / edits / items / properties / file / descriptionPrevious value: -"Path (absolute or relative) to the file to edit. Edits are grouped by file and applied all-or-nothing per file; the per-file status is one of success, conflict (file changed underneath the edit), error, snippet_mismatch, or fuzzy_match_failed."New value: +"Path (absolute or relative) to the file to edit. Edits are grouped by file and applied all-or-nothing per file; the per-file status is one of success, conflict (file changed underneath the edit), error, snippet_mismatch, or fuzzy_match_failed. On snippet_mismatch the op result carries an `actual` snapshot (line-numbered current contents at the target) so you can correct the anchor/line numbers in place without re-reading the file."Input schema / properties / edits / items / properties / fuzzy / descriptionPrevious value: -"String-patch tolerance: true = whitespace-insensitive matching; 'aggressive' = also normalize Unicode look-alikes (NFKD). Below 0.85 confidence it fails closed (fuzzy_match_failed) rather than guessing. Omit for exact-only matching."New value: +"String-patch tolerance: true = whitespace-insensitive matching; 'aggressive' = also normalize Unicode look-alikes (NFKD). Beyond whitespace it tolerates only ~5% character drift — short strings must match exactly after whitespace normalization — and it fails closed (fuzzy_match_failed) rather than guessing; if several locations match, the op errors out instead of picking one. Replacements adopt the file's existing indentation when it differs from oldString. Omit for exact-only matching."ParecodeSearch1 field changedInput schema / properties / modeAdded value: +{
+ "description": "Set to 'locate' to return only hit locations (file + line + matched line) with no content windows — the lean option for broad fan-out searches across many files. Follow up with ParecodeExpand on the locations you care about. Omit for the default windowed result.",
+ "enum": [
+ "locate"
+ ],
+ "type": "string"
+}v0.5.1ParecodeEditParecodeExpandParecodeSearchEach tool has a distinct purpose: search, expand, and edit. Descriptions clearly differentiate them, with no overlap.
All tools follow a consistent 'Parecode' prefix with a verb in CamelCase (Search, Expand, Edit).
Three tools is appropriate for a focused code manipulation server, covering the core search, read, and edit operations.
The set provides a complete workflow: search for code, expand to see context, and edit. No obvious gaps for the intended use.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives your AI access to the source code and docs of all public github repos
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/BasilSkyWalk/parecode'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
