Task Lifecycle

How tasks move through Konduktor, from creation to completion.

Board columns

Tasks live on a kanban board with these columns:

idea → to_do → in_progress → pr_submitted → done
                                              ↓
                                            trash

Column	Meaning
idea	Backlog — tasks that might be worked on
to_do	Ready to work on
in_progress	An agent is actively working on this
pr_submitted	A PR has been created and is awaiting review/merge
done	Completed (PR merged or manually marked done)
trash	Soft-deleted (can be restored)

Creating a task

konduktor tasks create <workspace> --title "Add search feature" --priority p1

Tasks start in idea by default. Use --status to_do to place them directly in the to-do column.

Priorities

Priority	Level
p0	Critical
p1	High
p2	Medium (default)
p3	Low
p4	Lowest

Running a task

konduktor tasks run <workspace> <task-id>

This:

1. Creates an isolated git worktree for the task (branched from main)
2. Spawns a detached Claude Code process in that worktree
3. Moves the task to in_progress
4. Creates a new session to track the run

The agent receives the task title, description, and any agent-visible workspace documents as context.

Worktree isolation

Each task runs in its own git worktree, so multiple tasks can run concurrently without interfering with each other. Worktrees are kept around after the task finishes so that resume and fix-conflicts can reuse them.

Orphaned worktrees (older than 24 hours with no active session) are automatically cleaned up.

Concurrency

The server supports up to 6 concurrent task executions by default.

Sessions

A session is a single agent execution run. A task can have multiple sessions:

• Initial run — the first tasks run
• Resume — a follow-up run in the same worktree with additional instructions
• Retry — a fresh attempt after a failure
• Fix conflicts — a resume specifically for resolving merge conflicts

Each session logs its output to a JSONL file on disk. You can view logs via:

konduktor sessions logs <workspace> <session-id> --pretty
konduktor sessions logs <workspace> <session-id> --follow  # live tail

Session statuses

Status	Meaning
queued	Waiting to start
running	Agent is executing
completed	Finished successfully
failed	Exited with an error
stopped	Manually killed
stuck	Killed by the stuck detector

PR creation

When the agent creates a GitHub PR during execution, Konduktor:

1. Auto-detects the PR URL from the session logs
2. Saves it on the task
3. Moves the task to pr_submitted

PRs created by Konduktor agents include a kid tag in the title (e.g. [kid: #4d9d444d]) that links the PR back to the task.

PR merge and completion

If you have a GitHub App configured, Konduktor receives webhooks when PRs are merged. When a PR with a kid tag is merged, the linked task automatically moves to done.

Without a GitHub App, move tasks to done manually:

konduktor tasks move <workspace> <task-id> done

Resuming a task

konduktor tasks resume <workspace> <task-id> --prompt "Also add error handling"

This spawns a new session in the existing worktree with the additional prompt. The agent picks up where it left off, with all previous changes intact.

Fixing merge conflicts

konduktor tasks fix-conflicts <workspace> <task-id>

This is shorthand for resume with a conflict-resolution prompt. The agent will attempt to resolve merge conflicts in the worktree and push the result.

If auto_fix_merge_conflicts is enabled in workspace config, Konduktor does this automatically when conflicts are detected.

Retrying a failed task

konduktor tasks retry <workspace> <task-id>

Retries the task — a new session is created. The attempt number increments.

Stopping a task

konduktor tasks stop <workspace> <task-id>

Kills the running session immediately.

Stuck detection

If an agent produces no output for 2 hours (configurable), the stuck detector kills the session and marks it as stuck. This prevents runaway processes from consuming resources indefinitely.

Diagram

  tasks create
       │
       ▼
    ┌──────┐    tasks move     ┌───────┐
    │ idea │ ───────────────── │ to_do │
    └──────┘                   └───────┘
                                  │
                              tasks run
                                  │
                                  ▼
                            ┌─────────────┐
                            │ in_progress │ ◄── resume / retry / fix-conflicts
                            └─────────────┘
                                  │
                          agent creates PR
                                  │
                                  ▼
                          ┌──────────────┐
                          │ pr_submitted │
                          └──────────────┘
                                  │
                          PR merged (webhook)
                          or manual move
                                  │
                                  ▼
                              ┌──────┐
                              │ done │
                              └──────┘