Skip to content
Kangentic

Quickstart

Get Kangentic running on your machine and create your first agent-managed project.

Prerequisites

Section titled “Prerequisites”

Before installing Kangentic, make sure you have:

You only need one of the agents above to use Kangentic. Install whichever CLI you already have a subscription or API key for. Any extras you install later are auto-detected and become available in the agent picker and per-column overrides.

Installation

Section titled “Installation”

  1. Install and launch

    Terminal window
    npx kangentic

    This downloads the signed binary for your platform, installs it, and launches the app. After the first run, auto-updates keep you current on every platform.

First launch: pick your agent

Section titled “First launch: pick your agent”

The first time you launch Kangentic, the Welcome screen runs a quick environment check before you can open a project. It looks for Git and each supported agent CLI and shows a detection grid:

  • Each row shows the detected version, or Not installed with an Install link, or Not signed in with a one-click button that copies the login command for you to run in a terminal.
  • The Open a Project button stays disabled until Git and at least one agent are detected.

The agent you pick here becomes your default agent for new sessions. You can change it later with the Default Agent setting in the Agent settings.

Two quiet links sit at the bottom of the Welcome screen: Read the setup guide, which opens this documentation, and Pair a phone, which opens the mobile pairing guide for linking Kangentic Mobile.

See Agent Orchestration for the multi-agent model, and Installation for installing and signing in to the agent CLIs.

Opening Projects

Section titled “Opening Projects”

Open a project directly from your terminal:

Terminal window
# Open a specific project
npx kangentic /path/to/project


# Launch without a path: reopens your last project
npx kangentic

Pass a path to open that project (it’s created automatically if Kangentic hasn’t seen it yet); --cwd works too if you prefer a flag. With no path, Kangentic reopens the project you last had active, or shows the welcome screen on a first run.

First Project Setup

Section titled “First Project Setup”

  1. Open a project folder - Launch Kangentic and pick a folder. The project takes its name from the folder, and if it is not a git repository yet, Kangentic initializes one for you - worktrees need git, so this happens without asking.

  2. Explore the default board - New projects start with seven columns:

    ColumnBehavior
    To DoHolding area, no agent runs here. Moving a task here kills its session.
    PlanningSpawns the default agent in plan mode; auto-moves to Executing when done
    ExecutingSpawns the default agent in its recommended permission mode
    Code ReviewAgent keeps running; add a message telling it how to review the work
    TestingAgent keeps running; add a message telling it how to test the work
    MergeAgent keeps running; add a message telling it how to ship the work
    DoneSuspends the session and archives the task

    The Behavior column describes the session lifecycle only. Column names never reach the agent, and by default no column delivers a prompt on arrival - see What the Agent Is Told for exactly what each move sends.

  3. Shape your board - The seven default columns are a starting point, not a fixed template. There are no presets to choose from; you customize the default board directly. Click Add column on the board toolbar, or click any column header, to open the Edit Columns dialog. There you can rename a column and set its color and icon, override the agent, permission mode, model, and reasoning effort per column, and configure a message to the agent, handoff context, and the session target (shared Main or Isolated). See Per-Column Customization for the full option table, Custom Workflows for transitions and actions, and Board Configuration for sharing your layout with a team via the committed kangentic.json file.

  4. Create your first task - Click + on a column header or use the New Task button. Enter a title and description, being specific about what you want the agent to do. You can also stage tasks in the Backlog first and promote them when ready. See Creating Tasks for details on attachments, labels, and worktree options.

  5. Run the task - Drag the task card to the Executing column. Kangentic will:

    • Create a new git worktree (if enabled)
    • Spawn your default agent with your task’s title and description as the prompt (What the Agent Is Told shows the exact format)
    • Display the agent’s terminal output in real-time

  6. Monitor and interact - Click on a running task to view its terminal. You can watch the agent work, or switch between multiple running agents using the terminal tabs. Running agents in several projects? The Agent Monitor lists every live session across all of them.

  7. Review results - When the agent completes, review the changes in the worktree. Merge the branch into your main branch when you’re satisfied.

Settings worth checking

Section titled “Settings worth checking”

A few settings are worth a look as you get started (open Settings from the sidebar):

  • Default Agent and Permission Mode in the Agent settings - the agent CLI and tool-approval behavior for new sessions.
  • Max Concurrent Sessions in the Behavior settings - how many agents may run at once (excess tasks queue).
  • Worktrees Enabled, Default Base Branch, and Init Script in the Git settings - toggle git worktrees, choose the branch they fork from, and run a setup script (such as npm install) in each new worktree.

See Settings for the complete reference.

Next steps

Section titled “Next steps”

Next: Creating Tasks - write effective prompts, attach images, and manage worktree options.

Then explore:

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

Star on GitHub