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”
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: the environment check

Section titled “First launch: the environment check”

The first time you launch Kangentic, the Welcome screen looks for Git and each supported agent CLI and sums up what it found in one line. Show setup expands the full detection grid, and it opens by itself when something is missing:

  • 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. Only three of the missing agents are listed at first; Show all reveals the rest, and Refresh re-runs detection after you install one.
  • The Open a project button reads Checking your setup while detection runs and is enabled the moment it finishes, whether or not anything was found. Detection is a PATH probe, and it can miss a CLI installed somewhere unusual, so a failed check never locks you out. Open a project, then set the CLI’s path under Settings > Agent > CLI path (the field shows the project’s default agent, so pick that agent first), or install an agent later.

The welcome screen on first launch: the Kangentic mark, an Open a project button, a line reporting the git and agent CLIs it found with a Show setup control, and three notes on what opening a project does. v0.46.0 The real app on a sample install. The projects and terminals are recordings, connected to nothing, so click anything.

The Welcome screen detects agents; it does not choose one. New projects start on Claude Code until you set your own default under Settings > Agent > Project defaults, which is the first step of the walkthrough below.

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. If Kangentic has not seen the folder before, it registers the project first. The launcher forwards the path to the app as its --cwd=<path> flag and drops any other flag it does not know, so the positional form is the one to use through npx. 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. If it is not a git repository yet, Kangentic initializes one for you without asking, because worktrees need git, and then asks for a first commit: a worktree needs a commit to branch from, so until then every task shares the project folder.

  2. Explore the default board - New projects start with seven columns: To Do, Planning, Executing, Code Review, Testing, Merge, and Done. No agent runs in To Do. Planning and Executing spawn one, the next three keep it running, and Done suspends the session and archives the task. Default board layout says what each column does to a session. Column names never reach the agent, and by default no column delivers a prompt on arrival. What the agent is told lists exactly what each move sends.

    The Kangentic board for contoso-web: columns from To Do to Testing, each card showing its agent, latest message, and context use, three projects in the sidebar, and the terminal panel along the bottom on the working auth-middleware agent. v0.46.0 The real app on a sample install. The projects and terminals are recordings, connected to nothing, so click anything.

  3. Shape your board - The seven default columns are a starting point, not a fixed template. Click Add column on the board toolbar, or any column header, to open the Column Manager, where each column gets its own name, color, agent, model, permission mode, session target, and automations. See Adding and editing columns for every option, What happens when you drag a card for what a move does, and Board configuration for sharing the layout with a team through the committed kangentic.json file.

  4. Create your first task - Click Add task at the bottom of the To Do column, or New Task on the board toolbar. Enter a title and description, being specific about what you want the agent to do. You can also stage tasks in the Backlog and imports first and promote them when ready. See Creating tasks for attachments, labels, and worktree options.

    The New Task dialog: a title field, a description editor that takes dropped files, priority and labels, the Branch row with the branch it will create from main in a new worktree, and the choice between the column's settings and an agent override. v0.46.0 The real app on a sample install. The projects and terminals are recordings, connected to nothing, so click anything.

  5. Run the task - Drag the task card to the Executing column. Kangentic creates a git worktree for the task (if worktrees are enabled), spawns your default agent with the task’s title and description as the prompt, and shows the agent’s terminal output as it arrives. What the agent is told shows the exact prompt format.

  6. Monitor and interact - Click a running task to open its terminal. Watch the agent work, or switch between running agents with 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 finishes, open the task’s Changes pane to read the diff, then merge the branch when you are satisfied. Moving the card to Done archives the task and keeps the branch.

Settings worth checking

Section titled “Settings worth checking”

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

  • Agent and Permissions under Project defaults 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. The rest queue.
  • Worktrees, Default base branch, and Post-worktree 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.

See also

Section titled “See also”
  • Creating tasks - write effective prompts, attach images, manage worktree options, and set every per-column override in the Column Manager
  • Agent orchestration - the mental model for running multiple agents in parallel
  • Columns - what a move does to the agent, and the Column Manager
  • Automations - what a column runs as a task enters, at each turn end, and as it leaves
  • Board configuration - share your column layout with your team via kangentic.json
  • Settings - themes, permission modes, and customization

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

Star on GitHub