João Salavisa
97c1f689e4
* feat(workflow): explicit step-completion signal for auto-advance Adds `step_complete_kandev` MCP tool + `WorkflowStep.auto_advance_requires_signal` column so workflow steps can gate their `on_turn_complete` transitions on an agent-emitted completion signal instead of inferring "done" from any turn-end. See docs/decisions/0015-explicit-completion-signal-for-auto-advance.md for the motivation, alternatives considered, and trade-offs. * fix(workflow): address PR review feedback for explicit completion signal - Dedup `LoadPendingStepSignal` into `internal/task/models` so the MCP handler (write site) and the orchestrator (read site) share one decoder. - Gate the out-of-band subscriber on `WorkflowStep.AutoAdvanceRequiresSignal` so `step_complete_kandev` is not an unintended manual-advance path for signalless steps. - Fail closed on step-load errors in `processOnTurnCompleteViaEngine`: a loader hiccup must block the transition rather than silently bypass the gate. - Reject `step_complete_kandev` for terminal sessions (Completed / Failed / Cancelled) so the agent gets a clear error instead of `accepted: true` followed by a no-op. - Surface bus-publish failures back to the agent instead of swallowing them — the idempotency guard makes the retry safe and prevents the session from getting stuck. - New `TestOnStepCompletionSignaled` covers the subscriber paths (RUNNING / WAITING+match / stale step / not signal-gated). - ADR doc fixes: payload field list now matches the wire shape, writer ownership is documented, the unsubstantiated 250ms-debounce claim is removed, and the late-signal re-close race is recorded as a deferred open question. - Drop the new toggle's HelpTip in favour of an inline description — the shadcn tooltip portal was intercepting clicks on the agent-profile dropdown options in the workflow settings E2E. * fix(workflow): round-2 review fixes for explicit completion signal - Split `handleStepComplete` into `resolveStepCompleteTarget` + `publishStepCompletionEvent` helpers so the entrypoint clears funlen (88 → under 80 lines) and the two halves are independently testable. - Classify session/task load errors instead of returning `NotFound` for every failure: use the exported `taskrepo.ErrTaskNotFound` sentinel for task lookups, substring-match for the session repo (no sentinel today), and surface anything else as `InternalError` with the raw error logged but not leaked to the agent — so a transient DB hiccup triggers a retry rather than session abandonment. - Pin `step_complete_kandev` explicitly in the mode-specific tool-count tests: `Contains` in `ModeTask`, `NotContains` in `ModeConfig` and `ModeOffice`, so accidental dereg or cross-mode registration is caught by the diff instead of by a still-equal count. * fix(workflow): round-3 review fixes + defer pipeline-editor toggle - Defer the "Wait for agent completion signal" sub-toggle to a follow-up PR. Adding it to the step config card shifts the layout enough that the agent profile select's Radix popper opens into a sibling tooltip's hover path, breaking workflow-agent-profile.spec.ts on shard 7. The backend column ships in this PR — workflows can opt in via the YAML import or the MCP `update_workflow_step_kandev` tool — and the UI affordance gets its own iteration where the test interference can be investigated without blocking the rest of the change. - Re-publish the bus event on the `already_signaled` short-circuit when the session is WAITING_FOR_INPUT. Without this, an agent's retry after the first call's publish failed would short-circuit on the persisted bag, never fire the subscriber, and leave the session stuck. - handleStepComplete docstring: drop the non-existent feature-flag claim and the "audit entry" wording — gating is purely `WorkflowStep.AutoAdvanceRequiresSignal` and the bag is cleared on the next turn start with no separate audit trail. - `step_complete_kandev` tool description: same fix — clarify that the call succeeds for non-gated steps but the signal is discarded on the next turn start (no audit history to query later). * test(workflow): cover handleStepComplete + reword defer-comment - Add `TestHandleStepComplete_*` (6 subtests, all passing) covering the uncovered handler paths flagged by Claude/cubic on round 3: missing-fields validation, session-does-not-belong-to-task ownership guard, terminal-session rejection (Completed/Failed/Cancelled), first-call happy path (bag persisted + bus payload shape pinned), dedup while RUNNING (no re-publish), and dedup while WAITING_FOR_INPUT (the retry-after-publish-failure path — must re-publish so the subscriber fires). - Reword the deferred-toggle comment to drop the YAML-export claim: the workflow export model doesn't yet serialize `auto_advance_requires_signal`, so MCP `update_workflow_step_kandev` is the only configuration path that round-trips today. Note the follow-up needs to extend the export schema alongside the UI toggle. * test(workflow): pin signaled_at + drop redundant GetTaskSession on bag-clear - Assert `signaled_at` is present and parses as RFC3339Nano in `TestHandleStepComplete_FirstCallAccepted`. The field is part of the handler's documented response contract; pinning it catches accidental drop/rename regressions. - Add `clearPendingStepSignalByID(ctx, sessionID)` as a thin DB-only variant of `clearPendingStepSignal` and use it from `executeStepTransition`, where the session struct isn't read after the clear. Avoids an extra `GetTaskSession` round-trip per transition. `clearPendingStepSignal(session)` still exists for the in-memory-mutation case (subscriber's stale-step path). * fix(workflow): subscriber stale-clear guard + ADR/comment drift fixes - onStepCompletionSignaled's stale-step path now reads the bag and only clears it when its current StepID matches the (stale) event's stepID. Previously the unconditional clear could destroy a valid signal that the new step's agent had just written when sessions are reused across steps without auto_start_agent. (Greptile P1.) - Drop the "feature flag" phrase from WorkflowStep.AutoAdvanceRequiresSignal docstring — leftover from an earlier draft. The gating is purely the boolean field; the global flag was removed two rounds ago. - Merge the two adjacent `if triggerOnEnter` blocks in executeStepTransition so the full triggerOnEnter=true path reads top- to-bottom in one place. (CodeRabbit + cubic.) - ADR 0015 Mechanism section: re-label the SessionStepHistory.Metadata audit annotation, the `step_complete_signaled` system message, and the expvar telemetry counters as deferred. They're planned shapes, not current behaviour — calling them "Audit" / "Chat visibility" / "Telemetry" in present tense was misleading for future readers. * fix(workflow): drop subscriber complexity + reload session on stale-clear - Extract `parseStepCompletionEvent` and `stepIsSignalGated` helpers from `onStepCompletionSignaled`. Cyclomatic complexity goes 17 → under 15 (cyclop on new code, CI lint regression after the round-6 stale-clear guard). - The stale-step branch now re-loads the session from the DB before deciding whether to clear the bag. The previous round-6 fix checked the local `session.Metadata` snapshot, which can be older than a concurrent write from the new step's agent — that check could see a stale signal that had since been overwritten with a valid one and erase the new bag entry. The narrower load-on-clear is cheap and closes the cubic P1 hole. (The broader race in `processOnTurnCompleteViaEngine` reading session.Metadata is the monotonic-marker open question in ADR 0015; out of scope here.) * test(workflow): pin stale-event guard's preserve-current-bag side + dedup StringFromAny - Add `TestOnStepCompletionSignaled` subtest "stale event → valid bag for CURRENT step is preserved" — fires a stale step-A event while the bag holds a valid step-B signal, asserts the bag still contains StepID=step_b after the subscriber runs. Pins the negative side of the round-6 `existing.StepID == stepID` guard, so a regression that drops or inverts the guard (and would silently leave signal-gated steps stuck) fails the test instead of slipping through. - Promote `pendingSignalString` to exported `models.StringFromAny` and reuse it from the orchestrator subscriber's `parseStepCompletionEvent`. Eliminates the byte-for-byte duplicate helper across the two packages; the bag-shape decoder and the bus- event decoder now share one source of truth for "missing string". --------- Co-authored-by: Kandev Agent <agent@kandev.dev>
Kandev
Manage and run tasks in parallel. Orchestrate agents. Review changes. Ship value.
Workflows | Run as a Service | Roadmap | Contributing | Architecture | Discord
What
Organize work across kanban and pipeline views with opinionated workflows and execute multiple tasks in parallel. Assign agents from any provider, and review their output in an integrated workspace - file editor, file tree, terminal, browser preview, and git changes in one place. Terminal agent TUIs are great for running agents, but reviewing and iterating on changes there doesn't scale.
Run it locally or self-host it on your own infrastructure and access it from anywhere via Tailscale or any VPN.
Open source, multi-provider, no telemetry, not tied to any cloud.
Vision
Humans stay in control. Define tasks, build agentic workflows with gates, review every change, decide what ships.
- Review-first - Humans support production systems. We need to understand (yet) and trust the code that gets deployed.
- Your workflow - Every team is different, and not every developer uses AI the same way. Define workflows once, share them across the team, and give everyone a consistent process for working with agents - regardless of experience level.
- Remote agents - Running multiple agents on a large codebase can quickly saturate a local machine. The goal is a single control plane: offload execution to servers, orchestrate from anywhere, including your phone.
Features
- Multi-agent support - Claude Code, Codex, GitHub Copilot, Gemini CLI, Amp, Auggie, OpenCode, Cursor, Qwen, Factory Droid, iFlow, Kilocode, Pi, Kimi, AWS Kiro, Qoder, Trae
- Parallel task execution – start and manage multiple tasks from different sources simultaneously, boosting productivity with AI agents
- Integrated workspace - Built-in terminal, code editor with LSP, git changes panel, embedded vscode and chat in one IDE-like view
- Kanban task management - Drag-and-drop boards, columns, and workflow automation
- Agentic workflows - Multi-step pipelines that mix-and-match agents per step - for example, Claude Code Opus to design a plan, GitHub Copilot Sonnet to implement it, and Codex GPT 5.4 to review the changes. See docs/workflows.md
- Sub-tasks - Agents can spawn sub-tasks that resume from the parent task's session. Useful for splitting a task that has grown too big, or producing several PRs from the same starting point.
- CLI passthrough - Drop into raw agent CLI mode for direct terminal interaction with any supported agent, leverage the full power of their TUIs
- Workspace isolation - Git worktrees prevent concurrent agents from conflicting
- Multi-repository tasks - Span a single task across multiple repositories, with one worktree per repo, per-repo branches, per-repo PRs, and per-repo grouping in the Changes panel and review dialog
- Flexible runtimes - Run agents as local processes, in isolated Docker containers or in remote executors like sprites.dev
- Session management - Resume and review agent conversations
- Stats - Track your productivity with stats on the completed tasks, agent turns, etc
Integrations
Connect Kandev to the tools your team already uses — pull issues into the kanban, link tasks to PRs, and surface review activity inline.
Supported ACP Agents
| Agent | Launch |
|---|---|
| Claude Code | npx -y @agentclientprotocol/claude-agent-acp |
| Codex | npx -y @zed-industries/codex-acp |
| GitHub Copilot | npx -y @github/copilot --acp |
| Gemini CLI | npx -y @google/gemini-cli --acp |
| Amp | npx -y amp-acp |
| Auggie | npx -y @augmentcode/auggie --acp |
| OpenCode | opencode acp |
| Cursor | cursor-agent acp (requires Cursor Pro) |
| Qwen | npx -y @qwen-code/qwen-code --acp |
| Factory Droid | npx -y droid exec --output-format acp |
| iFlow (beta) | npx -y @iflow-ai/iflow-cli --experimental-acp |
| Kilocode | npx -y @kilocode/cli acp |
| Pi | npx -y pi-acp |
| Kimi | kimi acp (install Kimi CLI from Moonshot AI) |
| Kiro | kiro-cli-chat acp (install Kiro CLI from AWS) |
| Qoder | qodercli --acp (install Qoder CLI) |
| Trae | traecli acp serve (install Trae IDE CLI) |
All agents communicate via ACP (Agent Client Protocol). Some agents support ACP natively, while others use ACP adapter packages that bridge their native protocols. CLI Passthrough mode is also available for direct terminal interaction with any agent CLI. If your agent isn't supported yet, open an issue or submit a PR with the integration. See Adding a New Agent CLI for a step-by-step guide.
Bring your own TUI agents
There is support for running any agent as TUI inside a terminal. Just add the cli command in the agent profile settings and the task will start the agent inside a PTY terminal instead of using ACP.
Supported Executors
| Executor | Description |
|---|---|
| Local Process | Runs the agent as a local process on the host machine |
| Docker | Runs the agent in an isolated Docker container |
| Sprites | Runs the agent in a remote cloud environment via sprites.dev |
Each executor uses git worktrees for workspace isolation, preventing concurrent agents from conflicting.
Quick Start
Homebrew (macOS, Linux)
brew install kdlbs/kandev/kandev
kandev
NPX
npx kandev@latest
Requires npm 7+. Installs the CLI plus a platform-matched runtime bundle in one step.
NPM (global)
npm install -g kandev@latest
kandev
Updates
brew upgrade kandevnpx kandev@latest(always uses the latest published version)npm install -g kandev@latest
The worktrees and sqlite db live in ~/.kandev by default. Works on macOS, Linux, and Windows (WSL or native).
From Source
# Clone the repository
git clone git@github.com:kdlbs/kandev.git
cd kandev
# Start in production mode
make start
Prerequisites: Go 1.26+, Node.js 18+, pnpm, Docker (optional - needed for container runtimes)
High level architecture
graph LR
UI[Web UI] --> Backend
Backend["Backend (Orchestrator)"]
Backend --> W1 & W2
subgraph W1[Local Process]
Agent1[Agent CLI] --- WT1[Worktree]
end
subgraph W2[Docker Container]
Agent2[Agent CLI] --- WT2[Worktree]
end
We also want to add support for these remote runtimes:
- Remote SSH - run agents on remote servers over SSH, using docker or local processes with workspace isolation
- K8s operator - run agents in a Kubernetes cluster, with auto-scaling and resource management.
Development
Project Structure
apps/
├── backend/ # Go backend (orchestrator, lifecycle, agentctl, WS gateway)
├── web/ # Next.js frontend (SSR, Zustand, real-time subscriptions)
├── cli/ # CLI tool (npx kandev launcher)
└── packages/ # Shared UI components & types
Prerequisites
- Go 1.21+
- Node.js 18+
- pnpm
- Docker (optional)
Running Dev Servers
# Start everything (backend + frontend with auto ports)
make dev
# Or run separately
make dev-backend # Backend on :38429
make dev-web # Frontend on :37429
Testing & Linting
make test # Run all tests (backend + web)
make lint # Run all linters
make typecheck # TypeScript type checking
make fmt # Format all code
Pre-commit Hooks
# Install pre-commit (https://pre-commit.com/#install)
pipx install pre-commit
# Install git hooks
pre-commit install
Comparison to Other Tools
There are a few similar tools in this space, and new ones appearing everyday. Here's what sets this one apart:
- Server-first architecture - Not a desktop app. Runs as a server you can access from any device, including your phone. Start a task away from your computer and check in on it later.
- Remote runtimes - Run agents on remote servers and Docker hosts, not just your local machine.
- Multi-provider - Use Claude Code, Codex, Copilot, Gemini, Amp, Auggie, OpenCode, Cursor, Qwen, Droid, iFlow, Kilocode, Pi, Kimi, Kiro, Qoder, and Trae side by side. Not locked to one vendor.
- CLI passthrough and chat - Interact with agents through structured chat messages or drop into raw CLI mode for full agent TUI capabilities.
- Open source and self-hostable - No vendor lock-in, no telemetry, runs on your infrastructure.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.
See the issue tracker for open tasks, or join our Discord to chat with maintainers and other contributors.
Acknowledgments
Built with these excellent open-source projects:
Monaco Editor · Tiptap · xterm.js · dockview · CodeMirror · dnd-kit · Mermaid · Recharts · TanStack Table · Zustand · Shadcn/UI · Radix UI · Tailwind CSS