Skip to content

Commit 1edccf3

Browse files
author
Martin Vogel
committed
Rewrite installation docs for binary-first onboarding
Lead with pre-built binary download (no toolchain needed), then setup scripts for automation, then build-from-source for contributors. - Add platform table with all 5 targets including linux-arm64 - Add Windows SmartScreen guidance for unsigned binary - Document checksums.txt for integrity verification - Credit @Flipper1994 for WSL2 workaround (closes #1)
1 parent 3c6ad62 commit 1edccf3

1 file changed

Lines changed: 94 additions & 33 deletions

File tree

‎README.md‎

Lines changed: 94 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -47,92 +47,153 @@ Claude Code formats and explains the results.
4747

4848
## Installation
4949

50-
### Quick Install via Claude Code
50+
### Just Want to Get Started?
5151

52-
The fastest way: paste the repo URL directly into Claude Code and ask it to install:
52+
Grab a pre-built binary from the [latest release](https://github.com/DeusData/codebase-memory-mcp/releases/latest) — no Go, no compiler, no git needed.
53+
54+
| Platform | Binary |
55+
|----------|--------|
56+
| macOS (Apple Silicon) | `codebase-memory-mcp-darwin-arm64.tar.gz` |
57+
| macOS (Intel) | `codebase-memory-mcp-darwin-amd64.tar.gz` |
58+
| Linux (x86_64) | `codebase-memory-mcp-linux-amd64.tar.gz` |
59+
| Linux (ARM64 / Graviton) | `codebase-memory-mcp-linux-arm64.tar.gz` |
60+
| Windows (x86_64) | `codebase-memory-mcp-windows-amd64.zip` |
61+
62+
Every release includes a `checksums.txt` with SHA-256 hashes for verification.
63+
64+
**3 steps:**
65+
66+
1. **Download and extract** the binary for your platform
67+
2. **Put it somewhere on your PATH** (e.g. `~/.local/bin/` on macOS/Linux, or any folder on Windows)
68+
3. **Tell Claude Code about it** — add to `.mcp.json` in your project root:
69+
```json
70+
{
71+
"mcpServers": {
72+
"codebase-memory-mcp": {
73+
"type": "stdio",
74+
"command": "/path/to/codebase-memory-mcp"
75+
}
76+
}
77+
}
78+
```
79+
80+
Restart Claude Code, verify with `/mcp`, then say **"Index this project"** — done.
81+
82+
> **Windows note**: Windows SmartScreen may show "Windows protected your PC" when you first run the binary. This is normal for unsigned open-source software. Click **"More info"** then **"Run anyway"**. You can verify the binary integrity using the `checksums.txt` file included in each release.
83+
84+
### Setup Scripts (Automated)
85+
86+
The setup scripts automate download, placement, and Claude Code configuration.
87+
88+
**macOS / Linux:**
89+
90+
```bash
91+
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash
92+
```
93+
94+
**Windows (PowerShell):**
95+
96+
```powershell
97+
irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex
98+
```
99+
100+
The scripts download the correct binary for your platform, install it, and offer to auto-configure Claude Code's MCP settings.
101+
102+
### Install via Claude Code
103+
104+
Or just paste the repo URL into Claude Code:
53105

54106
```
55107
You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"
56108
```
57109

58-
Claude Code will clone, build, and configure the MCP server automatically.
110+
Claude Code will clone, build, and configure it automatically.
111+
112+
### Want to Hack on It? Build from Source
59113

60-
### Prerequisites
114+
<details>
115+
<summary>Prerequisites</summary>
61116

62117
| Requirement | Version | Check | Install |
63118
|-------------|---------|-------|---------|
64119
| **Go** | 1.23+ | `go version` | [go.dev/dl](https://go.dev/dl/) |
65120
| **C compiler** | gcc or clang | `gcc --version` or `clang --version` | See below |
66121
| **Git** | any | `git --version` | Pre-installed on most systems |
67122

68-
**C compiler** is needed because tree-sitter uses CGO (C bindings for AST parsing):
123+
A **C compiler** is needed because tree-sitter uses CGO (C bindings for AST parsing):
69124

70-
- **macOS**: Install Xcode command line tools — `xcode-select --install`. This provides `clang` and is likely already installed.
125+
- **macOS**: `xcode-select --install` (provides `clang`)
71126
- **Linux (Debian/Ubuntu)**: `sudo apt install build-essential`
72127
- **Linux (Fedora/RHEL)**: `sudo dnf install gcc`
73-
- **Windows**: Not currently supported (CGO cross-compilation is complex). Use WSL2 with the Linux instructions above.
128+
- **Windows**: Install [MSYS2](https://www.msys2.org/), then: `pacman -S mingw-w64-ucrt-x86_64-gcc`. Build from an MSYS2 UCRT64 shell.
74129

75-
### Build from Source
130+
</details>
131+
132+
**Via setup script:**
76133

77134
```bash
78-
# Clone the repository
79-
git clone https://github.com/DeusData/codebase-memory-mcp.git
80-
cd codebase-memory-mcp
135+
# macOS / Linux
136+
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash -s -- --from-source
81137

82-
# Build the binary (CGO_ENABLED=1 is the default, but be explicit)
83-
CGO_ENABLED=1 go build -o codebase-memory-mcp ./cmd/codebase-memory-mcp/
138+
# Windows (PowerShell) — builds inside WSL
139+
irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 -OutFile setup.ps1; .\setup.ps1 -FromSource
140+
```
84141

85-
# Option A: Move to a directory on your PATH
86-
sudo mv codebase-memory-mcp /usr/local/bin/
142+
**Or manually:**
87143

88-
# Option B: Or keep it in place and use the absolute path in MCP config
144+
```bash
145+
git clone https://github.com/DeusData/codebase-memory-mcp.git
146+
cd codebase-memory-mcp
147+
CGO_ENABLED=1 go build -o codebase-memory-mcp ./cmd/codebase-memory-mcp/
148+
# Move the binary to somewhere on your PATH
89149
```
90150

91-
### Verify
151+
On **Windows with MSYS2** (from a UCRT64 shell):
92152

93153
```bash
94-
# Should print nothing and wait for stdio input (Ctrl+C to exit)
95-
codebase-memory-mcp
154+
CGO_ENABLED=1 CC=gcc go build -o codebase-memory-mcp.exe ./cmd/codebase-memory-mcp/
96155
```
97156

98-
### Configure Claude Code
157+
On **Windows with WSL** (credit: [@Flipper1994](https://github.com/Flipper1994)):
99158

100-
Add the MCP server to your project's `.mcp.json` (per-project) or `~/.claude/settings.json` (global):
159+
```bash
160+
# Inside WSL (Ubuntu)
161+
sudo apt update && sudo apt install build-essential
162+
# Install Go 1.23+ from https://go.dev/dl/
163+
git clone https://github.com/DeusData/codebase-memory-mcp.git
164+
cd codebase-memory-mcp
165+
CGO_ENABLED=1 go build -buildvcs=false -o ~/.local/bin/codebase-memory-mcp ./cmd/codebase-memory-mcp/
166+
```
101167

102-
**Per-project** (`.mcp.json` in project root — recommended):
168+
When using a WSL-built binary, configure Claude Code to invoke it via `wsl.exe`:
103169

104170
```json
105171
{
106172
"mcpServers": {
107173
"codebase-memory-mcp": {
108174
"type": "stdio",
109-
"command": "/usr/local/bin/codebase-memory-mcp"
175+
"command": "wsl.exe",
176+
"args": ["-d", "Ubuntu", "--", "/home/YOUR_USER/.local/bin/codebase-memory-mcp"]
110177
}
111178
}
112179
}
113180
```
114181

115-
**Global** (`~/.claude/settings.json`):
182+
### Configure Claude Code
183+
184+
Add the MCP server to your project's `.mcp.json` (per-project, recommended) or `~/.claude/settings.json` (global):
116185

117186
```json
118187
{
119188
"mcpServers": {
120189
"codebase-memory-mcp": {
121190
"type": "stdio",
122-
"command": "/usr/local/bin/codebase-memory-mcp"
191+
"command": "/path/to/codebase-memory-mcp"
123192
}
124193
}
125194
}
126195
```
127196

128-
If you kept the binary in the cloned directory, use the full path instead:
129-
130-
```json
131-
{
132-
"command": "/path/to/codebase-memory-mcp/codebase-memory-mcp"
133-
}
134-
```
135-
136197
Restart Claude Code after adding the config. Verify with `/mcp` — you should see `codebase-memory-mcp` listed with 11 tools.
137198

138199
### First Use

0 commit comments

Comments
 (0)