kdo documentation

Getting started

Install kdo, initialize a workspace, run your first task, and register kdo with your AI agent.

A 5-minute path from zero to a running kdo workspace with MCP wired into Claude Code or OpenClaw.

1. Install

Pick one. All three leave you with a kdo binary on your PATH.

Prebuilt binary (fastest, no Rust toolchain):

curl -fsSL https://vivekpal1.github.io/kdo/install.sh | bash -s -- --from-release

From crates.io (requires an explicit version during alpha):

cargo install kdo --version "0.2.0-alpha.1"

From source (for contributors):

git clone https://github.com/vivekpal1/kdo
cd kdo
make install          # → ~/.local/bin/kdo

Verify:

kdo --version
# kdo 0.2.0-alpha.1

2. Initialize a workspace

Inside any directory:

kdo init

On an empty directory: scaffolds a kdo.toml, a .kdo/ cache dir, a .kdoignore, and updates .gitignore. Tells you to run kdo new <name> for your first project.

On an existing repo: discovers every project by scanning manifests, builds the dependency graph, generates context into .kdo/context/, and writes a kdo.toml with detected tasks.

What shows up:

File / dirPurposeCommit it?
kdo.tomlWorkspace config + tasksYes
.kdoignoreContext exclusion rulesYes
.kdo/Cache (context, graph snapshot)No (gitignored)
.kdo/context/*.mdPer-project AI contextNo

3. Explore the workspace

kdo list              # table of every project
kdo graph             # dependency edges
kdo graph --format dot | dot -Tsvg > graph.svg
kdo context vault-sdk --budget 2048

Each of these is instant. Everything is cached from kdo init.

4. Run a task

kdo resolves tasks in this order:

  1. [projects.<name>.tasks] in kdo.toml (per-project override)
  2. [tasks] in kdo.toml (workspace-level)
  3. Project manifest scripts (e.g. package.json scripts)
  4. Language defaults (e.g. cargo build for Rust)
kdo run build                   # topological order across all projects
kdo run test --filter vault-sdk # one project only
kdo run ci --parallel           # independent projects run concurrently
kdo run build --dry-run         # show the plan, don't execute
kdo run build -- --release      # pass args through to the underlying command

5. Wire kdo into your agent

Claude Code

One command:

kdo setup claude --global

This registers kdo as a user-scope MCP server (via claude mcp add), updates ~/.claude/CLAUDE.md with a usage block, and seeds shared agent memory. Re-running is safe. It converges to the same state.

Preview without touching disk:

kdo setup claude --global --dry-run

Verify:

claude mcp list
# kdo: kdo serve --transport stdio --agent claude - ✓ Connected

OpenClaw

Same pattern:

kdo setup openclaw --global

Writes an AgentSkills-spec SKILL.md under ~/.openclaw/skills/kdo/, merges the MCP server registration into ~/.openclaw/openclaw.json at /mcpServers/kdo, and seeds memory. Restart OpenClaw to pick it up.

Workspace-scoped (no --global)

Drop --global and kdo setup writes to the current workspace only. Local MCP scope for Claude, per-project skill + AGENTS.md for OpenClaw, plus .kdo/memory/MEMORY.md either way.

Any other MCP client

Point it at:

kdo serve --transport stdio --agent generic

The server exposes 7 tools and a resources/list endpoint for the context files. Full catalog in MCP server.

6. Keep it fresh

  • When you add a project: run kdo init again to regenerate context.
  • When you upgrade: kdo upgrade pulls the latest release binary with an atomic replace.
  • When something breaks: kdo doctor walks the workspace and reports the first missing piece.

If you just want to try it without touching real code, clone the sample monorepo and run every command against it:

git clone --depth 1 https://github.com/vivekpal1/kdo
cd kdo/fixtures/sample-monorepo
kdo init
kdo list
kdo graph
kdo context vault-program --budget 4096
kdo run build --dry-run

The fixture mixes Anchor, Rust, TypeScript, and Python so every discovery and extraction path gets exercised.

Next