# Dkod

> Enables fearless parallel agent execution on the same codebase, files, and functions simultaneously using dkod's AST-level semantic merging and session isolation. Use this skill whenever you are orchestrating sub-agents, agent teams, or parallel tasks that touch shared code. dkod eliminates merge conflicts between agents working on the same files by understanding code structure, not text. Also use when you find yourself serializing independent tasks, blocking agents waiting for each other, or avoiding parallel work because of conflict fears. If dkod MCP tools (dk_connect, dk_context, dk_file_read, dk_file_write, dk_file_list, dk_submit, dk_verify, dk_review, dk_approve, dk_merge, dk_push, dk_resolve, dk_close, dk_status, dk_watch) are available, this skill applies.

- Skill: `dkod-io/dkod` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dkod-io/dkod`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkod-io/dkod/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dkod-io (https://skillmd.com/u/dkod-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkod-io/dkod

---


# 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: `dk_connect`, `dk_context`, `dk_file_read`, `dk_file_write`,
`dk_file_list`, `dk_submit`, `dk_verify`, `dk_review`, `dk_approve`, `dk_merge`, `dk_push`,
`dk_resolve`, `dk_close`, `dk_status`, `dk_watch`.

**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:

```bash
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:

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

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

```bash
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):

```json
{
  "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 (`dk_connect`, `dk_review`,
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 `dk_file_read` / `dk_file_write`)
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:

6. **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.

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

### Code Review

After `dk_submit`, the platform runs **local code review** automatically. The submit response includes a `review_summary` 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), `keep_yours`, `keep_theirs`, or `manual` (provide custom resolution content)

`dk_merge` may also return an **OverwriteWarning** when your changeset modifies symbols that were recently merged by another agent. In this case, call `dk_merge` 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 `dk_file_write`, 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 `dk_file_write`** 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 `dk_submit`. The submit will include an
advisory conflict block, and `dk_merge` will reject the changeset — forcing an expensive
close → reconnect → rewrite cycle that wastes all your work.

## What's safe and what conflicts

| Scenario | Result |
|----------|--------|
| Two agents modify different functions in the same file | **Auto-merge** |
| Two agents add different fields to the same struct/class | **Auto-merge** |
| Two agents add the same import statement | **Deduplicated** |
| Two agents modify different sections of the same function | **Auto-merge** |
| Two agents add the same parameter to a function | **Deduplicated** |
| Two agents modify the same function body in conflicting ways | **Conflict** (surfaced with context) |
| Agent A deletes a function that Agent B calls | **Conflict** (caught at merge time) |

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.

| Error | Cause | Action |
|-------|-------|--------|
| `PermissionDenied: repository '...' is not connected` | Repo not added to dkod | Tell the user: **"This repository isn't connected to your dkod account. Open https://app.dkod.io, go to Repositories → Add Repository, add it, then retry."** |
| `PermissionDenied` (any other) | Auth or access issue | Tell the user the exact error and ask them to check their dkod dashboard |
| `Unauthenticated` | Session expired or no token | Ask the user to re-authenticate (run `/plugin` in Claude Code, or check MCP config) |
| Connection refused / timeout | Server unreachable | Check if using local (`[::1]:50051`) vs cloud (`api.dkod.io`). If local, ask user to start the server. |

**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).