Agent orchestration

Kangentic runs coding agents from a Kanban board. A card is a task, the column it sits in decides which agent runs and how, and a drag spawns, suspends, or resumes the session. This page covers the supported agents, what each default column does to a session, the card indicators, and the session queue.

Supported agents

Kangentic orchestrates fourteen coding-agent CLIs side-by-side. Claude Code, Codex CLI, Gemini CLI, Grok Build, OpenCode, Qwen Code, and Kimi Code are the most tightly integrated: each has session resume plus a native session history file (or wire-protocol JSONL) that Kangentic parses for live telemetry and hands to the next agent on a handoff. Cursor CLI and GitHub Copilot CLI add session resume plus stream-based telemetry. Antigravity CLI and Factory Droid both resume and write a native session file, but do not stream live telemetry to Kangentic. Aider is simpler still: no session resume, and its chat history is parsed only for cost, though the file itself is readable enough to carry a handoff. Goose CLI resumes via caller-named sessions but streams no telemetry and leaves no history Kangentic reads. Warp (Oz CLI) leaves nothing behind at all. A fifteenth adapter, Ollama, is different in kind: it drives a local LLM as single-turn chat rather than an agentic coder, useful for quick local-model runs inside the board flow.

Agent	Resume	Handoff Source	Notes
Claude Code (Anthropic)	✓	✓	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 `auto` classifier permission mode.
Codex CLI (OpenAI)	✓	✓	Resume via `codex resume <id>`, carrying the column’s permission mode, model override, and MCP wiring. Native rollout file (`~/.codex/sessions/.../rollout-*.jsonl`) parsed for handoff context. Directory trust is pre-approved per spawn directory (Codex keys trust on the repo root with no inheritance, so a worktree per task would otherwise prompt every time).
Gemini CLI (Google)	✓	✓	Resume via `--resume <id>`. Reference-counted hooks in `.gemini/settings.json`. Native chat history (`~/.gemini/tmp/<cwd>/chats/session-*.jsonl`, `.json` on older builds) parsed for handoff context. Folder trust is pre-approved per spawn directory, since an untrusted folder disables every configured MCP server.
Cursor CLI	✓	-	Resume via `cursor-agent --resume="<id>"`. Probed as `cursor-agent` first, with Cursor’s short `agent` shim kept only as a fallback and guarded by Cursor’s own version format, since xAI’s Grok CLI installs an `agent` shim of its own. Session IDs captured from the init event on Cursor’s `--output-format stream-json` NDJSON stream. Non-interactive mode is the default so ContextBar can resolve the model pill and resume works reliably. Since v0.46.0 every session gets Kangentic’s MCP server through a `kangentic` entry in the folder’s `.cursor/mcp.json`, approved with `--approve-mcps`. No hooks. Cursor does write a transcript, but Kangentic leaves it unread: its records are untimestamped and its stored text is wrapped in markup, so it cannot back a handoff or a delivery check.
GitHub Copilot CLI	✓	-	Resume via `--resume <uuid>` with caller-controlled session IDs. Inline hooks in per-session `config.json` (`preToolUse`, `postToolUse`, `agentStop`, `preCompact`). Supports `--plan` and `--yolo`.
Grok Build (xAI)	✓	✓	Deliberately Claude-compatible surface: caller-owned session IDs (`--session-id` new / `--resume <uuid>` re-enter), the full Claude-style hook set, and Kangentic permission modes passed through 1:1 via `--permission-mode`. Session store at `~/.grok/sessions/<cwd>/<id>/` parsed for live telemetry and lifetime usage. Sign in with `grok login` (a free tier works without signing in).
Antigravity CLI (Google)	✓	✓	Google’s `agy` TUI. Resume via `--conversation <uuid>`, which works cross-directory; the conversation ID is captured from hook payloads. Brain-dir transcript parsed for the Transcript tab - no live telemetry. Shares `~/.gemini` with Gemini CLI but keeps its own subtree, trust store, and hook schema. Sign-in is Google Sign-In inside the TUI (no login subcommand).
Goose CLI (Block)	✓	-	Block’s `goose` CLI. Resume via `-r -n <id>` with a caller-supplied session name, which works cross-directory. Permission modes are delivered through the `GOOSE_MODE` env var: Plan (chat only, no file access), Default (Smart Approve), and Auto (Skip All Approvals). No hooks or MCP wired yet (Goose supports both natively), so activity detection is PTY-only and no history file is read.
OpenCode (sst)	✓	✓	Hook-driven activity via a plugin auto-loaded from `.opencode/plugins/` (`tool.execute.before/after`, `session.created`, `session.idle`). Native session IDs (`ses_<id>`). Kangentic MCP injected via `OPENCODE_CONFIG_CONTENT` so the user’s `opencode.json` is never modified, and the plugin file is hidden from git through the repository’s local `.git/info/exclude` rather than by editing your tracked `.gitignore`. Auth state probed at `~/.local/share/opencode/auth.json`. Permission selector exposes OpenCode’s native Plan and Build agents.
Aider	-	✓	Edit-first / fire-and-forget. No session resume (relaunched fresh on re-entry) and no injected hooks. It does write `.aider.chat.history.md` in the working directory, which Kangentic parses only for session cost, but which a receiving agent can read in full on a handoff.
Qwen Code (Alibaba)	✓	✓	Soft fork of Gemini CLI. Caller-owned session IDs via `--session-id`. Hook-based activity (BeforeModel / AfterModel / BeforeToolSelection) with PTY fallback. Worktree trust pre-populated to skip the Gemini-style folder-trust prompt, and reaped again when the worktree goes.
Kimi Code (Moonshot AI)	✓	✓	Caller-owned session IDs via `--session <uuid>`. Wire-protocol v1.9 JSONL at `~/.kimi/sessions/<hash>/<id>/wire.jsonl` drives ContextBar (context %, token counts, tool events). `--continue` for resume-latest. Plan and YOLO modes supported. Auth state surfaced as a warning when `~/.kimi/credentials/` is empty.
Factory Droid	✓	✓	Resume via `droid --cwd <cwd> --resume <uuid>`. PTY-only activity detection (silence timer + cursor-hide first-output marker). Session UUID captured from `~/.factory/sessions/<cwd-slug>/<id>.jsonl`. Live telemetry is intentionally not exposed - run `/cost` or `/context` inside the Droid TUI. Autonomy is controlled in-band (Shift+Tab cycles low/medium/high).
Warp (Oz CLI)	-	-	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`.
Ollama	-	-	Local LLMs via `ollama run`, as single-turn chat rather than an agentic coder: each spawn is one turn. No session resume, no hooks, no trust mechanism, no MCP wiring, no native history. `ollama run` always gets a model: the per-column or per-task override when set, otherwise a built-in default, and the picker is filled from `ollama list`. Run `ollama run <model>` in a Command Terminal for free-form multi-turn chat.

Which permission modes each agent offers, and the one it starts in, are in the permission modes matrix of the Configuration reference.

All fifteen adapters share the same detection pipeline. A user-configured override path (in Settings > Agent > CLI path) is probed and used as-is: if it does not answer its version command, the agent reports as not found at that path rather than silently resolving to a different binary. Otherwise which() discovers the binary on PATH, and since v0.39.0 every match is walked in order (on Windows the working directory first, then each PATH entry by PATHEXT), spending at most four version probes per binary name it tries, so a stale shim sitting ahead of the real install no longer hides it. An npm .cmd, .bat, or .ps1 shim whose target script is missing is skipped without a probe. On Windows the --version check is run through a shell so .cmd/.bat shims work. When nothing on PATH answers, macOS and Linux fall back to the standard install locations listed under CLI not found, and Claude Code checks the official installer’s ~/.claude/local/claude ahead of them, for the Finder-launch case where Electron doesn’t inherit the shell PATH. Kimi Code adds the uv tool install path (~/.local/share/uv/tools/kimi-cli/bin) for the same reason. Warp (Oz CLI) keeps its own detector, since oz has no --version, and takes only the first PATH match.

Pick a default agent under Settings > Agent > Project defaults. Only installed CLIs are offered. You can also override the agent per column (Claude for Planning, Codex for Executing) so a task switches agents as it moves. See Adding and editing columns.

When a column has handoff context enabled, Kangentic points the next agent at the previous agent’s native session history file so conversation context carries across even when the agent changes. It passes the real file path rather than a manufactured summary, and the receiving agent reads it directly.

What decides whether a handoff carries context is the outgoing agent, not the incoming one. Ten agents leave a readable native history behind: Claude Code, Codex, Gemini, Grok, Antigravity, OpenCode, Aider, Qwen Code, Kimi Code, and Factory Droid. Cursor, GitHub Copilot, Goose, Warp, and Ollama leave nothing Kangentic can hand on, so a task moving out of one of those starts the next agent with a pointer to git log instead of a transcript.

Any agent can be on the receiving end. A task moving into Cursor from Claude Code still hands Cursor the path to Claude’s transcript. Claude additionally gets a note that it can read the prior session through the kangentic_get_session_history MCP tool.

Kanban-based control

Each task card on the board is a potential or active coding-agent session, and the column it sits in decides what happens to that session. Default board layout is the one place the seven default columns are documented. In short: To Do holds a card with no session, Planning spawns the agent in plan mode, Executing spawns it in its default permission mode, Code Review, Testing, and Merge keep it running, and Done suspends the session and archives the task.

None of these column names reach the agent. A column only speaks to a running agent through an automation’s message, a Send message to agent row or the message on a Move to column row, and no default column carries one. What the agent is told lists exactly what crosses over.

Drag a card between columns to change its state. Every column except To Do and Done is fully customizable; see Adding and editing columns for the options.

Spawning agents

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

Creates a git worktree for the task (if worktrees are enabled)
Launches the column’s agent CLI in that worktree
Passes the task’s title and description, wrapped in a <task> envelope, plus any attachment paths, as the first prompt (What the agent is told shows the exact format)
Connects the agent’s terminal to a tab in the bottom panel

The agent starts at once. Watch it in the terminal, or move on to other tasks.

Card indicators

Every state a card can show, and the page that owns the detail:

Indicator	Meaning
Pulsing spinner	The agent is thinking or running tools (Activity detection)
Static icon	The agent is idle: finished, waiting, or asking for input. An idle card also raises the idle badge and notifications
Queued…	Waiting for a concurrent-session slot (the session queue)
Switching model…, Switching agent…, Applying new settings…, Starting new session…	A move suspended the session and a respawn is in flight (Session persistence)
(base N behind), (base fetch failed)	The spawn measured the worktree against its base branch (Starting from a fresh base)
Message trail	The agent’s latest message, pushed live into the card. Settings > Task > Card preview picks Latest (the agent’s newest message, the default), Recent (its recent messages), or Description (below)
Context bar	Token usage and context-window percentage, when the agent reports a window size (Native session history)
PR badge	The linked pull request’s state: open, draft, merged, or closed, and for an open PR ready, blocked, conflicts, queued, or running (Merge readiness on the badge)
Restore in progress	The card is coming back out of Done and its worktree is being rebuilt (When resume is refused)

The message trail

While a task’s agent is running, its card prints the agent’s newest message under the title, in a shaded terminal panel, in place of the task description. The panel updates live as the agent works, so you can follow progress without opening a terminal tab or the task window. The card goes back to its description while the session is paused or ended, and while the agent has not said anything yet. For Claude Code, the narration lines it prints between tool calls count as messages too. Before v0.45.0 the app read them as thinking, and they never reached the card. Card preview in Settings > Task picks Latest, Recent (the recent messages, one line each), or Description. The Agent Monitor renders the same panel.

Suspending and resuming

Suspend and resume are how the board holds more work than the machine can run at once.

Suspend - Press Pause in the task window, or move the task to Done or to a column with auto-spawn off. The session ID is kept and the agent process stops.
Resume - Move the task to an active column, or press Resume on a paused card. The agent picks up with its full conversation. Session resume is supported for Claude Code, Codex, Gemini, Cursor, GitHub Copilot, Grok, Antigravity, Goose, OpenCode, Qwen Code, Kimi Code, and Factory Droid. Aider, Warp, and Ollama relaunch fresh on re-entry.

Session queue

Each agent is its own CLI process with its own worktree, terminal, and conversation. Max concurrent sessions (Settings > Behavior, agent.maxConcurrentSessions, default 8) caps how many run at once, across every agent. A spawn past the cap queues, the card shows Queued, and the next queued session starts, first in first out, when a running one exits or suspends. The When max sessions are reached choice beside it (agent.queueOverflow) offers queue and reject, but nothing reads it: every spawn past the limit queues, and picking reject leaves the task queued rather than in its column.

The limit is global, not per-project, so three projects each running agents share one pool. Lower it if the machine runs out of memory or CPU with many agents running, and raise it if the machine has headroom. Both keys are in the Configuration reference.

Board search and filtering

The board toolbar has a docked search box (Ctrl+F / Cmd+F focuses it) and a Filter button for priorities and labels, shared with the Backlog view. Quick Find documents both, and Ctrl+Shift+F / Cmd+Shift+F opens Quick Find itself for search across tasks, backlog items, session events, conversations, and projects.

Task descriptions

Write a task description the way you would prompt the agent directly: name the file, the symptom, and the acceptance test.

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 agent gets the title and description as its first prompt. Creating tasks covers descriptions, attachments, labels, and priorities.

Agent-to-board integration (MCP)

Every spawned session holds Kangentic’s built-in MCP server, on by default, so an agent can create follow-up tasks, search existing ones, read transcripts, and move its own card when the work is done. The server exposes 90 tools in six groups:

Group	What it covers
Tasks	Create, list, search, find, update, move (within a board or to another project’s board), reorder, delete, link PRs, and remove attachments for individual tasks
Board	Columns and their automations, board profiles, the backlog, project discovery, usage stats, and unified search
Workflows	Plan, start, pause, resume, and delete a workflow of linked tasks, change its tasks, links, and routes, and give its agent read access to another project
Sessions	Session records, transcripts, activity events and interval history, dev-server port reservations, handoff context, and messages steered into another task’s session
Browser automation	Open, close, and drive a task’s embedded Browser pane (navigate, screenshot, click, type, eval)
Diagnostics	Read-only inspection: logs, crashes, process metrics, IPC traffic, worktrees, and SQL

How the MCP server works explains the transport and the per-agent wiring. The MCP tool reference describes every tool; every task, backlog, and session tool takes an optional project parameter for cross-project calls. To turn the server off, switch MCP server off in Settings > MCP Server or set mcpServer.enabled to false (Configuration reference).

Steering another task’s agent

One agent can read and steer another. kangentic_get_transcript reads what the agent on another task, or in another project, has said. kangentic_send_session_message types a message into that agent’s running session the way a paste would: to answer a question it is waiting on, unblock it, or redirect work a newer decision replaced. By default the message goes in at once and a busy agent reads it when its turn ends; deliverWhen: "idle" holds it until the turn is over.

The message arrives verbatim, with nothing prepended, so the receiving agent cannot tell another agent wrote it. Kangentic records who sent it out of band instead, from the calling session stamped into the agent’s MCP URL at spawn (MCP security and network access). A message is refused when it targets the sender’s own session, a session that has ended or sits at a permission prompt, or a session past its per-target rate limit. kangentic_get_session_messages_sent lists every attempt with its status: delivered, queued, refused, or failed.