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.

Note

The CONTRIBUTING.md guide in the repo is the authoritative source for contribution rules. This page summarizes it to get you oriented; if the two ever differ, the repo guide governs.

Prerequisites

• Node.js 22+, 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, Qwen Code, Kimi Code, OpenCode, Factory Droid, Cursor, GitHub Copilot CLI, Aider, or Oz (Warp). All eleven 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

Submitting a Pull Request

1. Fork the repo and create a branch from main. Use a descriptive branch name like fix/session-resume-crash, feat/multi-agent-support, or docs/update-architecture.

2. Make your changes and add or update tests for them.

3. Run the quick local pass before opening the PR:

   npm run lint
   npm run typecheck
   npm run test:unit
   npx playwright test --project=ui

4. Sign the CLA when the bot prompts you on your first PR (see Contributor License Agreement above).

5. Open the PR. The template prompts you for What / Why / How / Tests and a short checklist. Link any related issues.

Small, focused PRs are easier to review and merge faster. For the full three-tier testing strategy, see Testing.

What to Expect

Your PR must be green on every CI check before it can merge:

Check	Tool
Lint	ESLint, runs with --max-warnings 0, so any warning fails it
Type check	tsc
Unit tests	Vitest
Build	Production bundle
UI tests	Playwright
E2E tests	Electron

If a check fails, push a fix and CI re-runs automatically.

• A maintainer may push follow-up commits to your branch for design polish or hardening before merging. This is normal and keeps the bar consistent, not a reflection on your work.
• UI changes get a maintainer design review against the UI conventions. Including a screenshot or short clip in the PR makes that review much faster.
• A maintainer merges your PR once it is approved and green. You do not need write access to the repository.

Finding Work

Look for issues labeled good first issue for approachable tasks. If you want to take on something larger, open an issue first to discuss the approach. Questions are welcome in GitHub Discussions.

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