{"id":50326942,"url":"https://github.com/basilskywalk/parecode","last_synced_at":"2026-06-03T07:02:26.242Z","repository":{"id":360666375,"uuid":"1251157873","full_name":"BasilSkyWalk/parecode","owner":"BasilSkyWalk","description":"MCP server for AST-aware search and safe, atomic multi-file edits.","archived":false,"fork":false,"pushed_at":"2026-05-27T12:02:35.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T12:04:47.088Z","etag":null,"topics":["ast","claude-code","developer-tools","mcp","ripgrep","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BasilSkyWalk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T09:49:43.000Z","updated_at":"2026-05-27T11:24:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/BasilSkyWalk/parecode","commit_stats":null,"previous_names":["basilskywalk/parecode"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/BasilSkyWalk/parecode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasilSkyWalk%2Fparecode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasilSkyWalk%2Fparecode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasilSkyWalk%2Fparecode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasilSkyWalk%2Fparecode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BasilSkyWalk","download_url":"https://codeload.github.com/BasilSkyWalk/parecode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasilSkyWalk%2Fparecode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33852295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","claude-code","developer-tools","mcp","ripgrep","tree-sitter"],"created_at":"2026-05-29T07:04:35.165Z","updated_at":"2026-06-03T07:02:26.237Z","avatar_url":"https://github.com/BasilSkyWalk.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# parecode\n\nAn 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.\n\n[![parecode MCP server](https://glama.ai/mcp/servers/BasilSkyWalk/parecode/badges/card.svg)](https://glama.ai/mcp/servers/BasilSkyWalk/parecode)\n\n---\n\n## Requirements\n\n- **Node.js 20 or newer** (ESM, native test runner, stable `fetch`-free runtime).\n- **[ripgrep](https://github.com/BurntSushi/ripgrep)** on `PATH` (`rg` on Linux/macOS, `rg.exe` on Windows). Install via your package manager:\n  - macOS: `brew install ripgrep`\n  - Debian/Ubuntu: `apt install ripgrep`\n  - Windows: `winget install BurntSushi.ripgrep.MSVC` or `choco install ripgrep`\n- A supported MCP client (Claude Code is the reference target).\n\nParecode does **not** bundle ripgrep — it shells out to the system binary so you stay on a single, audited version.\n\n---\n\n## Install\n\n```sh\nnpm install -g parecode\n```\n\nPure JavaScript — no native dependencies, no C/C++ toolchain required.\n\n---\n\n## Quick start\n\nRegister the server with Claude Code:\n\n```sh\nparecode init                       # user scope; installs MCP + SessionStart hook + parecode-explore plugin (defaults)\nparecode init --scope project       # commit MCP config + hook to the repo\nparecode init --no-hook             # register MCP only; skip the SessionStart hook\nparecode init --no-plugin           # skip the parecode-explore Claude Code plugin\nparecode init --print               # print the equivalent command without running it\nparecode init --remove-hook         # remove the SessionStart hook (MCP stays registered)\nparecode init --remove-plugin       # uninstall the parecode-explore Claude Code plugin\n```\n\nThe 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.\n\nThe 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.\n\nThen in any session, the `ParecodeSearch`, `ParecodeExpand`, and `ParecodeEdit` tools become available. Run `parecode doctor` to confirm registration, hook status, and `.codegraph/` pairing if present.\n\n---\n\n## What it does\n\n- **`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.\n  - `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.\n  - Overlapping or adjacent windows within the same file are merged automatically (gap ≤ `contextLines`), with bridging lines loaded from disk.\n  - Per-match and response-level `estimatedTokens` are returned so the agent can self-budget before consuming results.\n  - Opt-in `relatedSymbols: true` surfaces likely event-flow neighbours (`Handle\u003cX\u003e`, `On\u003cX\u003e`, `\u003cX\u003eHandler/Listener/Closed/Completed/Started`) discovered in each match, capped at 10.\n  - Omitted line ranges are reported so the agent can widen with `ParecodeExpand` without re-reading the whole file.\n- **`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.\n- **`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.\n- **`parecode stats`** — local JSONL session log with token-saved estimates. Zero network. Zero telemetry.\n\n---\n\n## Measured savings\n\nOn 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:\n\n| repo | task | cost | turns |\n|---|---|--:|--:|\n| TypeScript | find every call site of a symbol, edit each (17 sites, 8 files) | −43% | −83% |\n| Unity / C# | find every call site of a symbol, edit each (11 sites, 5 files) | −41% | −76% |\n\n_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._\n\n---\n\n## Retroactive Savings Scan\n\nCurious how much Parecode would have saved you if you had installed it earlier? You can scan your past Claude Code sessions:\n\n```sh\nparecode stats --retroactive --since 30d\n```\n\nSample output:\n```text\nParecode — last 30d (retroactive scan)\n─────────────────────\nSessions:                   42\nTool calls:                156\nCalls batched (est):        89\nTokens saved (est):  1,200,000\n\n* Note: Retroactive savings are estimated, not measured.\n```\n\n**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.\n\n---\n\n## Privacy\n\nParecode 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 \u003cdays\u003e` or wipe the data dir.\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasilskywalk%2Fparecode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasilskywalk%2Fparecode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasilskywalk%2Fparecode/lists"}