Installation Guide

Detailed installation instructions for all platforms. For a quick start, see Installation & Setup.

Prerequisites

• At least one supported agent CLI, installed and authenticated. Kangentic will auto-detect any of these on PATH:
  • Claude Code (Anthropic)
  • Codex CLI (OpenAI)
  • Gemini CLI (Google)
  • Cursor CLI
  • GitHub Copilot CLI
  • Aider
  • Oz CLI (Warp)
• Git 2.25+, worktree support required
• Node.js 20+, needed for npx install and building from source

You can install more than one agent and switch between them globally or per column. Only the ones Kangentic detects on startup are offered in the Welcome screen’s detection grid, which shows each CLI’s detection status (installed version, override path, or “not found”) so you can verify your setup at a glance. If you install a new CLI after first launch, restart Kangentic or open Settings → Agent → CLI Paths to re-trigger detection.

Quick Install

npx kangentic

This downloads the signed binary for your platform, installs it, and launches the app.

Manual Download

Download installers directly from GitHub Releases:

Platform	Format	File
Windows	NSIS installer	Kangentic-Setup-x.y.z.exe
macOS	DMG	Kangentic-x.y.z.dmg
Linux (Debian/Ubuntu)	deb	kangentic_x.y.z_amd64.deb
Linux (Fedora/RHEL)	rpm	kangentic-x.y.z.x86_64.rpm

Platform-Specific Instructions

Windows

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

macOS

1. Open Kangentic-x.y.z.dmg
2. Drag Kangentic to your Applications folder
3. On first launch, if macOS Gatekeeper blocks the app:
   • Open System Settings → Privacy & Security
   • Scroll to the security section and click Open Anyway
   • Or right-click the app → Open → Open
4. Auto-updates are enabled via electron-updater

Linux

# Debian/Ubuntu
sudo dpkg -i kangentic_x.y.z_amd64.deb

# Fedora/RHEL
sudo rpm -i kangentic-x.y.z.x86_64.rpm

Note

Linux does not support auto-updates. Re-run npx kangentic or download a new release to update.

Caution

WSL users: Install the Windows version, not the Linux version. Kangentic is an Electron desktop app and needs access to the Windows desktop environment.

Building from Source

1. Install prerequisites:

   • Node.js 20+
   • Platform build tools (see Contributing for details)

2. Clone and build:

   git clone https://github.com/kangentic/kangentic.git
   cd kangentic
   npm install
   npm run package

3. The installer is created in the out/ directory

Custom Data Directory

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

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

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

Uninstall

Windows

Use Settings → Apps → Installed apps and uninstall Kangentic, or run the uninstaller from the install directory.

macOS

Drag Kangentic from Applications to the Trash. Optionally remove data:

rm -rf ~/Library/Application\ Support/kangentic
rm -rf ~/Library/Caches/Kangentic

Linux

# Debian/Ubuntu
sudo dpkg -r kangentic

# Fedora/RHEL
sudo rpm -e kangentic

Troubleshooting

CLI Not Found

If npx kangentic is not found, ensure Node.js 20+ is installed and npx is available on your PATH.

Native Module Build Failures

If npm install fails with native module errors:

• Windows: Install Visual Studio Build Tools with the “Desktop development with C++” workload
• macOS: Run xcode-select --install
• Linux: Install build-essential and python3

”App Is Damaged” on macOS

This Gatekeeper error appears when the app isn’t properly signed or notarized. 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