Skip to main content

​
Board columns

Tasks live on a kanban board with these columns: 
idea → to_do → in_progress → pr_submitted → done
                                              ↓
                                            trash
ColumnMeaning
ideaBacklog — tasks that might be worked on
to_doReady to work on
in_progressAn agent is actively working on this
pr_submittedA PR has been created and is awaiting review/merge
doneCompleted (PR merged or manually marked done)
trashSoft-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

PriorityLevel
p0Critical
p1High
p2Medium (default)
p3Low
p4Lowest

​
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

StatusMeaning
queuedWaiting to start
runningAgent is executing
completedFinished successfully
failedExited with an error
stoppedManually killed
stuckKilled 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 │
                              └──────┘