Installation & Setup

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

Prerequisites

Before installing Kangentic, make sure you have:

• Node.js 20+ — Download from nodejs.org
• Git 2.25+ — with worktree support
• At least one supported agent CLI, installed and authenticated on your PATH:
  • Claude Code (Anthropic)
  • Codex CLI (OpenAI)
  • Gemini CLI (Google)
  • Cursor CLI
  • GitHub Copilot CLI
  • Aider
  • Oz CLI (Warp)

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.

Tip

Run claude --version, codex --version, gemini --version, agent --version (Cursor), copilot --version, or aider --version to verify your agent CLI is installed. Warp’s oz uses oz dump-debug-info instead. If you haven’t authenticated yet, run the CLI directly and follow its prompts.

Installation

1. Install and launch

   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 (Windows and macOS).

Note

Want to build from source instead? See the Contributing guide.

Opening Projects

Open a project directly from your terminal:

# Open the current directory
npx kangentic open

# Open a specific project
npx kangentic open /path/to/project

If the project doesn’t exist in Kangentic yet, it’s created automatically.

First Project Setup

1. Open a git repository — Launch Kangentic and open a git repo. Kangentic needs a git repository to create worktrees for each agent.

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

   Column	Behavior
   Backlog	Holding area, no agent runs here
   Planning	Spawns the default agent in plan mode; auto-moves to Executing when done
   Executing	Spawns the default agent in its recommended permission mode
   Code Review	Agent keeps running; attach an auto-command for review prompts
   Tests	Agent keeps running
   Ship It	Agent keeps running
   Done	Suspends the session and archives the task

3. 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.

4. 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 as the prompt
   • Display the agent’s terminal output in real-time

5. 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.

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

Note

Kangentic stores project data in a .kangentic/ directory at the root of your repository. This is automatically added to .gitignore.

Next Steps

• Learn about agent orchestration to manage multiple agents
• Understand git worktrees and how Kangentic uses them
• Explore custom workflows to automate your pipeline
• Configure settings to customize your setup