Skip to content
Kangentic

Installation

Detailed installation instructions for all platforms. For a quick start, see Quickstart.

Prerequisites

Section titled “Prerequisites”

You can install more than one agent and switch between them globally or per column. The Welcome screen’s detection grid lists every supported CLI: detected ones first with their version, the rest as Not installed with an Install link, behind Show all. A detected CLI that is not signed in leads the grid on a full-width row, with a button that copies its login command, and the summary line above the grid names it. If you install a new CLI after first launch, click Refresh on the Welcome screen, click the re-detect icon beside the CLI path field under Settings > Agent, or restart Kangentic.

The welcome screen with its setup list open: a prompt to sign in to OpenCode, OpenCode on top marked Not signed in with its login command to copy, git and three agents found with versions, and three more marked Not installed beside an Install link. v0.46.0 The real app on a sample install. The projects and terminals are recordings, connected to nothing, so click anything.

Quick install

Section titled “Quick install”
Terminal window
npx kangentic

This downloads the signed binary for your platform, installs it, and launches the app. It installs to %LOCALAPPDATA%\Programs\Kangentic\ on Windows, ~/Applications/Kangentic.app on macOS (or /Applications when a copy already lives there), and /usr/bin/kangentic on Linux. The launcher installs the release that matches its own package version, so npx kangentic@0.41.0 pins an older build if you need one, and the changelog says what each version changed. It picks the build for your machine: Windows x64, macOS on Apple Silicon or Intel, and Linux x64 or arm64. On a Mac it installs the Apple Silicon build even when an Intel build of Node runs it under Rosetta. Windows on ARM runs the x64 build under emulation. On macOS 12 or older the launcher stops before downloading anything and says Kangentic requires macOS 13 or later.

Manual download

Section titled “Manual download”

Download installers directly from GitHub Releases:

PlatformFormatFile
Windows (x64)NSIS installerKangentic-Setup-x.y.z.exe
macOS (Apple Silicon, macOS 13+)DMGKangentic-x.y.z-arm64.dmg
macOS (Intel, macOS 13+)DMGKangentic-x.y.z-x64.dmg
macOS (the archive npx kangentic downloads)zipKangentic-x.y.z-arm64-mac.zip or Kangentic-x.y.z-x64-mac.zip
Linux x64 (Debian/Ubuntu)debkangentic_x.y.z_amd64.deb
Linux x64 (Fedora/RHEL)rpmkangentic-x.y.z-1.x86_64.rpm
Linux arm64 (Debian/Ubuntu)debkangentic_x.y.z_arm64.deb
Linux arm64 (Fedora/RHEL)rpmkangentic-x.y.z-1.aarch64.rpm

The Intel Mac and Linux arm64 builds are new in v0.46.0. Everything works on an Intel Mac except the Knowledge Graph: its local model runs on onnxruntime, which ships no Intel macOS build, so Settings > Knowledge Graph shows it as unavailable and the app never downloads the model. Keyword search in Quick Find and the index still works.

Platform-specific instructions

Section titled “Platform-specific instructions”
  1. Run Kangentic-Setup-x.y.z.exe
  2. If Windows SmartScreen shows a warning, click More info > Run anyway (the binary is signed, but new publishers may trigger SmartScreen initially)
  3. The app installs and launches automatically
  4. Auto-updates are enabled - new versions install silently in the background

Building from source

Section titled “Building from source”

  1. Install prerequisites:

    • Node.js 22.14+ or 24+. better-sqlite3 13 needs Node-API 10, and older Node 22 releases crash on the first database open instead of reporting it
    • Build tools on Linux and macOS only: Windows needs none, because every native module ships a prebuilt Windows binary. See Contributing for details

  2. Clone and build:

    Terminal window
    git clone https://github.com/kangentic/kangentic.git
    cd kangentic
    npm install
    npm run make

  3. The installer is created in the out/ directory (use npm run package instead for an unpacked app directory without an installer)

Custom data directory

Section titled “Custom data directory”

By default, Kangentic stores its data in the platform-standard application data directory. Override with:

Terminal window
# Environment variable
export KANGENTIC_DATA_DIR=/path/to/custom/dir


# CLI flag
npx kangentic --data-dir /path/to/custom/dir

When both are set, the environment variable wins over the flag. Two more flags are worth knowing. --force re-downloads and reinstalls the app build even when the current version is already installed, which repairs an install that was interrupted or corrupted. --demo points the app at a fresh temporary data directory and passes it --ephemeral, so you can try Kangentic without touching your real projects, your settings, or the single-instance lock.

Uninstall

Section titled “Uninstall”

Use Settings > Apps > Installed apps and uninstall Kangentic, or run "%LOCALAPPDATA%\Programs\Kangentic\Uninstall Kangentic.exe" directly. To remove all data too, delete %APPDATA%\kangentic\.

Troubleshooting

Section titled “Troubleshooting”

npx cannot find kangentic

Section titled “npx cannot find kangentic”

If npx kangentic is not found, make sure Node.js 20+ is installed and npx is on your PATH. A missing agent CLI is a different problem; see CLI not found on the Troubleshooting page.

Native module build failures

Section titled “Native module build failures”

If npm install fails with native module errors:

  • Windows: No compiler is needed since v0.44.0; every native module ships a prebuilt Windows binary. Try npm cache clean --force, then npm install again
  • macOS: Run xcode-select --install. A macOS package build needs it for node-pty’s spawn-helper
  • Linux: Install build-essential and python3. node-pty ships no Linux binary and compiles on install

Windows: Kangentic closes right after it starts

Section titled “Windows: Kangentic closes right after it starts”

Kangentic checks at startup that its sandboxed processes can read the install folder, and exits before its window opens when they cannot. On a few machines the per-user install folder carries an access entry left by a packaged app but no read grant for packaged apps. The installer has added that grant on every install and update since v0.44.0. If an install still closes at once, run this in PowerShell and start Kangentic again:

Terminal window
icacls "$env:LOCALAPPDATA\Programs\Kangentic" /grant "*S-1-15-2-1:(OI)(CI)(RX)"

macOS 12 or older

Section titled “macOS 12 or older”

Kangentic needs macOS 13 (Ventura) or later, starting with v0.44.0. npx kangentic refuses to install on an older Mac, and an installed v0.43.2 or earlier on macOS 12 stays where it is: its update feed tells it the new release needs macOS 13, so it never downloads a build that would not open. Update macOS to move to v0.44.0.

”App is damaged” on macOS

Section titled “”App is damaged” on macOS”

This Gatekeeper error appears when the app isn’t properly signed or notarized, which in practice means a build you made yourself. Use the bypass:

  1. Open System Settings > Privacy & Security
  2. Click Open Anyway next to the Kangentic warning
  3. Or run xattr -cr ~/Applications/Kangentic.app (or /Applications/Kangentic.app for a DMG install)

See also

Section titled “See also”

Kangentic is free and open source. A star helps other people find it.

Star on GitHub