# kdo
**Workspace manager for the agent era. Cuts Claude Code token consumption 5-10x on polyglot monorepos.**
kdo scans your workspace, builds a dependency graph, and serves structured context via MCP instead of letting agents traverse the filesystem blindly. Current tools (Turbo, Nx, Moon, Bun) burn 60-80% of agent tokens on navigation. kdo fixes this.
## Install
```bash
cargo install --git https://github.com/vivekpal1/kdo
```
Or with Docker:
```bash
docker pull ghcr.io/vivekpal1/kdo:latest
docker run -v $(pwd):/workspace ghcr.io/vivekpal1/kdo list
```
## Quick start
```bash
# Initialize a new workspace (or adopt an existing repo)
kdo init
# Create a new project interactively
kdo new my-service
# ? Language: [rust] / typescript / python / anchor
# ? Project type: [library] / binary
# ? Framework: [none] / react / next
# List all projects
kdo list
# Show dependency graph
# Get agent-optimized context for a project (within token budget)
kdo context vault-program --budget 2048
# Run a task across all projects (build, test, lint, dev, etc.)
kdo run build
kdo run test --filter vault-program
# Run an arbitrary command in each project
kdo exec "ls src"
# Find projects affected by recent changes
kdo affected --base main
# Check workspace health
kdo doctor
# Generate shell completions
kdo completions zsh >> ~/.zshrc
# Start MCP server for AI agents
kdo serve --transport stdio
```
## How it works
### `kdo init`
On an **empty directory**: scaffolds a workspace template with `kdo.toml`, `.kdo/`, `.kdoignore`, and `.gitignore` — ready for `kdo new`.
On an **existing repo**: discovers all projects, builds the dependency graph, and generates context files.
Creates two things:
1. **`kdo.toml`** at workspace root (committed) — workspace declaration + task definitions:
```toml
[workspace]
name = "my-monorepo"
[tasks]
build = "cargo build"
test = "cargo test"
lint = "cargo clippy"
```
2. **`.kdo/`** directory (gitignored) — cache for agents:
```
.kdo/
├── config.toml # workspace configuration
├── cache/ # content hash cache for incremental updates
├── context/ # per-project context files (agents read here)
│ ├── vault-program.md
│ ├── vault-sdk.md
│ └── ...
└── graph.json # cached dependency graph snapshot
```
### `kdo new <name>`
Interactive project scaffolding. Prompts for language, project type, and framework, then generates a complete project skeleton with manifest, source files, and tests. Supports:
- **Rust**: library or binary, clean Cargo.toml
- **TypeScript**: plain, React, or Next.js, with tsconfig
- **Python**: plain, FastAPI, or CLI (click), with pyproject.toml
- **Anchor**: Solana program skeleton with Anchor.toml
### `.kdoignore`
Works like `.gitignore` — controls which files kdo excludes from context generation and content hashing. Created automatically by `kdo init` with sensible defaults:
```
node_modules/
target/
dist/
build/
__pycache__/
.git/
.kdo/
*.lock
```
## Benchmark
Measured on a Solana monorepo (Anchor program + TS SDK + Python tool):
| **Reduction** | **~7x** | Only public API signatures, summaries, deps |
## Architecture
```mermaid
graph LR
A[kdo-cli] --> B[kdo-graph]
A --> C[kdo-context]
A --> D[kdo-mcp]
B --> E[kdo-resolver]
B --> F[kdo-core]
C --> B
C --> F
D --> B
D --> C
E --> F
```
| `kdo-core` | Types (`Project`, `Dependency`, `Language`), errors (`KdoError`), token estimator |
| `kdo-resolver` | Manifest parsers: `Cargo.toml`, `package.json`, `pyproject.toml`, `Anchor.toml` |
| `kdo-graph` | `WorkspaceGraph` via petgraph — discovery, DFS/BFS queries, blake3 hashing, cycle detection |
| `kdo-context` | Tree-sitter signature extraction, context generation, token budget enforcement |
| `kdo-mcp` | MCP server (JSON-RPC 2.0 over stdio) exposing 5 tools |
| `kdo-cli` | Clap subcommands, interactive scaffolding, tabled output |
## MCP setup
### Claude Code
Add to `~/.claude/mcp_servers.json` or `.claude/mcp_servers.json`:
```json
{
"mcpServers": {
"kdo": {
"command": "kdo",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"kdo": {
"command": "kdo",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
## MCP tools
| `kdo_list_projects` | List all projects with name, language, summary, dep count |
| `kdo_get_context` | Token-budgeted context bundle (summary + API signatures + deps) |
| `kdo_read_symbol` | Read a specific function/struct/trait body via tree-sitter |
| `kdo_dep_graph` | Dependency closure or dependents for a project |
| `kdo_affected` | Projects changed since a git ref |
| `kdo_search_code` | Search for a pattern across all workspace source files |
## Supported languages
- **Rust** — `Cargo.toml`, tree-sitter signature extraction
- **TypeScript / JavaScript** — `package.json`, `tsconfig.json` detection
- **Python** — `pyproject.toml` (PEP 621 + Poetry)
- **Solana Anchor** — `Anchor.toml`, CPI dependency tracking
## CLI reference
```
kdo init # Initialize workspace
kdo new <name> # Create project interactively
kdo run <task> [--filter project] # Run task across projects
kdo exec <cmd> [--filter project] # Run command in each project
kdo list [--format table|json] # List projects
kdo graph [--format text|json|dot] # Show dependency graph
kdo context <project> [--budget N] # Generate context bundle
kdo affected [--base ref] # Changed projects since ref
kdo doctor # Validate workspace health
kdo completions <shell> # Generate shell completions
kdo serve [--transport stdio] # Start MCP server
```
All commands support `--format json` for scripting.
## Composability
kdo operates at the **workspace layer** — discovering projects, building the dependency graph, and serving structured context. For symbol-level intelligence within a project, see [scope-cli](https://github.com/nicholasgasior/scope-cli) — they compose cleanly.
## Roadmap
See [TODO.md](TODO.md) for the full roadmap. Key upcoming items:
- Content-addressable task output caching
- Watch mode with filesystem events
- SSE transport for MCP
- Go, Java/Kotlin language support
- Remote cache (S3/GCS)
- `kdo run` parallel execution with dependency ordering
## License
MIT