Creating Tasks

Tasks are how you give work to Claude Code agents. Each task becomes a prompt - the title and description are passed directly to the agent when it spawns.

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, 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.

@-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 (Windows/Linux) or Cmd+V (macOS) 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 prompt when it spawns. Right-click an image attachment to copy it to the clipboard, or click any thumbnail 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 1568 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.

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.

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. Global 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.

Task Detail Dialog

Click any task card to open its detail dialog. From here you can:

• View the task’s display ID (e.g., #42) in the header - click to copy
• See the priority badge next to the display ID
• View Markdown-rendered descriptions with GFM support
• Edit the title, description, priority, and labels
• View and manage attachments of any file type (drag-and-drop or paste)
• See terminal output - the dialog takes ownership of the terminal session while open
• View session stats - usage, model info, and session status
• Pause or resume the agent session using the header button
• Run shortcuts from the header bar
• Open the Commands popover to browse and run Claude Code commands and skills
• Access the kebab menu for move, archive, open folder, view PR, and delete

When the dialog is open, the bottom terminal panel releases the session. Closing the dialog returns it to the bottom panel.

Changes Panel

The Changes panel shows a full git diff viewer for the task’s worktree against the project’s base branch:

• File tree - click any file to view its diff. The first file is auto-selected when you open the panel
• Split / inline toggle - switch between side-by-side and inline diff modes
• Expand / collapse - hide the file tree to give the diff more room
• Untracked files - uncommitted new files are visible alongside modified files
• State persistence - your expand state, split mode, and last-selected file are remembered per task

Open the Changes panel from the task context menu, from the kebab menu in the task detail dialog, or from the Command Terminal dialog. It stays open next to the terminal without flicker.

Completed Tasks

Tasks in the Done column are archived automatically. You can browse and search completed tasks from the Done column.

Sorting

Sort completed tasks by different criteria to find what you need:

Sort Option	Description
Date	When the task was completed (default)
Cost	Total API cost of the session
Tokens	Total tokens consumed
Duration	How long the session ran

Bulk Operations

The completed tasks dialog supports bulk actions:

• Unarchive - select multiple tasks and move them back to the board at once
• Delete - permanently remove multiple completed tasks and their associated worktrees

Unarchiving

To resume work on a completed task, drag it back to any active column. The suspended session is resumed with its full context intact.

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, Qwen, Kimi, Copilot, OpenCode, and Cursor all support this; Aider and Warp opt out). The suggested title appears in a banner; accept, edit, or dismiss.

Per-Task Agent, Model, and Effort Overrides

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

Advanced section (New Task and Edit dialogs). Expand the Advanced disclosure to pick an agent, model, and effort before the task is saved. Available models and effort levels are capability-gated by the selected agent - only what its CLI actually supports is shown.

Context bar (running session). Click the model pill or effort pill in the context bar above the terminal to open the same picker 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:

• Agent override locks the agent for the task’s lifetime. Once set, moving the task between columns will not change which CLI runs it - task.agent_override wins over swimlane defaults and the project default.
• Model and effort overrides persist on the task and live-apply via the agent’s /model and /effort slashes when a session is running.
• On a cross-agent handoff (e.g. moving to a column whose effective agent differs), model and effort overrides are cleared automatically because they’re model-name-specific. If an explicit agent override is set, the picks are kept (they were made for the locked agent).
• Per-task overrides win over per-column overrides. Clear them in the picker to fall back to the column or project default.

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.

For each column you can configure:

Setting	Description
Name	Column display name
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, Qwen Code, Kimi Code, OpenCode, Factory Droid, Cursor CLI, GitHub Copilot CLI, Aider, or Warp/Oz CLI) 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
Auto Spawn	Whether moving a task here spawns an agent (default: on)
Auto Command	Command injected into running sessions when tasks arrive
Handoff Context	Pass the prior agent’s native session history file as context to the new agent on column entry
Plan Exit Target	For plan-mode columns: where tasks auto-move when planning completes

Toggle settings (Auto Spawn, Handoff Context) 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

Columns can only be deleted when they contain no tasks. Move or delete all tasks first.

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