Skip to main content

​
Prerequisites

​
Part one: Create and run a task using a background agent

​
Create a workspace

The first thing you need to do to start using Konduktor is create a workspace. This is as simple as clicking the “New workspace” button from the Konduktor home page and pasting in a GitHub repo URL. You can also do this via the CLI like so: 
konduktor workspaces create https://github.com/myorg/myrepo

​
Create a task

Now that you’ve created a workspace, you can create and run a task. Tasks are the basic unit of work in Konduktor, and they are somewhat analogous to tickets in project management tools or issues on GitHub. Creating a task will place it on the board so you can keep track of work, and you can either pick it up yourself, or, more interestingly, start a Claude Code session in the background to complete your task. To create a task in the UI you need to be inside your desired workspace, and you can then click “New task” on the top right of the “Board” page or you can simply use the keyboard shortcut CMD + K to open the command bar and start typing a title. An option to create task will pop up and you can then fill in the rest of the details in the modal. From the CLI, creating a task is even simpler: 
konduktor tasks create \
    --title "bug: component re-renders 3 times on first load" \
    -w <workspace_name>
Pro tip: If you know you’ll mostly be working on one specific workspace, you can run konduktor workspaces set-default <workspace_name> to avoid having to append all CLI command calls with the -w flag and the workspace name.
The CLI also let’s you add tags, priority, a description, a status (maps to board column), and more. Anything you can do in the UI you can do using the CLI. If task creation succeeded, you’ll see a response like: 
Task created: d80339c4 "bug: component re-renders 3 times on first load"

​
Run the created task

From the UI, running the task can be done in like 4 different ways. You can click the little play button that appears when you hover on a task card, open the task modal and click “Run task” on the top right, search for the task using the command bar and use the shortcut CMD + R, and you can also click “Create and run” (or use the shortcut) when creating a task. To run a task from the CLI, we’ll need the short task ID returned to us in the previous command. Most objects in Konduktor (tasks, projects, questions) have full UUIDs. However, since the chance of collision is unlikely, Konduktor CLI commands all support short IDs for ergonomics. If you ever run into a conflict, just use the full task ID. 
konduktor tasks run d80339c4 -w <workspace_name>
And that’s it! You now have a running task and will soon get a PR on your repo for it. If you merge it, the task will automatically be moved to “Done”, and if yu close it, the task will automatically move to “Closed”. And this isn’t all we can do with tasks. Tasks can be resumed, we can enable auto-fixing for merge conflicts and CI failures, inspect logs, and a lot more, which is what we’ll cover in Part Two. But first, a quick note on tasks and sessions.

​
What does running a task mean?

Running a task will create a Claude Code session that gets passed your task’s context as the prompt and creates a new worktree for your repo to work on. We keep the worktree around until the task is marked as “Done” or “Closed” which means triggering a resume via the UI or CLI will mean the agent just picks up from where it left off. You can stop running sessions, and you can get complete logs for each of them. Logs never get deleted. The default system prompt instructs the agent to create a PR once it’s done, but you can change this system prompt in the “Workspace Config” page (or using the CLI) if you’d prefer to not get PRs and instead do something else. We have a whole system built around sessions to handle edge cases that may come about, like sessions dying or sessions becoming orphaned and running “forever” (or appearing to do so). Periodic processes will, among other things, clean up worktrees and orphaned sessions, meaning we only keep stuff that’s useful on disk (a lot of worktrees can use up a lot of space). Agent sessions also have access to the Konduktor CLI internally, which means they can look at what else is on the board, update the task status, create docs, create questions, and do basically anything you can do yourself, which brings us nicely to the concept of scheduled agents.

​
Part two: Scheduled agents

Scheduled agents are Claude Code sessions that run periodically on a schedule you’ve set. Basically a cron job that triggers a Claude Code session. They use similar mechanisms to task agents but are meant to be used for a different purpose. Again, the key part is that they have access to the Konduktor CLI so they can scan everything that’s going on (the board, the open questions, the docs) and act on it accordingly (create tasks, update projects, create questions, run tasks). For instance, I’m currently running five scheduled agents:
  1. pr-reviewer (every 30 min): Reviews PRs from tasks in the “PR Submitted” board column. What’s nice is that the reviewer has full context of my project because it not only has the code but also the product docs, the board status, etc. and it can run tests, actually run code, and so on. This makes the reviews really useful.
  2. ideator (every 12h): The ideator agent is told to analyze the codebase, docs, and board and create a well-scoped task in the Ideas column that would be a useful feature to have right now. AI ideas are of course limited, but we can’t always think of everything, and I’ve gotten both great fully-formed ideas from the ideator plus have derived ideas from concepts it pointed me towards. This is only two ideas a day so it’s not a massive cognitive load and it’s easy to dismiss or accept. Keeps me open-minded and helps prevent me from getting stuck, since I can always just protoype a new idea and see if it makes sense.
  3. bug-fixer (every 12h): Audits a part of the codebase for major bugs and creates and runs one task to fix the most impactful bug it finds. I started off having this run more regularly, but I realized it was a bit too much for me. Two ideas per day + two unprompted bug fixes is enough context that I’m not already considering. Since I wasn’t looking for the bug myself, context switching to understand it deeply and its fix can take a bit of energy, but I’m happy to spend that energy twice a day as a tradeoff for having a more robust codebase.
  4. challenger (every 8h): Looks at tasks with the needs-spec tag (my own concept) and asks questions about them. Sometimes I have an idea for something but I’m working on something else. In order to not disrupt my flow, I’ll just throw it as a to-do or idea in Konduktor and get back to what I’m doing. The challenger then goes into these tasks, infers what’s needed from the code, and asks me targeted questions to help me scope it better when I have time, instead of me having to go in and do that ground work myself.
  5. project-runner (every 2h): If I have a project with the agent-ready tag, the project-runner will see if there are recently unblocked tasks and then trigger them. This helps move projects that have solid specs forward while I’m focused on something else.
In summary, you can see that there’s a lot that can be done with scheduled agents. They can also generate digests for you to start your day or your week, update documentation, and so on. Your imagination is the limit, and with Konduktor serving as the backbone, they have a structured environment to operate in that you can easily oversee and they can easily act on.

​
Part three: Getting more out of tasks

As I mentioned earlier, there’s still a lot more to tasks than what we’ve covered.

​
Task configuration

In the Workspace Config page (konduktor config in the CLI) you can do a few interesting things:
  1. Enable merge conflict auto-fixing
  2. Enable CI failure auto-fixing
  3. Edit the task agent system prompt
The first two options being enabled means that when a task’s PR has merge conflicts or a CI job failed, we’ll automatically start a new session from the previous history and instruct the agent to fix the conflicts and push a change or fix the tests (or whatever caused CI to fail) and push a fix. This let’s you deal with PRs only when they’re green and ready to go. Then, you can also edit the system prompt passed to the task agent. We’ve set up a solid default that will work for most but you can have this structured however you like.

​
Projects

We’ve left Projects almost for last but they are one of Konduktor’s most important features (and soon to become more powerful). The key idea behind Projects is that it’s hard to keep track and ship complex features using only tasks as a concept. Most orchestrators let you fire off a bunch of sessions but how do you oversee that everything is moving towards the right direction? In Konduktor, projects are the answer. If you find yourself with a complex feature to ship that naturally has multiple steps, or you wrote a task spec that is clearly too much for a single task, you should create a project. At the end of the day, projects are quite simple: they have phases, and phases can have any number of tasks. Phases are sequential, meaning you can’t run any tasks from Phase 2 until all tasks in Phase 1 are completed. However, all tasks within a phase can run in parallel. And that’s basically it. What’s cool about projects is that you can run multiple tasks in parallel, come back to validate at phase end that everything in the spec was covered, and move on to the next phase, while having a clear understanding of how the project is moving. Projects can be fully managed from the CLI, but this is where I think the UI shines in helping us process all the information we need to process to make decisions.

​
Questions

Questions are yet another concept that’s unique to Konduktor and that I think are a key part of how we should interact with agents. Most coding agents today will ask you questions before doing work, but as we move towards orchestrators, a lot of stuff is becoming fire-and-forget. Questions in Konduktor are a way for agents (be it task agents or scheduled agents) to ask you questions asynchronously forcing you to think more deeply about problems and specs and also for the agent to gather the context it needs to work without interrupting you. As of today, Konduktor was deliberately built without notifications, and while this may change in the future, the idea right now is that Konduktor works in the background, proactively and autonomously, while you focus on what you need to do, be it planning out the vision, interviewing users, running the company, or even coding something by hand. With that in mind, questions are a way for you and the agents to communicate without interrupting each other. Scheduled agents can trigger tasks to run autonomously and projects that have a great spec can move forward without you at all, but if there’s a spec with gaps or a direction that needs to be picked, the agent will flag this to you and you can, at your convenience, unblock the agent. I’ve actually been surprised by how eager agents are to use questions, and there are patterns I didn’t anticipate in how they want to use them which means this feature is probably pointing in the right direction but also that it will need a few iterations to be the most useful it can be.