Multi-Project Support

Kangentic supports multiple projects in a single window. Each project has its own board, columns, sessions, and settings - switch between them from the sidebar.

Sidebar Project List

The sidebar displays all your projects. Click a project to switch to its board. Each project is independent:

• Its own set of columns (which you can customize per-project)
• Its own tasks and agent sessions
• Its own settings overrides
• Its own database stored in .kangentic/ within the project directory

Drag projects to reorder them - the order persists across app restarts.

Project Actions

The selected project shows action buttons directly on its row:

Button	Action
Open in Explorer	Opens the project directory in your file manager
Project Settings	Opens per-project settings
Delete	Removes the project from Kangentic (with confirmation)

Right-click any project to open a context menu with additional options:

Option	Action
Rename	Edit the project name inline - press Enter to save, Escape to cancel
Open in Explorer	Opens the project directory
Change Directory…	Re-point the project at a moved or renamed folder (see Relocating a Project)
Project Settings	Opens per-project settings
Move to [Group]	Move the project into a project group
Remove from group	Move the project out of its current group (only shown for grouped projects)
Delete	Remove the project from Kangentic

Adding Projects

From the app

Click Add project in the sidebar footer. It is the primary half of a split button, and the caret beside it opens New group. Right-clicking empty space below the project list opens a menu with both items.

Add project opens a folder picker rather than a form:

1. Choose the folder that holds your code
2. If that folder is already a registered project, Kangentic switches to it instead of adding a duplicate
3. Otherwise the project takes its name from the folder, and Kangentic sets up git if the folder is not a repository yet

Kangentic initializes a .kangentic/ directory inside your project (auto-added to .gitignore) and creates a board with default columns.

If Kangentic had to start the git repository for you, it says so and asks for a first commit. A worktree needs a commit to branch from, so until then every task shares the one working tree. If git could not be set up at all, Kangentic warns you and still opens the board.

From the command line

Open a project directly from your terminal:

npx kangentic /path/to        # Open a specific project path
npx kangentic                 # No path: reopens your last project

If the project doesn’t exist in Kangentic yet, it’s created automatically. Without a path, Kangentic reopens the project you last had active.

Relocating a Project

There are two ways to point a project at a new home, depending on whether the folder has already moved:

Let Kangentic move it. Open Project Settings > General and click Move… next to the project location, then pick the destination folder. A confirmation dialog lists any active agent sessions (they are stopped and resumed automatically), and Kangentic relocates the folder itself: on the same drive this is an instant rename; across drives it copies with a progress indicator and removes the original only after the copy succeeds, so a failed move never leaves the project half-migrated.

Re-point after moving it yourself. If you moved or renamed the folder outside Kangentic, the app shows a Project Folder Not Found dialog with a Locate Folder… button - point it at the new location and the project is re-attached in place.

Either way, tasks, sessions, and board history are keyed by project ID, so everything is preserved. Kangentic validates the new path, suspends any live sessions so they resume at the new location, rewrites stored worktree and session paths, repairs the moved repository’s git worktree metadata, and migrates each agent’s per-project data that lives outside the folder (such as Claude’s ~/.claude/projects transcripts and ~/.claude.json entries) so resumed sessions keep their history.

If Kangentic launches and a registered project’s folder is missing, a Project Folder Not Found dialog appears with a Locate Folder… button so you can point it at the new location. The project is never silently recreated at the stale path.

Per-Project Settings

Project-level settings override global defaults for that repository. You can customize:

• Default permission mode
• Git worktree settings (base branch, copy files, init script)
• Agent, model, and permission-mode defaults

Project settings are stored in .kangentic/config.json. See Settings for the full list of configurable options.

When you create a new project, Kangentic seeds it with only a subset of your most recently configured project’s settings - theme, default permission mode, and git options. Terminal cosmetics (font, colors, cursor) became global-only in v0.31.0 and are no longer per-project. Project-specific data such as the embedded browser’s default URL and saved backlog import sources stays per-project and is never copied into a new project.

Note

Some settings like max concurrent sessions and sidebar width are global-only and cannot be overridden per-project. These apply across all projects.

Startup Behavior

Every project is opened when Kangentic launches, so agents from all projects are ready to resume immediately. If you’d rather not auto-resume suspended sessions on launch (e.g., to avoid a startup stampede when many tasks have auto_spawn enabled), turn Auto-Resume Agents on Restart off in Settings, under the Behavior tab. The projects still open; the sessions stay paused until you click Resume on each task.

Sidebar Counts

The sidebar header and each project row surface task counts so you can gauge load at a glance without switching projects:

• Header counts: totals across all projects
• Per-project counts: active (thinking) and idle task counts for that project
• Group counts: for collapsed project groups, the aggregated counts for projects inside the group

These counts update live as agents move between states.

Cross-Project Awareness

The sidebar shows real-time agent status for every project:

• Thinking badge (green spinner) - shows the count of actively running agents
• Idle badge (amber) - shows the count of agents that need attention (idle, waiting for input, or permission-blocked)
• Command Terminal indicator - a terminal glyph with a count for projects with open Command Terminals, sitting beside the agent badges but never merged into them (a Command Terminal is not a task agent). Its tone matches the title-bar icon: green while a terminal’s agent works, amber when one waits on you, muted when idle. Clicking it switches to that project and reopens its terminal layer, and the collapsed rail shows the same state as a small tone dot.

When agents need attention on a project you’re not currently viewing:

• The taskbar icon flashes (Windows) to get your attention
• Desktop notifications fire with the task name as the title and project name in the body
• Clicking a desktop notification brings the window to the foreground, switches to that project, and opens the task detail dialog
• Auto-focus can switch to the idle session’s tab automatically

These notifications help you manage agents across projects without constantly switching between boards. See Notifications for more details.

For more than a glance, open the Agent Monitor (Ctrl+Shift+M / Cmd+Shift+M or the title-bar activity icon) - every project’s sessions in one view, with live output peeks and task details that open in place.

Moving a Task Between Projects

A task can be relocated from one project’s board to another’s through the kangentic_move_task_to_project MCP tool, so an agent can file or hand off work into a different repository without you re-creating the task. The move is scoped to the To Do column: entering To Do already resets a task’s live state (its session is killed, worktree removed, and branch deleted), so a To Do task has nothing live that would be stranded when it crosses the project boundary. Move a task to To Do first if it is elsewhere. The relocation preserves the task’s title, description, labels, priority, creation time, and attachments, and lands it in the destination board’s To Do column (or an auto-spawn column, which spawns an agent on arrival).

Next steps

Next: Project Groups - organize the sidebar when project counts grow.

See also:

• Notifications - desktop alerts that span projects
• Agent Monitor - every project’s sessions in one surface
• Settings - per-project defaults and overrides