Creating Tasks

Tasks are how you give work to agents. Each task becomes a prompt - the title and description are delivered as the agent’s first message, wrapped in a small <task> envelope.

Creating a Task

Click the + button on any column header, or use the New Task button in the toolbar. Enter a title and an optional description. You can also set a priority level, add labels, and attach files.

The title and description together become the agent’s prompt (see What the Agent Is Told for the exact format), so write them the way you’d prompt Claude Code directly. Be specific about what you want - reference files, error messages, or test cases.

Descriptions support Markdown rendering with full GitHub Flavored Markdown - tables, task lists, strikethrough, and links all render in the task detail dialog.

Writing Descriptions

The description box is a source-first markdown editor with a compact Write | Preview toggle. It is deliberately not WYSIWYG - the text you write is interpolated verbatim into the agent’s prompt. Editing conveniences:

• Enter continues -, *, 1., and - [ ] list markers (ordered lists increment, checkboxes reset, and an empty marker clears itself); Tab / Shift+Tab indent and outdent inside a list
• Ctrl+B / Cmd+B, Ctrl+I / Cmd+I, and Ctrl+K / Cmd+K wrap the selection in bold, italic, or a link
• Pasting a URL over selected text produces [selection](url); pasting rich HTML converts to markdown automatically; Ctrl+Shift+V / Cmd+Shift+V pastes plain
• Edits flow through the native undo stack, so undo and redo behave like any text field

@-Mention File Autocomplete

In the description field, type @ to trigger file autocomplete. A dropdown lists files and directories from the project root. Navigate with arrow keys and press Enter to insert the selected path. This works in both the task creation form and the task detail dialog’s edit mode.

File Attachments

You can attach files of any type to a task:

• Paste - Press Ctrl+V / Cmd+V to paste from your clipboard
• Drag and drop - Drop files onto the task creation form or the task detail dialog

Images, documents, logs, and any other file type are supported. Attachments are included in the agent’s first prompt as file paths listed after the task text. They render as a compact chip strip under the description - each chip keeps a small preview and an always-visible remove control. Right-click an image chip to copy it to the clipboard, or click one to open a full-size preview.

Pasted Screenshot Compression

Pasted screenshots larger than 500 KB are auto-compressed before they’re attached. Kangentic resizes the long edge to 2000 px and re-encodes as WebP, walking a quality ladder until the encoded blob fits under ~1.5 MB - well below Claude’s 5 MB per-image cap, so large screenshots no longer fail with HTTP 400. PNGs that already fit the target are left alone (so icons keep their alpha), and GIF/SVG, drag-dropped files, and PDFs are never recompressed. If the pipeline fails for any reason, the original bytes are attached and a single warning toast fires - pastes never silently disappear.

2000 px is a measured floor rather than a round number. Token cost tracks pixel area only up to roughly 2.25 megapixels and then flattens, so a 4K paste and a 2000 px paste cost the same and downscaling below the plateau is the only thing that saves anything. Measuring what that costs in accuracy is what set the floor: at 2000 px, a probe set of small UI affordances and text read correctly every time, while the same set at 1568 px produced silent misreads - a branch hash off by two characters, the wrong bar named in a three-bar chart - with no hedging from the agent. An agent misreading the screenshot you pasted to explain a bug costs far more than the extra tokens.

Labels and Priorities

Each task can have labels and a priority level:

• Labels - free-form text tags for categorizing tasks (e.g., “bug”, “frontend”, “refactor”). Labels can have custom colors and are shared between the backlog and the board.
• Priority - a severity level from the project’s priority scale. The default scale is None, Low, Medium, High, Urgent. Priority shows as a colored badge on the task card and in the detail dialog header.

Set labels and priorities when creating a task, or edit them later in the task detail dialog. Labels and priorities carry over when promoting tasks from the backlog to the board.

Display ID

Every task has a short display ID (e.g., #42) shown on the task card and in the detail dialog header. Click the ID to copy it to the clipboard. Display IDs are also available via the MCP tools.

Worktree Toggle

Each task has a Main / Worktree toggle that controls whether the agent runs in an isolated git worktree or directly in your main working directory.

This is a per-task override of the global worktree setting. Use it when you want a specific task to run in main (e.g., a quick config change) while keeping worktrees enabled for everything else.

See Git Worktrees for details on how worktrees work.

Branch Names

The Branch control in the task dialog combines the worktree chip, the base-branch picker, and a branch-name input. The input’s placeholder shows the auto-generated name the task will get if you leave it alone; type your own to override it (invalid git branch names are rejected as you type). Naming a branch that already exists checks that branch out into the task’s worktree instead of creating a new one - useful for pointing a task at work that already started elsewhere.

The name is only editable while the task sits in To Do. Once a worktree exists the branch is real, so the field switches to showing the base branch instead.

Base Branch

By default, worktrees branch from the global defaultBaseBranch (usually main). You can override this per-task when creating a task - useful when you want the agent to work on top of a feature branch.

The base branch priority order is:

1. Task’s base branch (per-task override)
2. Action config’s base branch (per-transition override)
3. The team-shared defaultBaseBranch in kangentic.json
4. Your git.defaultBaseBranch setting (default: main)

Task Context Menu

Right-click any task card on the board to open a context menu:

• Copy Task ID - copies the display ID (e.g., Task #42) to clipboard in a format optimized for MCP context
• Edit - opens the task detail dialog in edit mode
• Changes - open the Changes panel for this task, showing the git diff against the base branch
• Move to - submenu listing all other columns as move targets
• Backlog - send the task back to the backlog (cleans up session and worktree)
• Archive - move the task to Done
• Delete - permanently delete the task, session, and worktree

Note

When you move a task with pending uncommitted changes back to To Do, Kangentic shows a confirmation dialog so you don’t accidentally lose work. The card stays in place until you confirm.

Reordering Tasks

Drag task cards within a column to reorder them. The order persists across app restarts.

Agents can order a column too, which is useful when you ask one to triage a backlog into the sequence you should work it. kangentic_reorder_tasks sets the top-to-bottom order of a column in a single call: the task IDs you list take the top slots in that order, and anything you leave out keeps its relative order below them. kangentic_move_task also accepts a position, a zero-based slot in the destination column, so an agent can file a task straight into the right place instead of appending. Neither spawns, suspends, or otherwise touches a session; naming a task’s current column with a position just repositions it in place.

Task Detail Dialog

Click any task card to open its detail window - a modeless window you can drag, resize, snap, and tile over the board, with the terminal, header pills, the Changes and Browser panes, and the Commands popover inside. It has its own page now: see Task Detail Window.

Completed Tasks

Tasks in the Done column are archived automatically, and the completed-tasks dialog is where they live afterward - a sortable table with per-session cost summaries, bulk restore and delete, and resume-with-context. It has its own page now: see Completed Tasks.

Auto-Naming

Tasks created without a title - for instance, transient sessions opened from the Command Terminal, or backlog items dropped into a column without one - get a one-shot title summarized from the prompt by the active agent. Kangentic spawns the CLI in non-interactive --print mode for the summarize call (Claude, Codex, Gemini, Cursor, Copilot, Grok, Antigravity, OpenCode, Qwen, Kimi, and Factory Droid all support this; Aider, Warp, and Ollama opt out). The suggested title appears in a banner; accept, edit, or dismiss.

Per-Task Agent, Model, Effort, and Permission Overrides

Each task can override the agent, model, reasoning effort, and permission mode independently of the column defaults. There are two places to set them:

How this task runs (New Task and Edit dialogs). The dialog asks the question directly, with two mutually exclusive cards - picking one clears the other, and the choice persists with the task:

• Column Settings - each column applies its own settings as the task moves. This card carries a Profile dropdown to ride a named Board Profile instead of the columns’ own ladder (disabled until the board has one - profiles are created in Edit Columns).
• Agent Override - pick an agent, model, effort, and permission mode pinned for the whole task. Available models and effort levels are capability-gated by the selected agent - only what its CLI actually supports is shown. Each picker pre-fills with the resolved default (column, then project, then agent default), so you can see what the task will spawn with before changing it. An edit pencil beside the Agent field jumps to Settings > Agent. When only one CLI is detected the agent row shows disabled rather than hiding, so the option stays discoverable.

Context bar (running session). Click the profile, model, or effort pill in the context bar above the terminal to open the same pickers live. When no session has spawned yet, a pre-spawn version of the bar lets you set overrides without going through the spawn-then-cancel-and-restart loop.

Behavior (since v0.30.0, the Agent Override picks are a contract that locks at first spawn; a task riding a Board Profile never trips this lock - its ladder keeps applying):

• First spawn locks all four fields. If the Agent Override card is selected when the task spawns for the first time - even with every field left on its resolved default - all four lock to exactly the values the card displayed: explicit picks stay as picked, and the still-inherited fields freeze to what they resolved to at configuration time (the column the task lived in when you configured it, then the project default). The destination column’s settings never leak into the locked contract - you never saw them in the dialog.
• Column moves cannot change a locked task. A locked agent means moving between columns never changes which CLI runs the task; a locked permission mode wins over the column’s and the global agent.permissionMode. The one exception: a column that forces plan mode (a Planning column) still wins for spawns from that column, but the locked permission is what the task runs under everywhere else.
• A task left on the Column Settings card is untouched: it keeps following column and project defaults for its whole life.
• Resetting to To Do does not unlock. The lock keys off the task’s first-ever spawn, so a task that spawned once, was reset, and is redragged forward keeps its locked contract.
• Before the first spawn, per-task overrides win over per-column overrides, and clearing one in the picker falls back to the column or project default. After the first spawn the fields are frozen.
• Model and effort overrides live-apply via the agent’s /model and /effort slashes when a session is running.
• On a cross-agent handoff (moving to a column whose effective agent differs), model and effort overrides are cleared automatically because they are model-name-specific. Since the first-spawn lock, this mainly applies to picks made mid-session on a task that spawned with no overrides - a task with a locked agent never hands off via column moves in the first place.

Discovered models are cached in discoveredModelsByAgent so the picker stays populated across restarts and grows live from session usage events.

Column Management

Adding and Editing Columns

Open Edit Columns from the board toolbar. The unified manager lists every column on the left and shows the editable fields for the selected column on the right. Add, rename, reorder, and configure columns from one place - there is no separate “Add Column” dialog. The manager can be maximized (the header toggle, a double-click on its title bar, or Ctrl+Shift+M / Cmd+Shift+M) when you have a lot of columns to work through.

The column rail is headed by a Profile switcher for Board Profiles - named alternate per-column strategy ladders. While a profile is selected, the editors show that profile’s values and column structure is locked (no add, reorder, or delete): structure belongs to the board, profiles only change what columns do.

For each column you can configure:

Setting	Description
Name	Column display name
Description	Optional column description, shown as a tooltip on the column header. Display only: it is never sent to the agent
Color	Header accent color
Icon	Lucide icon name (e.g., square-terminal, code, flask-conical)
Agent Override	Use a specific agent (Claude Code, Codex CLI, Gemini CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, OpenCode, Aider, Qwen Code, Kimi Code, Factory Droid, Warp/Oz CLI, or Ollama) for sessions in this column instead of the project default. Hidden for To Do / Done columns
Permission Mode	Override the global permission mode for agents in this column. The dropdown re-populates based on what the selected agent supports
Model Override	Adapter-specific model identifier (e.g. opus, gpt-5-codex). Live-applied via /model when a running session moves into the column. Hidden when the adapter has no --model flag
Effort Override	Adapter-specific reasoning level (e.g. low, medium, high, xhigh, max). Live-applied via /effort on column transition. Hidden when the adapter doesn’t expose effort levels
Start an agent here	Whether moving a task here spawns an agent (the auto_spawn toggle; default: on)
Message to agent	Sent to the running session when a task arrives in this column. Plain prose or a slash command; an insert-variable picker in the field offers the template variables. Stored as autoCommand in kangentic.json and auto_command in the database
Message timing	When that message is delivered: Run immediately (default - delivered on arrival, and queued by the CLI if the agent is mid-turn) or Wait for current turn, which holds it until the agent finishes what it is doing. Neither interrupts a running turn
Receive context from prior agent	Pass the prior agent’s native session history file as context to the new agent on column entry (the handoff_context toggle)
After Plan Mode	For plan-mode columns: where tasks auto-move when planning completes
Session	Which session track a task runs on in this column: Main session (the shared conversation carried between normal columns) or Isolated session (this column’s own context-isolated session). Forced to Main for To Do / Done
On enter	What happens to that track on column entry: Create or resume (resume the track’s session if one exists, else spawn) or Always spawn new (start a fresh pass, retiring the prior session)

Toggle settings (Start an agent here, Receive context from prior agent) use a click-anywhere card affordance - the entire row is the click target, not just the switch.

Reordering Columns

Drag column headers on the board, or drag rows in the Edit Columns list, to reorder.

Deleting Columns

Delete a column with the trash control on its selected row in Edit Columns. Columns can only be deleted when they contain no tasks - move or delete all tasks first - and the role columns (To Do and Done) carry no delete control at all. Like adding and reordering, deletion is staged until you Save, so Cancel still undoes it. Saving a delete also cleans up in one transaction: lane transitions, other columns’ plan-exit targets, and any Board Profile entries that referenced the column.

Next steps

Next: Backlog - stage tasks before promoting them to the board.

See also:

• Custom Workflows - automate what happens when tasks move
• Git Worktrees - control how tasks get their isolated workspaces