Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 25 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,20 +63,34 @@
| Singleton MCP with PID lock + 1h idle timeout | |
| Sensitive file blocking (.env, credentials, keys) | |
| Codesigned macOS ARM64 binary; Intel slice temporarily unsigned | |
| SHA256 checksum verification in installer | |
| Cross-platform: macOS (ARM/x86), Linux (ARM/x86) | |
| SHA256-verified release downloads and npm packages | |
| Cross-platform: macOS (ARM/x86), Linux (ARM/x86), Windows (x86_64) | |

---

## ⚡ Install

### macOS and Linux

```bash
curl -fsSL https://codedb.codegraff.com/install.sh | bash
```

Downloads the binary for your platform and auto-registers codedb as an MCP server in **Claude Code**, **Codex**, **Gemini CLI**, **Cursor**, **Windsurf**, and **Devin** — each written directly and additively into that tool's config (only when the tool is present). The installer prints the exact `codedb mcp` command it registered plus hook setup pointers for Codex and Claude Code.

### Or via npm/npx (zero-install for MCP clients)
On Windows, run this command inside WSL only if you want the Linux binary inside WSL. For the native Windows binary, use PowerShell below.

### Windows

Run in PowerShell:

```powershell
irm https://raw.githubusercontent.com/justrach/codedb/main/install/install.ps1 | iex
```

Run the same command again to update codedb.

### npm/npx on macOS and Linux

```bash
npx -y codedeebee mcp
Expand Down Expand Up @@ -106,14 +120,16 @@ Useful for MCP clients (Claude Code, Cursor, opencode, Claude Desktop) that alre

### Updating or repairing an older install

If `codedb update` fails on an older release, rerun the installer:
On macOS or Linux, if `codedb update` fails on an older release, rerun the installer:

```bash
curl -fsSL https://codedb.codegraff.com/install.sh | bash
```

This replaces the `codedb` binary with the latest GitHub Release and keeps your existing MCP registrations, config, caches, and snapshots. Use this path for any release whose built-in updater cannot fetch release checksums.

On native Windows, self-update is not yet supported. Rerun the PowerShell installer above to update or repair the binary.

## Documentation

- **[MCP setup](docs/mcp.md)** — per-client configurations (Claude Desktop, Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI), root resolution, troubleshooting
Expand All @@ -129,16 +145,17 @@ This replaces the `codedb` binary with the latest GitHub Release and keeps your
| macOS x86_64 (Intel) | `codedb-darwin-x86_64` | temporarily unsigned |
| Linux ARM64 | `codedb-linux-arm64` | — |
| Linux x86_64 | `codedb-linux-x86_64` | — |
| Windows x86_64 | `codedb-windows-x86_64.exe` | SHA256 verified automatically |

Or install manually from [GitHub Releases](https://github.com/justrach/codedb/releases/latest).
Or install manually from [GitHub Releases](https://github.com/justrach/codedb/releases/latest). Always verify the binary against the attached `checksums.sha256` before running it.

---

## ⚡ Quick Start

### As an MCP server (recommended)

After installing, codedb is automatically registered. Just open a project and the 21 MCP tools are available to your AI agent.
The macOS/Linux shell installer registers codedb automatically. For npm/npx installs on macOS/Linux and manual Windows installs, use the MCP configuration above or the client-specific examples in [docs/mcp.md](docs/mcp.md). Then open a project and the 21 MCP tools are available to your AI agent.

```bash
# Manual MCP start (auto-configured by install script)
Expand Down Expand Up @@ -244,7 +261,7 @@ For Codex and Claude Code hook examples around `codedb_remote`, see [`docs/hooks
| `codedb snapshot` | Write codedb.snapshot to project root |
| `codedb serve` | HTTP daemon on :7719 |
| `codedb mcp [path]` | JSON-RPC/MCP server over stdio |
| `codedb update` | Self-update to the latest release; if it fails on an older build, rerun the curl installer above |
| `codedb update` | Self-update to the latest release on macOS/Linux; on Windows rerun the PowerShell installer |
| `codedb nuke` | Uninstall codedb, remove caches/snapshots, and deregister MCP integrations |
| `codedb --version` | Print version |

Expand Down Expand Up @@ -474,6 +491,7 @@ Binary: `zig-out/bin/codedb`
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-linux
zig build -Doptimize=ReleaseFast -Dtarget=aarch64-linux
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-macos
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-windows
```

### Releasing
Expand Down
48 changes: 33 additions & 15 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,32 +16,48 @@ scan, and the most common failure modes.

---

## 1. Quick install (auto-configures all detected clients)
## 1. Quick install

### macOS and Linux (auto-configures detected clients)

```bash
curl -fsSL https://codedb.codegraff.com/install.sh | bash
```

The installer downloads the binary for your platform, drops it in
`~/.local/bin/` (or `/usr/local/bin/` on root installs), and auto-registers
The installer downloads the binary for your platform, drops it in `~/bin`
(or `$CODEDB_DIR` when set), and auto-registers
codedb as an MCP server in every client it can find — Claude Code, Codex,
Gemini CLI, Cursor, opencode. It prints the exact `codedb mcp` command it
Gemini CLI, Cursor, Windsurf, and Devin. It prints the exact `codedb mcp` command it
registered.

### Windows x86_64 (native)

Run in PowerShell:

```powershell
irm https://raw.githubusercontent.com/justrach/codedb/main/install/install.ps1 | iex
```

The shell installer is for macOS/Linux; running it in WSL installs the Linux binary inside WSL, not the native Windows binary.

If you prefer to wire it up by hand, the client-specific snippets below
all work directly.

---

## 2. Client-specific configuration

All clients launch `codedb mcp` as a stdio child process. Replace
`/usr/local/bin/codedb` with `which codedb` output on your system.
All clients launch `codedb mcp` as a stdio child process. Find a global install with `command -v codedb` on macOS/Linux. On Windows, the default path is `C:\Users\<you>\AppData\Local\Programs\codedb\codedb.exe`.

The examples below use `/absolute/path/to/codedb`; replace it with the path for your installation. In JSON on Windows, escape backslashes, for example `C:\\Users\\you\\AppData\\Local\\Programs\\codedb\\codedb.exe`.

### Claude Code

```bash
claude mcp add codedb -s user -- /usr/local/bin/codedb mcp
claude mcp add codedb -s user -- /absolute/path/to/codedb mcp

# Windows PowerShell
claude mcp add codedb -s user -- "$env:LOCALAPPDATA\Programs\codedb\codedb.exe" mcp
```

Or edit `~/.claude.json` directly:
Expand All @@ -50,14 +66,14 @@ Or edit `~/.claude.json` directly:
{
"mcpServers": {
"codedb": {
"command": "/usr/local/bin/codedb",
"command": "/absolute/path/to/codedb",
"args": ["mcp"]
}
}
}
```

Verify: `claude mcp list` should show `codedb: /usr/local/bin/codedb mcp - ✓ Connected`.
Verify with `claude mcp list`; the `codedb` entry should report `Connected`.

### Claude Desktop

Expand All @@ -68,7 +84,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
{
"mcpServers": {
"codedb": {
"command": "/usr/local/bin/codedb",
"command": "/absolute/path/to/codedb",
"args": ["mcp"]
}
}
Expand All @@ -86,7 +102,7 @@ Edit `~/.cursor/mcp.json` (per-user) or `<project>/.cursor/mcp.json`
{
"mcpServers": {
"codedb": {
"command": "/usr/local/bin/codedb",
"command": "/absolute/path/to/codedb",
"args": ["mcp"]
}
}
Expand All @@ -104,7 +120,10 @@ Same `mcpServers` block as Cursor, scoped to whichever extension you use.
### Codex CLI

```bash
codex mcp add codedb -- /usr/local/bin/codedb mcp
codex mcp add codedb -- /absolute/path/to/codedb mcp

# Windows PowerShell
codex mcp add codedb -- "$env:LOCALAPPDATA\Programs\codedb\codedb.exe" mcp
```

### Gemini CLI / opencode
Expand All @@ -116,7 +135,7 @@ Both read MCP configuration from `~/.gemini/mcp.json` (Gemini) and
{
"mcpServers": {
"codedb": {
"command": "/usr/local/bin/codedb",
"command": "/absolute/path/to/codedb",
"args": ["mcp"]
}
}
Expand Down Expand Up @@ -213,8 +232,7 @@ Fixed in v0.2.5815 — `codedb_find` now accepts `query`, `name`, `path`,
### Tools list looks short / `codedb_context` is missing

`codedb_context` was added in **v0.2.5815**. Older binaries expose only
20 tools. Upgrade with `codedb update` (or the installer one-liner above)
and verify with `codedb --version`.
20 tools. On macOS/Linux, upgrade with `codedb update` (or the installer one-liner above). On Windows, rerun the verified PowerShell installer and verify with `codedb --version`.

### Snapshot indexer keeps re-scanning

Expand Down
141 changes: 141 additions & 0 deletions install/install.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
[CmdletBinding()]
param(
[string]$Version = $env:CODEDB_VERSION,
[string]$InstallDir = $env:CODEDB_DIR,
[switch]$NoPath
)

Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"

$repo = "justrach/codedb"
$assetName = "codedb-windows-x86_64.exe"
$baseUrl = if ($env:CODEDB_URL) { $env:CODEDB_URL.TrimEnd("/") } else { "https://codedb.codegraff.com" }

if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
throw "This installer is for native Windows. Use install.sh on macOS or Linux."
}

$architecture = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString()
if ($architecture -ne "X64") {
throw "Unsupported Windows architecture: $architecture (x86_64 is required)"
}

if (-not $InstallDir) {
$InstallDir = Join-Path $env:LOCALAPPDATA "Programs\codedb"
}
$InstallDir = [IO.Path]::GetFullPath($InstallDir)
if ($env:CODEDB_NO_PATH) {
$NoPath = $true
}

if (-not $Version) {
try {
$release = Invoke-RestMethod `
-Headers @{ "User-Agent" = "codedb-installer" } `
"https://api.github.com/repos/$repo/releases/latest"
Comment on lines +34 to +36

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Enable TLS before resolving the release version

In Windows PowerShell 5.1 environments where ServicePointManager.SecurityProtocol does not already include TLS 1.2, this first Invoke-RestMethod still negotiates with the obsolete default because the TLS 1.2 setup runs later at lines 50-56. That means both the GitHub release lookup and the latest.json fallback can fail before the installer reaches the download step, so the documented PowerShell one-liner exits without installing; move the TLS-enabling block above this first network call.

Useful? React with 👍 / 👎.

$Version = $release.tag_name
} catch {
$latest = Invoke-RestMethod `
-Headers @{ "User-Agent" = "codedb-installer" } `
"$baseUrl/latest.json"
$Version = $latest.version
}
}
$Version = $Version.TrimStart("v", "V")
if ($Version -notmatch '^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$') {
throw "Invalid codedb version: $Version"
}

# Windows PowerShell 5.1 may otherwise negotiate an obsolete TLS version.
if ([Net.ServicePointManager]::SecurityProtocol -band [Net.SecurityProtocolType]::Tls12) {
# TLS 1.2 is already enabled.
} else {
[Net.ServicePointManager]::SecurityProtocol = `
[Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
}

$releaseUrl = "https://github.com/$repo/releases/download/v$Version"
$downloadDir = Join-Path ([IO.Path]::GetTempPath()) ("codedb-install-" + [guid]::NewGuid().ToString("N"))
$targetPath = Join-Path $InstallDir "codedb.exe"
$stagedPath = Join-Path $InstallDir ("codedb.exe.new." + $PID)

try {
New-Item -ItemType Directory -Force -Path $downloadDir, $InstallDir | Out-Null

$downloadedBinary = Join-Path $downloadDir $assetName
$downloadedChecksums = Join-Path $downloadDir "checksums.sha256"

Write-Host "codedb installer"
Write-Host " version v$Version"
Write-Host " install $InstallDir"
Write-Host " download $assetName"

Invoke-WebRequest -UseBasicParsing `
-Headers @{ "User-Agent" = "codedb-installer" } `
"$releaseUrl/$assetName" `
-OutFile $downloadedBinary
Invoke-WebRequest -UseBasicParsing `
-Headers @{ "User-Agent" = "codedb-installer" } `
"$releaseUrl/checksums.sha256" `
-OutFile $downloadedChecksums

$checksumLine = Get-Content -LiteralPath $downloadedChecksums |
Where-Object { $_ -match "\s\*?$([regex]::Escape($assetName))$" } |
Select-Object -First 1
if (-not $checksumLine) {
throw "Release v$Version has no checksum for $assetName"
}

$expectedHash = ($checksumLine -split '\s+')[0]
if ($expectedHash -notmatch '^[0-9a-fA-F]{64}$') {
throw "Release v$Version contains an invalid checksum for $assetName"
}

$actualHash = (Get-FileHash -LiteralPath $downloadedBinary -Algorithm SHA256).Hash
if ($actualHash -ne $expectedHash.ToUpperInvariant()) {
throw "SHA256 mismatch for $assetName"
}
Write-Host " verify SHA256 OK"

Copy-Item -LiteralPath $downloadedBinary -Destination $stagedPath -Force
Unblock-File -LiteralPath $stagedPath -ErrorAction SilentlyContinue
Move-Item -LiteralPath $stagedPath -Destination $targetPath -Force

if (-not $NoPath) {
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$pathEntries = @($userPath -split ';' | Where-Object { $_ })
$alreadyOnPath = $false
foreach ($entry in $pathEntries) {
if ($entry.TrimEnd("\") -ieq $InstallDir.TrimEnd("\")) {
$alreadyOnPath = $true
break
}
}
if (-not $alreadyOnPath) {
$newUserPath = if ($userPath) {
$userPath.TrimEnd(';') + ';' + $InstallDir
} else {
$InstallDir
}
[Environment]::SetEnvironmentVariable("Path", $newUserPath, "User")
Write-Host " PATH added for future terminals"
}
}

if (-not (($env:PATH -split ';') | Where-Object { $_.TrimEnd("\") -ieq $InstallDir.TrimEnd("\") })) {
$env:PATH = "$InstallDir;$env:PATH"
}

& $targetPath --version
if ($LASTEXITCODE -ne 0) {
throw "Installed codedb failed its version check"
}

Write-Host ""
Write-Host "Installed: $targetPath"
Write-Host "MCP command: $targetPath mcp"
} finally {
Remove-Item -LiteralPath $stagedPath -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath $downloadDir -Recurse -Force -ErrorAction SilentlyContinue
}
Loading
Loading