{
  "markdown": "# Codehelper\n\n**Local-first repo intelligence for AI coding assistants.**\n\nCodehelper 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.\n\n[![Version](https://img.shields.io/badge/version-3.0.3-blue)](VERSION)\n[![Go](https://img.shields.io/badge/go-1.25+-00ADD8)](https://go.dev/)\n[![MCP](https://img.shields.io/badge/MCP-server-purple)](https://modelcontextprotocol.io/)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.VeyrForge%2Fcodehelper-0A7)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.VeyrForge/codehelper)\n[![License: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-orange)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey)](#supported-platforms)\n[![Glama score](https://glama.ai/mcp/servers/VeyrForge/codehelper/badges/score.svg)](https://glama.ai/mcp/servers/VeyrForge/codehelper)\n\n[![Glama](https://glama.ai/mcp/servers/VeyrForge/codehelper/badges/card.svg)](https://glama.ai/mcp/servers/VeyrForge/codehelper)\n\n---\n\n## Three reasons to use Codehelper\n\n1. **Project-aware agents** — Search symbols, callers, and blast radius locally instead of grepping whole files.\n2. **Works offline** — No API keys; your code stays on your machine.\n3. **Fits your editor** — MCP for Cursor, Claude Code, Codex; one `codehelper init` per repo.\n\n---\n\n## Installation\n\n**Linux / macOS (recommended):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/VeyrForge/codehelper/main/scripts/install.sh | sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\install.ps1\n```\n\n**From source** (requires Go 1.25+, CGO, and a C compiler):\n\n```bash\ngit clone https://github.com/VeyrForge/codehelper.git && cd codehelper\nnpm run build\n```\n\nPrebuilt **3.0.3** bundles (Linux, macOS, Windows) include `codehelper`, MCP server, **`ge` 1.1.1**, and **`greencompress` 1.1.1** on [GitHub Releases](https://github.com/VeyrForge/codehelper/releases).\n\n**Updates:** `codehelper upgrade` downloads the latest release from [VeyrForge/codehelper](https://github.com/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`).\n\n---\n\n## 30-second example\n\n```bash\ncd your-git-repo\ncodehelper init\ncodehelper help tools --main\n```\n\nReload 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.\n\n---\n\n## See it work\n\nNo bundled demo video yet — here is a typical first session:\n\n```text\n$ codehelper init\ninit: ready — index + watch daemon active\n\n$ codehelper status\nsymbols: 1247  edges: 3891  freshness: current\n\n$ codehelper help tools --main\n  project_context  bootstrap tool catalog + index stats\n  query            search the symbol graph\n  context          source + callers + callees\n  impact           blast radius before you edit\n```\n\nBenchmark methodology (no invented competitor numbers): [docs/BENCHMARK_COMPARISON.md](docs/BENCHMARK_COMPARISON.md).\n\n---\n\n## Supported platforms\n\n| Platform | Install | Notes |\n|----------|---------|-------|\n| **Linux** | `scripts/install.sh` | Full support; primary CI target |\n| **macOS** | `scripts/install.sh` | Universal + per-arch release binaries |\n| **Windows** | `scripts/install.ps1` | x64 supported |\n\n| Client | Setup |\n|--------|--------|\n| **Cursor** | Per-project `.mcp.json` via `codehelper init` |\n| **Claude Code** | Managed block in `~/.claude.json` |\n| **Codex** | Reads generated `AGENTS.md` |\n\n---\n\n## How it works\n\n| Layer | Technology |\n|-------|------------|\n| Indexing | [tree-sitter](https://tree-sitter.github.io/) parsers + SQLite symbol/call graph |\n| Search | BM25 + trigrams + call-graph ranking (optional local semantic rerank — [docs/LOCAL_EMBED.md](docs/LOCAL_EMBED.md)) |\n| MCP transport | stdio (default) or HTTP (`codehelper mcp --http :8765`) |\n| Optional local models | [Green Engine](https://github.com/VeyrForge/GreenEngine) embed/chat + [Green Compress](https://github.com/VeyrForge/GreenCompress) weights |\n\n`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\n\nFull tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)\n\n---\n\n## Benchmarks\n\nSee [docs/BENCHMARK_COMPARISON.md](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.\n\n**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.\n\n```bash\n# One recipe: prepare + paired + dated report\nscripts/testbeds-all.sh\nscripts/testbeds-all.sh fixture   # always-safe, no beds\n```\n\nLayout and prepare/eval usage: [docs/TESTBEDS.md](docs/TESTBEDS.md).\n\n---\n\n## Documentation\n\n- [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) — MCP tool reference\n- [docs/BENCHMARK_COMPARISON.md](docs/BENCHMARK_COMPARISON.md) — benchmark methodology + harness (no fake competitor numbers)\n- [CHANGELOG.md](CHANGELOG.md) — version history\n- [third_party/README.md](third_party/README.md) — bundled Green stack binaries\n\n---\n\n## Limitations\n\n- Requires a **git** repository for indexing.\n- **CGO** and a C compiler are required to build from source (tree-sitter).\n- Semantic rerank: optional tiny local embed path (`bash scripts/install-local-embed.sh` / `codehelper green init-embed`) — see [docs/LOCAL_EMBED.md](docs/LOCAL_EMBED.md). Enrichment needs optional local model services ([Green Engine](https://github.com/VeyrForge/GreenEngine)).\n- 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).\n\n---\n\n## Contributing\n\nBug reports, benchmark results, compatibility notes, and suggested improvements are welcome on the official [VeyrForge/codehelper](https://github.com/VeyrForge/codehelper) repository.\n\nPull requests improving Codehelper are welcome. By contributing, you agree to the [Contributor License Agreement](CLA.md). You may also keep private/internal forks for your own deployment under the [BUSL-1.1](LICENSE) 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](#license-and-permitted-use) and [LICENSE-FAQ.md](LICENSE-FAQ.md).\n\n---\n\n## Public release history\n\nSee [CHANGELOG.md](CHANGELOG.md) and [GitHub Releases](https://github.com/VeyrForge/codehelper/releases).\n\n---\n\n## License and permitted use\n\nCodehelper is **source-available** under the **Business Source License 1.1** ([BUSL-1.1](LICENSE)). It is not OSI open source until the Change License applies.\n\n**You may:**\n\n- Use and run Codehelper (including in production) for personal use or internal business purposes (including employees and contractors acting on your behalf)\n- Copy, modify, and create derivative works for those same purposes — **without** having to contribute changes back\n- Use Codehelper to develop, test, maintain, review, or operate software for yourself or your customers (without offering Codehelper itself as a product or service)\n- Study the published source\n\n**You may not** (until the Change License applies):\n\n- 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\n- Sell a renamed fork or embed Codehelper as the main feature of another paid product without a commercial license\n\n**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**.\n\nTutorials 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.\n\nFor commercial redistribution, OEM licensing, or other usage not covered above, contact **licensing@veyrforge.com**.\n\nThis section is a plain-language summary. The binding terms are in [LICENSE](LICENSE). Interpretive Q&A: [LICENSE-FAQ.md](LICENSE-FAQ.md). See also [CLA.md](CLA.md), [SECURITY.md](SECURITY.md), [docs/PERMISSIONS.md](docs/PERMISSIONS.md), and [docs/ROADMAP.md](docs/ROADMAP.md).\n",
  "bytes": 9269,
  "sha": "d42bc973c7c139cddc550c64e2cfccf3ef97dd11156e019ca6e2f3f4bdd93b6a",
  "repo_slug": "veyrforge/codehelper",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_veyrforge_codehelper_6b19f845/readme"
}