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 Add task at the bottom of the To Do column, or New Task on the board 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; What the agent is told shows the exact format. Write them the way you would prompt the agent directly, and be specific: reference files, error messages, or test cases. With an Automation agent set up, a sparkle button beside the title can write it from the description (see Auto-naming).

Descriptions render as GitHub Flavored Markdown in the task detail window: tables, task lists, strikethrough, and links.

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 open file autocomplete. A dropdown lists files and directories from the project root; move with the arrow keys and press Enter to insert the selected path. It works in the New Task dialog and in the task detail window’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 New Task dialog or the task detail window

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 task detail window’s header.

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

Display ID

Every task has a short display ID (#42) shown on the task card and in the task detail window’s header. Click the ID to copy it to the clipboard. The MCP tools accept display IDs too.

Where the agent runs

The Worktree | Project control beside the Branch field chooses whether the agent runs in an isolated git worktree or in the project folder itself, the checkout you have open in your editor. It is a per-task override of the global worktree setting: use Project for a quick config change you want landing on your working copy while keeping worktrees on for everything else.

The line under the Branch row states the outcome before you create the task, for example “Auto-generated branch will be created from main in a new worktree” or “Runs in the project folder on main”. When the project cannot have a worktree (not a git repository, no commits yet, the folder is itself a worktree, or the agent runs on a remote server), the Worktree option is disabled with the reason in its tooltip.

See Where the agent runs for the full picture, including how the task detail shows which one a running task got.

Branch names

The Branch field in the task dialog pairs a branch-name input with the base-branch picker in one shell, with the Worktree | Project control standing beside it. 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

The base-branch picker beside the Branch field overrides, for this task, the branch its worktree is cut from. Leave it alone and the worktree branches from the board’s defaultBaseBranch in kangentic.json, or failing that your git.defaultBaseBranch setting (default main). Pick a branch when the agent should work on top of a feature branch. Base branch has the full ladder and how the base is kept fresh.

Working with cards

What you can do with a card once it exists: its menu, its order, its window, and the overrides it carries.

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

Copy Task ID - copies Task #42, the form the MCP tools accept
Edit - opens the task detail window in edit mode
Changes - open the Changes panel for this task, showing the git diff against the base branch. Only offered while the task has a worktree
Move to - submenu listing all other columns as move targets
New workflow - plan a workflow starting from this task. Offered on a To Do card that is in no workflow
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

On a task in a running workflow, a move the workflow’s lock refuses, and Backlog and Archive, stay in the menu disabled, with the reason on hover.

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 window

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. 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. See Completed tasks.

Auto-naming

Kangentic can write a task’s title from its description in two ways:

Name from prompt, the sparkle button beside the title field in the New Task dialog, the backlog’s new-item dialog, and the task detail window’s edit mode. It fills the title from the description you have written so far.
A rename suggestion. When a task’s agent has been running for 30 seconds and the title is still a placeholder (empty, the task’s own ID, or a word like fix, wip, todo, test, or untitled), a toast offers Rename to ”…”? with a Rename button. Each task is asked once, and a task with no description is never asked.

Both run on the Automation agent, with its model and effort, which you choose in Settings under Workflows. With no Automation agent set up, naming is off: the button is hidden and no suggestion appears. The agent has to be one that can summarize: Claude Code, Codex, Gemini CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, OpenCode, Qwen Code, Kimi Code, or Factory Droid. Command Terminals are named by the same agent. Before v0.46.0 naming ran on the CLI’s default model with the project’s instructions, tools, and MCP servers loaded, which on Claude Code cost about 120,000 tokens for a title of a few words.

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 the Column Manager).
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.

The Agent Override picks are a contract. Since v0.41.0 the lock fires when the task first leaves To Do, or spawns for the first time, whichever comes first. A task riding a board profile never trips it, because its ladder keeps applying. The rules:

Leaving To Do locks all four fields. If the Agent Override card is selected when the task leaves To Do for a spawn column - or spawns for the first time ever, whichever comes first - all four fields 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 that moment (the column the task was configured in, 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 keeps the pins but re-arms the lock. A task that locked, was reset, and is redragged forward keeps its contract - nothing in To Do erases the four fields. To Do is where the gate reopens, though: clear a field there and the next move out re-resolves it and pins it again, to whatever the dialog was showing at that point.
Before the lock, per-task overrides win over per-column overrides, and clearing one in the picker falls back to the column or project default; unpinned fields keep resolving live while the task sits in To Do. After the lock the fields are frozen.
Model and effort changes reach a running session without you typing anything. Kangentic suspends the session and resumes it with the new --model or --effort flag, so the conversation carries over and the card reads Switching model… (or Applying new settings… for an effort change alone) for a couple of seconds. The restart ends the turn in progress, so pick between turns when you can. Nothing is typed into the terminal. Before v0.45.0 an effort change went in as a live /effort on Claude and Copilot, but a mid-turn /effort leaves no record that it landed, so it now restarts the session like a model change. A session already running at the new value, or a move into a column left on its default, restarts nothing. A level the model lowers on its own, such as max on a model that tops out at high, counts as applied once the session has been launched at it, so later moves into the column restart nothing either. The Command Terminal is the exception and still switches live.
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 override 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.

The models a picker offers are what the agent’s CLI reports right now, plus the ones you have run before. Kangentic keeps no list of its own. When the agent offers floating aliases, the Model list leads with a Latest group: pick one and the task follows each new release of that model, while a specific version stays put. See Model picker for how discovery works and how the list is grouped.