Skip to content
Back to News
technical
v8.0
compound-operations

How Compound Operations Work Under the Hood

By CKB Team

Compound operations are the headline feature of CKB 8.0. They reduce AI tool calls by 60-70% by combining multiple queries into single, optimized operations. But how do they actually work?

The Problem: Sequential Tool Calls

Before compound operations, understanding a symbol required your AI assistant to make multiple sequential calls:

1. searchSymbols("HandleRequest")     → Find the symbol
2. getSymbol(symbolId)                → Get metadata
3. explainSymbol(symbolId)            → Get AI explanation
4. findReferences(symbolId)           → Get all usages
5. getCallGraph(symbolId)             → Get callers/callees

Each call adds latency. Each response consumes tokens. For complex queries, this pattern repeated dozens of times per session.

The Solution: Smart Aggregation

Compound operations flip this model. Instead of the AI orchestrating multiple calls, CKB does it internally with full access to its index.

The understand Operation

When you call understand, here's what happens:

// Single request
{ "query": "HandleRequest", "includeReferences": true }

// Internal execution (parallel, not sequential)
├── searchSymbols → resolve query to symbol ID
├── getSymbol → fetch full metadata
├── explainSymbol → generate contextual explanation
├── findReferences → gather all usages (grouped by file)
└── getCallGraph → map callers and callees

The key insight: these operations run in parallel against the in-memory index. There's no network overhead between steps. The index is already loaded.

Disambiguation Handling

What if your query matches multiple symbols? understand handles this gracefully:

{
  "disambiguation": {
    "matched": 3,
    "symbols": [
      { "id": "ckb:repo:sym:abc", "name": "HandleRequest", "file": "api/handler.go" },
      { "id": "ckb:repo:sym:def", "name": "HandleRequest", "file": "internal/rpc/handler.go" },
      { "id": "ckb:repo:sym:ghi", "name": "HandleRequestAsync", "file": "api/async.go" }
    ]
  },
  "suggestion": "Specify file path or use symbol ID directly"
}

Your AI can then refine the query or ask you to clarify—without wasting calls on the wrong symbol.

The Three Compound Operations

explore - Area Exploration

Use case: "What's in this directory?" or "Help me understand this module."

Aggregates:

  • explainFile → File-level overview
  • searchSymbols → Key symbols in scope
  • getCallGraph → Dependency relationships
  • getHotspots → Recent change activity

Parameters:

{
  "target": "internal/api",
  "depth": "standard",      // shallow | standard | deep
  "focus": "structure"      // structure | dependencies | changes
}

The depth parameter controls thoroughness. "Shallow" returns a quick overview. "Deep" analyzes every file and traces all dependencies.

understand - Symbol Deep-Dive

Use case: "What does HandleRequest do?" or "How is this function used?"

Aggregates:

  • searchSymbols → Symbol resolution
  • getSymbol → Full metadata
  • explainSymbol → AI explanation
  • findReferences → Usage locations
  • getCallGraph → Caller/callee graph

Parameters:

{
  "query": "HandleRequest",
  "includeReferences": true,
  "includeCallGraph": true,
  "maxReferences": 50
}

prepareChange - Impact Analysis

Use case: "What breaks if I change UserService?"

Aggregates:

  • analyzeImpact → Blast radius calculation
  • getAffectedTests → Test coverage for change
  • analyzeCoupling → Coupled files and symbols
  • Risk scoring algorithm

Parameters:

{
  "target": "ckb:repo:sym:abc123",
  "changeType": "modify"    // modify | rename | delete | extract
}

The changeType matters. Renaming a function has different impact than modifying its implementation.

Batch Operations

For bulk queries, CKB 8.0 includes two batch operations:

batchGet - 50 Symbols at Once

{
  "symbolIds": [
    "ckb:repo:sym:abc",
    "ckb:repo:sym:def",
    // ... up to 50
  ]
}

Returns all symbols in a single response. Failed lookups are reported separately without failing the entire batch.

batchSearch - 10 Searches at Once

{
  "queries": [
    { "query": "Handler", "kind": "function" },
    { "query": "Service", "kind": "class" },
    { "query": "Repository", "limit": 5 }
  ]
}

Each query runs independently. Results are grouped by query.

Performance Characteristics

Real-world measurements from a 500k LOC codebase:

Operation Without Compound With Compound Improvement
Understand symbol 5 calls, ~2.1s 1 call, ~0.4s 81% faster
Explore directory 4 calls, ~1.8s 1 call, ~0.5s 72% faster
Prepare change 4 calls, ~2.4s 1 call, ~0.6s 75% faster

Token savings are even more dramatic—each avoided round-trip saves the full tool schema overhead.

Using Compound Operations

All compound operations are available in every MCP preset, including the minimal core preset. Your AI assistant can use them immediately:

User: "What does the AuthMiddleware function do?"

AI: [calls understand with query "AuthMiddleware"]

"AuthMiddleware validates JWT tokens on incoming requests.
It's called by 12 route handlers and has 3 callees:
- validateToken() for JWT verification
- getUserFromToken() for user lookup
- logAuthAttempt() for audit logging

47 references across 8 files. Confidence: high."

What's Next

We're exploring additional compound operations for CKB 8.1:

  • reviewChange - Pre-commit analysis combining diff, ownership, and test coverage
  • explainArchitecture - Full system overview with module boundaries and data flow
  • findSimilar - Locate similar code patterns across the codebase

Links: