Full install matrix for grafel. For the five-command path see quickstart.md.
| Requirement | Notes |
|---|---|
| Go 1.26+ | CGO must be enabled (tree-sitter uses a C library) |
| C/C++ compiler | macOS: xcode-select --install / Debian-Ubuntu: apt install build-essential / Windows: MinGW-w64 (UCRT) via MSYS2 — set both CC (gcc) and CXX (g++): tree-sitter is C, its yaml grammar is C++. CGO_ENABLED=0 → "build constraints exclude all Go files"; missing CXX → exec: "g++": not found. |
| Node.js 20+ + npm | Dashboard build only — not needed at runtime after make build |
| git | Required for indexing |
The recommended install path. Downloads the latest release binary, verifies it, and places grafel under ~/.grafel/bin.
curl -fsSL https://raw.githubusercontent.com/cajasmota/grafel/main/install.sh | bashThe script respects GRAFEL_VERSION (pin a release tag), GRAFEL_PREFIX (install location, default ~/.grafel), and GRAFEL_FORCE=1 (overwrite an existing install).
The scripted paths install the same release binary into %USERPROFILE%\.grafel\bin, add that folder to your user PATH, record the binary in install.json, and register grafel as an MCP server in your AI coding tools. They deliberately do not run bare grafel install (issue #6163): that command is scoped to the directory you run it from — it appends /.grafel/ to that repo's .gitignore and installs four git hooks there — and an installer is run from wherever your console happens to be, not from a repository you chose. Run grafel install yourself, inside the repo you want it to configure. None require administrator rights — everything lives under your user profile. There is no native windows_arm64 build; on Windows on ARM the x86_64 binary runs under x64 emulation, and the installers select it automatically.
irm https://raw.githubusercontent.com/cajasmota/grafel/main/install.ps1 | iexcmd.exe can't pipe-execute a remote script the way PowerShell's iex can, so download the .bat first, then run it:
curl -fL https://raw.githubusercontent.com/cajasmota/grafel/main/install.bat -o "%TEMP%\grafel-install.bat" && "%TEMP%\grafel-install.bat"The .bat mirrors the PowerShell installer exactly (same prefix, asset names, SHA256 verification, user-PATH append) using only Windows 10 1803+ built-ins (curl, certutil, tar, setx).
Download the windows_x86_64 archive from the releases page, extract it, add the folder to PATH, and run grafel install. Full step-by-step with copy-pasteable commands: install-windows-manual.md.
Both the PowerShell and CMD installers, as well as GRAFEL_VERSION / GRAFEL_PREFIX, are documented inline at the top of each script. Windows release binaries link statically against MinGW — users do not need MinGW installed at runtime.
Release archives are published at https://github.com/cajasmota/grafel/releases for those who prefer a manual download over the installer script.
Archives per platform: linux_x86_64, linux_arm64, macos_x86_64, macos_arm64, windows_x86_64.
Extract the archive and move the grafel binary to a directory on your PATH. On Windows, see install-windows-manual.md for the exact extract + PATH + grafel install steps.
For contributors, or if you prefer to build the binary yourself.
git clone https://github.com/cajasmota/grafel.git
cd grafel
make build # builds dashboard (npm ci + vite build) + Go binary
./grafel --versionmake build runs dashboard-build (npm) then go build. If you only want the Go binary and the dashboard is already built:
make build-go-onlyTo install the binary system-wide:
go install -ldflags="-X main.commit=$(git rev-parse --short HEAD)" ./cmd/grafel
# installs to ~/go/bin -- ensure ~/go/bin is on PATHFor contributors who want to edit skills in-place and see changes without reinstalling:
grafel install --devThis creates symlinks in ~/.claude/skills/ pointing back to skills/ in the source checkout instead of copying files.
grafel doctor # smoke-check install + tools
grafel wizard # create a group (interactive)
grafel install # start daemon, register MCP, install skills
grafel status # confirm MCP: connectedgrafel install writes MCP entries, rules files, and (for Claude Code) skills
into the AI coding tools you use. By default it targets every supported
tool. To pick a subset:
grafel install --tools claude,cursor,windsurf # non-interactive allow-list
grafel install # interactive wizard on a TTY
grafel install --no-wizard # keep current/default set; skip wizard
grafel tools list # inspect enabled/detected state
grafel tools enable kiro # enable a tool after install (in-process)
grafel tools disable codeium # disable a tool after install (in-process)The same selection is editable from the dashboard under Settings → AI coding tools.
See tools.md for the full supported-tools matrix (exact MCP config paths and rules-file paths per tool) and the complete enable/disable reference, and setup-per-tool.md for step-by-step setup + verification in each tool.
grafel update # fetch latest stable, atomic replace, re-run install
grafel update --pre # latest pre-release
grafel update --tag v1.2.3 # pin a specific versionIf the upgrade fails, the binary is automatically restored from the pre-update stash.
grafel uninstall # removes skills, MCP entries, stops daemon; leaves graphs
grafel uninstall --purge # also removes ~/.grafel/store/ and docs/Uninstall reads install.json to remove only what grafel owns — it will not touch other tools' MCP registrations.
User preferences are persisted to ~/.grafel/settings.json. See settings.md for the full field reference.
See troubleshooting.md.