Contributing

This guide covers what you need to get started contributing to Kangentic. For detailed architecture documentation, see the Architecture page or the repo docs.

Prerequisites

• Node.js 20+, Download from nodejs.org
• Git 2.25+, worktree support required
• At least one supported agent CLI on PATH for end-to-end testing: Claude Code, Codex, Gemini, Cursor, GitHub Copilot CLI, Aider, or Oz (Warp). All seven are first-class: add features or adapters for any of them.

Platform Build Tools

Platform	Required
Windows	Visual Studio Build Tools (for better-sqlite3 native compilation)
macOS	Xcode Command Line Tools
Linux	build-essential, python3

Quick Start

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

The dev server starts three parallel processes: Vite (renderer HMR), esbuild (main/preload watch), and Electron.

Project Structure

src/
  main/                  # Electron main process (Node.js)
    agent/               # Agent adapters (per-agent subfolders) with detection, command building, hooks, trust
    config/              # Three-tier config: global → project → effective
    db/                  # SQLite database layer + migrations
    engine/              # Transition engine, session recovery
    git/                 # Worktree creation and cleanup
    ipc/                 # IPC handler registration + handlers/
    pty/                 # Terminal session management + queue
  preload/               # Context bridge (window.electronAPI)
  renderer/              # React UI
    components/          # Board, dialogs, layout, terminal
    hooks/               # React hooks (useTerminal, etc.)
    stores/              # Zustand state management
  shared/                # Shared types, IPC channels, path utilities
tests/
  unit/                  # Vitest — pure logic, no browser
  ui/                    # Playwright + Chromium — mock electronAPI
  e2e/                   # Playwright + real Electron

Build System

Mode	Command	What Runs
Development	npm start or npm run dev	Vite dev server + esbuild watch + Electron
Production	npm run build	tsc --noEmit → Vite build → esbuild (minified)
Package	npm run package	Build + create platform installer
Make	npm run make	Build + create distributable
Publish	npm run publish	Build + upload to GitHub Releases

In development, native modules (better-sqlite3, node-pty, simple-git) are marked external in esbuild and loaded at runtime from node_modules.

Packaging

Kangentic uses electron-builder for creating platform installers, configured via electron-builder.yml in the project root.

Platform Targets

Platform	Format	Notes
Windows	NSIS installer (.exe)	Signed via Azure Trusted Signing
macOS	DMG (.dmg)	Hardened runtime + notarization
Linux	.deb, .rpm	No auto-update support

Native Module Handling

Native modules (better-sqlite3, node-pty) are rebuilt for the target Electron version during packaging. The bridge script is selectively unpacked from the ASAR archive to allow process spawning.

Security Fuses

Production builds enable Electron security fuses:

• RunAsNode — disabled (prevents ELECTRON_RUN_AS_NODE)
• NodeOptions — disabled (prevents NODE_OPTIONS injection)
• Inspection — disabled (prevents --inspect debugging)
• Cookie encryption — enabled
• ASAR integrity — enabled

Contributor License Agreement

First-time contributors must sign a Contributor License Agreement (CLA) before their pull request can be merged. When you open your first PR, the CLA Assistant bot will post a comment — you sign by adding a comment to the PR. It takes about 30 seconds and only needs to be done once.

Kangentic is dual-licensed: the public version uses AGPLv3, and commercial licenses are available for organizations that need proprietary modifications. The CLA (modeled after the Apache ICLA) grants VORPAHL LLC a non-exclusive license to distribute your contribution under any license, while you retain full copyright to your work.

Key Conventions

• TypeScript strict mode — noImplicitAny enabled, no any types
• Icons — Lucide React only, no inline SVGs
• Test selectors — data-testid attributes on interactive elements
• IPC channels — src/shared/ipc-channels.ts is the single source of truth
• Commit messages — Conventional Commits format, enforced by commitlint

Next Steps

• Testing — Three-tier testing strategy
• Architecture — Process model, data flow, IPC channels
• Configuration Reference — All settings keys and types
• Repo docs — Deep dives on database schema, transition engine, session lifecycle, and more