Installation Guide & CLI Commands

Introduction

CostWise-MCP runs as a local native Go binary. It maps your codebase's AST symbols, function call-graphs, and references into a local SQLite database. It interfaces with your IDE or CLI coding agent using standard Input/Output (stdio) streams.

1. Linux Installation (Variants)

Variant A: Automated Installer Script (amd64 & arm64)

The recommended way to install on modern Linux distributions. It automatically checks for Go and C compiler dependencies, builds from source, and registers with your AI clients:

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

Variant B: Debian / Ubuntu Manual Build

Install system build dependencies and compile the binary manually:

# Install Go compiler and gcc (required for CGO Tree-sitter bindings)
sudo apt update && sudo apt install -y golang-go gcc git

# Build and verify
git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build -o ~/.local/bin/costwise ./cmd/costwise
chmod +x ~/.local/bin/costwise
costwise --version

Variant C: Alpine Linux Build

Alpine requires specific compilation environment setups to accommodate musl libc and native build tooling:

# Install build dependencies
apk add --no-cache go build-base git

# Clone and compile
git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build -o ~/.local/bin/costwise ./cmd/costwise

Variant D: RHEL / Fedora / CentOS Build

For Red Hat family distributions, configure using dnf:

sudo dnf install -y golang gcc git
git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build -o ~/.local/bin/costwise ./cmd/costwise

2. macOS Installation (Variants)

Variant A: Automated Shell Script (Intel & Apple Silicon)

Run the automated script inside your macOS Terminal to set up paths and config targets:

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

Variant B: Apple Silicon (M1 / M2 / M3 / M4 arm64) Manual Build

Ensure you have Xcode Command Line Tools installed (xcode-select --install). Build natively targeting ARM64 architecture:

# Build targeting local ARM64 arch
git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o ~/.local/bin/costwise ./cmd/costwise
chmod +x ~/.local/bin/costwise

Variant C: macOS Intel (amd64) Manual Build

Compile natively targeting Intel x86_64 architecture:

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o ~/.local/bin/costwise ./cmd/costwise
chmod +x ~/.local/bin/costwise

3. Windows Installation (Variants)

Variant A: Windows Subsystem for Linux (WSL) - Recommended

For the best performance and CGO compiling environment, install Ubuntu under WSL and run the quick installer script:

# In PowerShell (run as Administrator to set up WSL):
wsl --install

# Once inside WSL (Ubuntu), run the shell installer:
curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

Variant B: Native PowerShell Build (Requires Go + gcc)

To run natively on Windows without WSL, you must have Go 1.25+ and a gcc compiler (such as MinGW-w64) installed and configured in your environment PATH:

# In PowerShell:
git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
$env:CGO_ENABLED=1
go build -o costwise.exe ./cmd/costwise/
Move-Item costwise.exe C:\Users\$env:USERNAME\.local\bin\

4. CLI Utility Commands

Once the binary is built, use these utility flags to manage and repair client configurations:

# Run interactive auto-installer (detects and configures clients)
costwise install

# Configure all detected clients automatically without prompts
costwise install --all

# Configure a specific editor target
costwise install --target cursor
costwise install --target claude

# Rebuild the binary from source before configuring clients
costwise install --build

# Install without the session-awareness skill
costwise install --no-skill

# Run idempotent repair mode (fixes broken paths/configs)
costwise install --repair

5. Session-Awareness Skill

Installation also adds the costwise-session skill, which teaches your editor to keep sessions lean (stash large output, recall only what is needed, remember durable facts). Every MCP client receives this guidance automatically through the server. You can also manage the native skill file directly:

# Write the Claude Code skill (also runs during install)
costwise skill install

# Write it into the current project only
costwise skill install --local

# Remove it
costwise skill uninstall

# Print the guidance for manual placement in any tool
costwise skill print

6. Diagnostics with Doctor Command

Verify that the installation is intact and all IDE configurations are running with correct absolute binary paths:

costwise doctor

Diagnostics Output Structure:

CostWise Doctor

PASS Binary Found
       ~/.local/bin/costwise
PASS Binary Permissions
PASS Binary Version
       costwise version 1.0.0
PASS Binary in PATH
       /home/user/.local/bin/costwise
PASS Cursor Config
       ~/.cursor/mcp.json
PASS OpenCode Config
       ~/.config/opencode/opencode.jsonc
PASS Antigravity / Gemini Config
       ~/.gemini/antigravity/mcp_config.json
PASS MCP Startup
       Server responds to JSON-RPC initialize
PASS Repository
       /home/user/project
PASS Index Directory
       /home/user/project/.mycli-fts

Results: 10 PASS, 0 WARN, 0 FAIL
Status: READY