Agent Orchestration

Kangentic’s core feature is visual agent orchestration. Instead of juggling terminal windows and manually managing coding-agent sessions, you control everything from a Kanban board.

Supported Agents

As of v0.15.0, Kangentic orchestrates seven coding-agent CLIs side-by-side. Claude Code, Codex CLI, and Gemini CLI are the most tightly integrated: each has session resume, reference-counted hook files, and a native session history file that Kangentic parses for handoff context. Cursor CLI and GitHub Copilot CLI add session resume plus stream-based telemetry. Aider and Warp (Oz CLI) are intentionally simpler: they participate in the Kanban flow without session resume or conversation handoff.

Agent	Resume	Handoff Source	Default Permission	Notes
Claude Code (Anthropic)	✓	✓	Accept Edits	Resume via `--resume <id>` with caller-controlled session IDs. Event hooks injected via `event-bridge.js`. Supports Kangentic’s trust pre-approval dialog and the Claude-only `auto` classifier permission mode.
Codex CLI (OpenAI)	✓	✓	Accept Edits	Resume via `codex resume <id>`. Reference-counted hooks in `.codex/hooks.json`. Native rollout file (`~/.codex/sessions/.../rollout-*.jsonl`) parsed for handoff context.
Gemini CLI (Google)	✓	✓	Accept Edits	Resume via `--resume <id>`. Reference-counted hooks in `.gemini/settings.json`. Native chat history (`~/.gemini/tmp/<cwd>/chats/session-*.json`) parsed for handoff context.
Cursor CLI	✓	—	Non-Interactive	Resume via `agent --resume="<id>"`. Session IDs are captured from the init event on Cursor’s `--output-format stream-json` NDJSON stream (not caller-assigned). Non-interactive mode is the default so ContextBar can resolve the model pill and resume works reliably. No hooks, no native history file.
GitHub Copilot CLI	✓	—	Accept Edits	Resume via `--resume <uuid>` with caller-controlled session IDs (same semantics as Claude). Inline hooks in per-session `config.json` (`preToolUse`, `postToolUse`, `agentStop`, `preCompact`). Supports `--plan` and `--yolo`.
Aider	—	—	Bypass Permissions	Edit-first / fire-and-forget. No session resume (relaunched fresh on re-entry), no native session history, no injected hooks.
Warp (Oz CLI)	—	—	Default	No session resume, no hooks, no native history file. Permissions are managed via Warp agent profiles (`--profile`), so the permission-mode labels are informational. Detection uses `dump-debug-info` rather than `--version`.

All seven adapters share the same detection pipeline: a user-configured override path (in Settings → Agent → CLI Paths) wins if set, otherwise which() discovers the binary on PATH, and on Windows the --version check is run through a shell so .cmd/.bat shims work. Claude Code additionally checks Homebrew fallback paths (/opt/homebrew/bin/claude, /usr/local/bin/claude, /home/linuxbrew/.linuxbrew/bin/claude) for the macOS Finder-launch case, where Electron doesn’t inherit the shell PATH.

Pick a default agent in the Welcome screen’s detection grid (on first launch) or under Settings → Agent → Default Agent. Only installed CLIs are offered. You can also override the agent per-column (e.g., Claude for Planning, Codex for Executing) so a task moving between columns automatically switches agents. See Per-Column Customization.

When a column has handoff context enabled, Kangentic hands the prior agent’s native session history file to the next agent so conversation context carries across even when the agent changes. Handoff is supported for Claude Code, Codex, and Gemini in both directions. Cursor, Copilot, Aider, and Warp don’t write a native session history file that Kangentic can parse, so a task moving from one of those agents into another carries no conversation context, and a task moving into one of them simply starts a fresh session.

Kanban-Based Control

Each task card on the board represents a potential or active coding-agent session. The default board columns map to agent states:

Column	Role	What Happens
Backlog	Holding area	No agent runs here. Moving a task here kills its session.
Planning	Plan mode	Spawns the configured agent in plan mode. The agent creates a plan, then auto-moves to Executing.
Executing	Auto-spawn	Spawns the configured agent in its default permission mode. The agent works on the task.
Code Review	Auto-spawn	Agent keeps running. Attach an auto-command for review prompts.
Tests	Auto-spawn	Agent keeps running.
Ship It	Auto-spawn	Agent keeps running.
Done	Archive	Suspends the session (preserving context) and archives the task.

Drag a card between columns to change its state. All columns except Backlog and Done are fully customizable — see Settings for per-column options.

Spawning Agents

When you move a task to an active column, Kangentic:

Creates a new git worktree for the task (if worktrees are enabled)
Launches the configured agent CLI (Claude Code, Codex, Gemini, Aider, Cursor, Copilot, or Warp) in that worktree
Passes your task title and description as the initial prompt
Connects the agent’s I/O to a terminal tab (see Terminal)

The agent starts working immediately. You can watch its progress in real-time or switch to other tasks.

Card Indicators

Task cards show real-time status:

Indicator	Meaning
Pulsing spinner	Agent is actively thinking or running tools
Static icon	Agent is idle — finished, waiting, or needs input
Context bar	Token usage and context window percentage
”Queued” label	Waiting for a concurrent session slot to open

Suspending and Resuming

One of Kangentic’s key capabilities is the ability to suspend and resume agent sessions:

Suspend — Move a task to Done. The session is saved (conversation/session ID preserved), the agent process stops, and system resources are freed.
Resume — Unarchive a completed task and drag it to an active column. The agent picks up where it left off with full conversation context. Session resume is supported for Claude Code, Codex, Gemini, Cursor, and GitHub Copilot. Aider and Warp relaunch fresh on re-entry.

This means you can run more agents than your system can handle simultaneously — just rotate them in and out of active columns.

Session Queue

When the max concurrent sessions limit is reached, new sessions are queued automatically. Queued tasks show a “Queued” indicator on their card. When a running session exits or is suspended, the next queued session promotes automatically (FIFO order). Queue promotion is reentrancy-safe — if a promotion triggers another session exit, the queue processes correctly without race conditions.

Configure the session limit in Settings under the Behavior tab. You can also set the overflow behavior to queue (default) or reject via the agent.queueOverflow setting — see Configuration Reference.

Concurrent Sessions

Kangentic supports running multiple agents simultaneously. Each agent runs as a separate CLI process with its own:

Git worktree (isolated file system)
Terminal session
Conversation history
Working state

The Kanban board gives you a clear view of what’s running, what’s queued, and what’s completed.

Board Search and Filtering

Press Ctrl+F (Windows/Linux) or Cmd+F (macOS) to open the board search bar. Type to filter tasks across all columns by title or description. Matching tasks are highlighted while non-matching tasks are dimmed. Toggle the search bar with the showBoardSearch setting or the keyboard shortcut.

Click the filter icon in the search bar to open the filter popover:

Priority — toggle one or more priority levels (None, Low, Medium, High, Urgent)
Labels — toggle one or more labels from the project’s label set

Active filters show a count badge on the filter icon. Priority and label filters combine with the search query — a task must match all active criteria to be visible. Click “Clear all filters” to reset.

Task Descriptions

Write task descriptions the same way you’d prompt Claude Code directly. Be specific:

Fix the race condition in the WebSocket connection handler.
The issue is in src/ws/handler.ts — when two clients connect
simultaneously, the session map can get corrupted.
Add proper locking and write tests for the concurrent case.

The more context you provide, the better the agent will perform. You can also attach files, set priorities, and add labels — see Creating Tasks for details.

Agent-to-Board Integration (MCP)

Kangentic includes a built-in MCP (Model Context Protocol) server that gives agents tools to interact with the board while they work. This is enabled by default.

When an agent discovers follow-up work — bugs, refactoring opportunities, or new features — it can create tasks directly on the board without you manually entering each one. Agents can also search existing tasks to avoid duplicates, read session transcripts, and view board status for context.

Available MCP tools:

Board and tasks

Tool	Purpose
`kangentic_create_task`	Create a new task (board or backlog)
`kangentic_update_task`	Update a task’s title, description, labels, or priority
`kangentic_delete_task`	Delete a task and its associated session/worktree
`kangentic_move_task`	Move a task to a different column
`kangentic_list_tasks`	List tasks, optionally filtered by column
`kangentic_search_tasks`	Search tasks by keyword
`kangentic_find_task`	Find a task by branch name, title, or PR number
`kangentic_get_current_task`	Return the task that owns the calling session
`kangentic_list_columns`	List all columns with task counts
`kangentic_get_column_detail`	Get detailed column configuration
`kangentic_board_summary`	High-level board overview with metrics
`kangentic_get_task_stats`	Session metrics for a task or all tasks
`kangentic_update_column`	Update column settings

Backlog

Tool	Purpose
`kangentic_list_backlog`	List backlog entries
`kangentic_search_backlog`	Search backlog entries by keyword
`kangentic_promote_backlog`	Promote a backlog entry to a board task
`kangentic_update_backlog_item`	Update a backlog entry’s title, description, labels, or priority
`kangentic_delete_backlog_item`	Delete a backlog entry

Sessions and handoff

Tool	Purpose
`kangentic_list_sessions`	List sessions for a task or project
`kangentic_get_session_history`	Get session event history for a task
`kangentic_get_session_events`	Stream structured session events
`kangentic_get_session_files`	List files touched in a session
`kangentic_get_transcript`	Read the rich structured transcript for a session
`kangentic_get_handoff_context`	Fetch the context packet prepared for the next agent

Advanced

Tool	Purpose
`kangentic_query_db`	Run a read-only query against the project database (advanced)

In v0.15.0 the MCP server was rewritten to use an in-process streamable HTTP transport (replacing the earlier file-based bridge), reducing latency and making command dispatch atomic. Each session is still isolated to its project.

Cross-Project Tool Calls

Added in v0.17.0. Every task, backlog, and session tool accepts an optional project parameter. Pass a project name or path and the tool resolves against that project instead of the calling session’s own project. This lets a task running in Project A look up or create work in Project B without leaving its session. kangentic_get_current_task is intentionally excluded because it resolves the agent’s own CWD/branch, so cross-project lookup makes no sense there.

To disable the MCP server, toggle MCP Server off in Settings or set mcpServer.enabled to false in the config file — see Configuration Reference.