Codehelper

Codehelper

Local-first repo intelligence for AI coding assistants.

Codehelper indexes git repositories on your machine, builds a symbol and call graph, and exposes 60+ MCP tools so Cursor, Claude Code, Codex, and other MCP clients can search, understand, and safely change your code — without uploading the whole repo to a cloud model.

---

Three reasons to use Codehelper

1. Project-aware agents — Search symbols, callers, and blast radius locally instead of grepping whole files.
2. Works offline — No API keys; your code stays on your machine.
3. Fits your editor — MCP for Cursor, Claude Code, Codex; one codehelper init per repo.

---

Installation

Linux / macOS (recommended):

curl -fsSL https://raw.githubusercontent.com/VeyrForge/codehelper/main/scripts/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

From source (requires Go 1.25+, CGO, and a C compiler):

git clone https://github.com/VeyrForge/codehelper.git && cd codehelper
npm run build

Prebuilt 3.0.3 bundles (Linux, macOS, Windows) include codehelper, MCP server, ge 1.1.1, and greencompress 1.1.1 on GitHub Releases.

Updates: codehelper upgrade downloads the latest release from VeyrForge/codehelper by default. Override the upgrade source with --repo owner/name or CODEHELPER_UPGRADE_REPO. codehelper update rebuilds from a local git checkout and works from any directory (remembers the source path, or use CODEHELPER_SOURCE / update /path/to/codehelper).

---

30-second example

cd your-git-repo
codehelper init
codehelper help tools --main

Reload Cursor or Claude Code after the first init, then call project_context once per session so the agent knows which tools exist and how fresh the index is.

---

See it work

No bundled demo video yet — here is a typical first session:

$ codehelper init
init: ready — index + watch daemon active

$ codehelper status
symbols: 1247  edges: 3891  freshness: current

$ codehelper help tools --main
  project_context  bootstrap tool catalog + index stats
  query            search the symbol graph
  context          source + callers + callees
  impact           blast radius before you edit

Benchmark methodology (no invented competitor numbers): docs/BENCHMARK_COMPARISON.md.

---

Supported platforms

Platform	Install	Notes
Linux	scripts/install.sh	Full support; primary CI target
macOS	scripts/install.sh	Universal + per-arch release binaries
Windows	scripts/install.ps1	x64 supported

Client	Setup
Cursor	Per-project .mcp.json via codehelper init
Claude Code	Managed block in ~/.claude.json
Codex	Reads generated AGENTS.md

---

How it works

Layer	Technology
Indexing	tree-sitter parsers + SQLite symbol/call graph
Search	BM25 + trigrams + call-graph ranking (optional local semantic rerank — docs/LOCAL_EMBED.md)
MCP transport	stdio (default) or HTTP (codehelper mcp --http :8765)
Optional local models	Green Engine embed/chat + Green Compress weights

init indexes the repo, starts the watch daemon, wires MCP for your editor, and writes agent rules. Optional local dashboard: ge ui serve → http://127.0.0.1:8780

Full tool reference: docs/MCP_TOOLS.md

---

Benchmarks

See docs/BENCHMARK_COMPARISON.md for competitor-comparison methodology (arms, metrics, bed tiers — no invented competitor numbers). Fill measured cells from reproducible local harness runs only.

Caveats: many published tables are self-repo (this tree) or methodology-lite paired locate probes (MCP vs host file walk). Those are not end-to-end coding-assistant issue-fix rates. Prefer multi-bed hold-outs (CODEHELPER_TESTBEDS) and fill competitor cells only from local re-runs.

# One recipe: prepare + paired + dated report
scripts/testbeds-all.sh
scripts/testbeds-all.sh fixture   # always-safe, no beds

Layout and prepare/eval usage: docs/TESTBEDS.md.

---

Documentation

• docs/MCP_TOOLS.md — MCP tool reference
• docs/BENCHMARK_COMPARISON.md — benchmark methodology + harness (no fake competitor numbers)
• CHANGELOG.md — version history
• third_party/README.md — bundled Green stack binaries

---

Limitations

• Requires a git repository for indexing.
• CGO and a C compiler are required to build from source (tree-sitter).
• Semantic rerank: optional tiny local embed path (bash scripts/install-local-embed.sh / codehelper green init-embed) — see docs/LOCAL_EMBED.md. Enrichment needs optional local model services (Green Engine).
• Windows arm64 CI is experimental/non-blocking (windows-11-arm). Releases always ship Windows amd64; a *_windows_universal.zip is published only when both amd64 and arm64 builds succeed (historical *_windows_universal.zip assets through v3.0.2 were amd64-sized and should not be treated as true universal).

---

Contributing

Bug reports, benchmark results, compatibility notes, and suggested improvements are welcome on the official VeyrForge/codehelper repository.

Pull requests improving Codehelper are welcome. By contributing, you agree to the Contributor License Agreement. You may also keep private/internal forks for your own deployment under the BUSL-1.1 Additional Use Grant. Do not offer Codehelper (or a substantially similar substitute) to third parties as a hosted or competing product. See License and permitted use and LICENSE-FAQ.md.

---

Public release history

See CHANGELOG.md and GitHub Releases.

---

License and permitted use

Codehelper is source-available under the Business Source License 1.1 (BUSL-1.1). It is not OSI open source until the Change License applies.

You may:

• Use and run Codehelper (including in production) for personal use or internal business purposes (including employees and contractors acting on your behalf)
• Copy, modify, and create derivative works for those same purposes — without having to contribute changes back
• Use Codehelper to develop, test, maintain, review, or operate software for yourself or your customers (without offering Codehelper itself as a product or service)
• Study the published source

You may not (until the Change License applies):

• Offer Codehelper or a modified version to third parties as a hosted, managed, embedded, or distributed product or service whose primary purpose is to provide functionality substantially similar to Codehelper as a substitute
• Sell a renamed fork or embed Codehelper as the main feature of another paid product without a commercial license

Change Date: 2029-07-24 — on that date, or the fourth anniversary of the first public BSL distribution of this version (whichever is earlier), this version becomes available under Apache License 2.0.

Tutorials and blog posts may include short illustrative snippets from the published source for explanation, provided they do not redistribute the software as a competing product or imply an OSI open-source grant before the Change Date.

For commercial redistribution, OEM licensing, or other usage not covered above, contact [email protected].

This section is a plain-language summary. The binding terms are in LICENSE. Interpretive Q&A: LICENSE-FAQ.md. See also CLA.md, SECURITY.md, docs/PERMISSIONS.md, and docs/ROADMAP.md.