Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/basilskywalk/parecode

MCP server for AST-aware search and safe, atomic multi-file edits.
https://github.com/basilskywalk/parecode

ast claude-code developer-tools mcp ripgrep tree-sitter

Last synced: 22 days ago
JSON representation

MCP server for AST-aware search and safe, atomic multi-file edits.

Awesome Lists containing this project

README 

          
# 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](https://glama.ai/mcp/servers/BasilSkyWalk/parecode/badges/card.svg)](https://glama.ai/mcp/servers/BasilSkyWalk/parecode)



---



## Requirements



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

- **[ripgrep](https://github.com/BurntSushi/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.



---



## Install



```sh

npm install -g parecode

```



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



---



## Quick start



Register the server with Claude Code:



```sh

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`, `On`, `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:



```sh

parecode stats --retroactive --since 30d

```



Sample output:

```text

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`](https://github.com/sindresorhus/env-paths)) with `0600` permissions on Unix. Prune with `parecode prune ` or wipe the data dir.



---



## License



[MIT](LICENSE)