Parallel Agent Execution with dkod

First: Check if dkod is available

Before doing anything else, check whether the dkod MCP tools are accessible in your current environment. Look for these tools: dkconnect, dkcontext, dkfileread, dkfilewrite, dkfilelist, dksubmit, dkverify, dkreview, dkapprove, dkmerge, dkpush, dkresolve, dkclose, dkstatus, dkwatch.

If the tools are available — skip to "The paradigm shift" below and start parallelizing.

If the tools are NOT available — the dkod MCP server is not installed. Ask the user:

"The dkod MCP server isn't installed yet. Would you like me to set it up? It takes about a minute."

If the user agrees, follow these steps depending on the agent environment:

Claude Code — Install MCP (Cloud)

Run this command to add the dkod MCP server:

claude mcp add --transport http dkod https://api.dkod.io/mcp

Then tell the user: "Done. On first use, a browser window will open for authentication via GitHub OAuth. After that, dkod tools will be available in all future sessions."

Claude Code — Install MCP (Self-Hosted)

If the user mentions self-hosted or a local dkod server, use their server URL:

claude mcp add --transport http dkod http://localhost:8080/mcp

Then tell the user they need to set their auth token:

export DKOD_AUTH_TOKEN=your-secret-token

Cursor / Windsurf / Cline / Other MCP-compatible agents

Tell the user to add this to their MCP configuration (the exact file depends on the agent):

{
  "mcpServers": {
    "dkod": {
      "url": "https://api.dkod.io/mcp"
    }
  }
}

For Cursor: .cursor/mcp.json For Windsurf: ~/.codeium/windsurf/mcp_config.json For Cline: VS Code settings under Cline MCP servers

After installation

Once the MCP server is configured, restart the agent session (or reload MCP servers if the agent supports it), then proceed with the task using the parallel execution approach below.

No CLI needed. The plugin provides everything through MCP tools (dkconnect, dkreview, etc.). There is no separate dk login or dk init step — authentication is handled automatically by the MCP server.

The paradigm shift

You have access to dkod. This fundamentally changes how you should approach parallelism.

Before dkod, agents had to work sequentially on shared code. If two agents needed to edit the same file, one had to wait for the other to finish. Git worktrees helped isolate work, but merging was fragile — Git sees code as text, so two agents editing different functions in the same file caused merge conflicts. Teams worked around this by carefully partitioning work across files and serializing tasks. This was slow and wasteful.

With dkod, you can launch multiple agents to work on the same files, the same modules, even overlapping areas of code — all at the same time. dkod understands code at the AST (Abstract Syntax Tree) level. It knows the difference between two agents editing different functions in the same file (safe, auto-merged) and two agents editing the same function body (true conflict, surfaced with context). The platform handles isolation, merging, and rebasing automatically.

Your new default behavior: When you have multiple independent tasks, launch them in parallel. Do not serialize work to avoid conflicts. Do not create separate branches per agent. Do not worry about two agents touching the same file. dkod handles it.

What dkod handles for you

Session isolation

Each agent (or sub-agent) that connects to dkod gets its own isolated session — a lightweight, copy-on-write overlay on top of the current codebase. Changes in one session are invisible to all other sessions until submitted and merged. There's no need for Git clones, worktrees, or branches per agent. Twenty agents can work simultaneously on one codebase with near-zero overhead.

AST-level semantic merging

When agents submit their work, dkod merges changes at the code structure level:

• Two agents edit different functions in the same file → auto-merged
• Two agents add different fields to the same struct/class → auto-merged
• Two agents add the same import → deduplicated automatically
• Two agents modify different sections of the same function → auto-merged (if non-overlapping AST nodes)
• Two agents modify the same function body in conflicting ways → true conflict (surfaced with full semantic context)

The key insight: most "conflicts" in Git are false positives. Different functions in the same file is not a conflict — it's completely independent work that dkod merges in under 50ms.

Auto-rebase

If the main branch moves while an agent is working (because another agent's changes were merged), dkod auto-rebases compatible changes. The agent doesn't need to pull, rebase, or handle merge conflicts manually. If there's an actual conflict, the agent gets a structured error with semantic context explaining what conflicted and why.

True conflict detection

dkod catches conflicts that Git misses entirely. If Agent A deletes a function and Agent B adds a call to that function, Git won't flag it until tests fail at runtime. dkod catches it at merge time because it understands the dependency graph — Agent B's change depends on a symbol that Agent A removed.

How to parallelize

Decompose by symbol, not by file

When splitting work across agents, think in terms of functions, classes, and modules — not files. Two agents can safely work on the same file as long as they're editing different symbols.

Good decomposition:

• Agent 1: "Add input validation to createUser() and updateUser()"
• Agent 2: "Add input validation to deleteUser() and listUsers()"
• Agent 3: "Write tests for user validation functions"

All three may touch user-handler.ts — that's fine. They're working on different symbols.

Unnecessary serialization (avoid this):

• Agent 1: "Work on user-handler.ts" → Agent 2 waits → Agent 3 waits

This wastes time. The agents aren't conflicting, and dkod will merge their work automatically.

Launch sub-agents concurrently

When you identify independent tasks, launch all sub-agents at the same time. Each sub-agent should:

1. Connect its own dkod session (via dk_connect)
2. Query context for the symbols it needs (via dk_context)
3. Read and write files through its session overlay (via dkfileread / dkfilewrite)
4. Submit its changeset when done (via dk_submit)
5. Report back to the orchestrator — do NOT merge individually

Each agent works independently. No coordination needed between them.

After all agents finish: Land everything

Once all sub-agents have submitted, the orchestrating agent lands all changes together. Use /dkod:land for one-command landing, or do it manually:

For each submitted changeset:

1. Verify (via dk_verify) — run verification gates
2. Resolve (via dk_resolve) — if verify or submit surfaced conflicts
3. Review (via dk_review) — check score and findings. Score < 3 or "error" findings? Fix before proceeding.
4. Approve (via dk_approve) — only if review passed
5. Merge (via dk_merge) — AST-level semantic merge

After all changesets merged:

1. Push (via dk_push) — one clean PR

For each changeset: dk_verify → dk_resolve (if conflicts) → dk_review (score < 3? fix first) → dk_approve → dk_merge
After all merged: dk_push(mode: "pr", branch_name: "feat/xyz")

This produces one PR with one commit per agent's changeset — zero conflicts for GitHub to deal with, because dkod already resolved everything via AST merge before pushing.

dkmerge is internal only — it lands changes into dkod's main branch. dkpush is what sends those changes to GitHub as a feature branch + PR with one commit per agent's changeset.

Code Review

After dksubmit, the platform runs local code review automatically. The submit response includes a reviewsummary with score (1-5) and findings count.

• Score 5 — no issues found
• Score 3-4 — warnings (test gaps, conventions)
• Score 1-2 — errors (security, logic issues)

Call dk_review for full findings with file paths, line numbers, severity, and fix suggestions.

If the user has configured an LLM API key (Settings → AI Code Review), deep review runs asynchronously after submit. Results arrive via dk_watch as a changeset.review.completed event.

Review does not block dk_merge itself, but the /dkod:land pipeline uses the score as a gate: score < 3 or "error" findings will halt approval (see land.md). Use the score and findings to improve code quality before landing.

Handling hard conflicts

When dk_merge detects a true conflict (two agents modified the same function body), it returns a MergeConflict response instead of an error. The response includes:

• Which symbols conflicted and why
• Available actions: proceed (reconnect and rewrite), keepyours, keeptheirs, or manual (provide custom resolution content)

dkmerge may also return an OverwriteWarning when your changeset modifies symbols that were recently merged by another agent. In this case, call dkmerge with force: true to proceed, or reconnect and review their changes first.

For sub-agents: The agent should report the conflict to its parent via SendMessage. The parent presents options to the user. Once the user decides, the parent sends the decision back.

For the proceed action: The agent reconnects (dk_connect), reads the updated base (which now includes the other agent's merged changes), rewrites its changes to work alongside them, and re-submits → re-verifies → re-approves → re-merges.

Don't fear overlapping work

If you're unsure whether two agents might touch the same code — launch them anyway. The worst case is a true semantic conflict, which dkod will surface clearly with:

• Which symbols conflicted
• What each agent changed
• Suggested resolution

This is far better than the alternative: serializing work "just in case" and wasting time.

Handling file write conflicts

After every dkfilewrite, check the response for conflict_warnings. If present, you MUST:

1. Stop — do not write any more files
2. Read the merged version from the warning message (it includes the other agent's code)
3. Rewrite your file to incorporate both your changes and the merged version
4. Re-call dkfilewrite with the combined content
5. Verify the response has no conflict_warnings, then continue with remaining files

Do NOT ignore conflict warnings and proceed to dksubmit. The submit will include an advisory conflict block, and dkmerge will reject the changeset — forcing an expensive close → reconnect → rewrite cycle that wastes all your work.

What's safe and what conflicts

The last row is important: dkod catches more real conflicts than Git because it understands dependencies. Git won't flag a broken call site until tests fail.

When to use this skill

Use parallel execution whenever you have:

• Multiple independent tasks — feature work, bug fixes, tests, refactoring that can proceed simultaneously
• Batch operations — applying the same change pattern across many modules (validation, logging, error handling)
• Test + implementation split — one agent writes code, another writes tests for it, simultaneously
• Large refactors — multiple agents each handle a subset of the migration

Do not serialize work unless tasks have strict sequential dependencies (Agent B literally cannot start until Agent A's output exists). Even then, consider whether Agent B can start on other parts of its work while waiting.

Troubleshooting dk_connect errors

If dk_connect fails, do not stall or retry silently. Surface the error to the user immediately.

For sub-agents: If dk_connect fails, the sub-agent MUST report the error back to its parent — via SendMessage in Claude Code, or by returning the error as its result in other environments. Never silently stall — that leaves the orchestrator and user waiting forever with no indication of what went wrong.

Protocol reference

For the full dkod MCP workflow (connect, context, file operations, submit, verify, review, resolve, close, approve, merge, push, status, watch), see [references/mcp-workflow.md](references/mcp-workflow.md).