overview

Overview

Klock is the coordination infrastructure for multi-agent AI systems.

When multiple AI agents edit the same files simultaneously, the results are corrupted—silently. The build passes, but 24% of intended changes are lost. We call this the Multi-Agent Race Condition (MARC).

Klock sits between your agents and shared resources. It enforces intent-based locking with Wait-Die timestamp-ordered scheduling—the same technique used in distributed databases—to guarantee that no two agents corrupt each other's work.

Installation

Klock is available for Python, JavaScript/TypeScript, and Rust.

Python

pip install klock

JavaScript / TypeScript

npm install @klock-protocol/core

Rust

cargo add klock-core

Quick Example

Wrap any LangChain tool with @klock_protected:

from klock import KlockClient
from klock_langchain import klock_protected
from langchain_core.tools import BaseTool

klock_client = KlockClient()
klock_client.register_agent("refactor-agent-01", 100)

class EditFileTool(BaseTool):
    name = "edit_file"
    description = "Edit a source file"

    @klock_protected(
        klock_client=klock_client,
        agent_id="refactor-agent-01",
        session_id="session-001",
        resource_type="FILE",
        resource_path_extractor=lambda kwargs: kwargs["path"],
        predicate="MUTATES",
    )
    def _run(self, path: str, content: str) -> str:
        with open(path, 'w') as f:
            f.write(content)
        return f"Wrote {len(content)} chars to {path}"

# That's it. Concurrent agents now coordinate automatically.

The Klock Contract

  • Safety: No two simultaneously granted leases contain conflicting intents on the same resource.
  • Liveness: Timestamp-ordered scheduling ensures waiting edges flow in one direction — cycles cannot form. Deadlock is impossible.
  • Intent Serializability: Completed executions admit a serial order consistent with the conflict-induced partial order.

Next step: Follow the 5-minute Quickstart to run your first multi-agent coordination.

Architecture Overview

Klock runs as a lightweight coordination server. Your agents communicate with it via HTTP or the native SDK bindings (Rust FFI compiled to Python/JS for native performance).

┌──────────────────────────────────────────────┐
│                  Your System                  │
│                                               │
│  ┌──────────┐    ┌──────────┐    ┌─────────┐  │
│  │ Agent A  │    │ Agent B  │    │ Agent C │  │
│  └────┬─────┘    └────┬─────┘    └────┬────┘  │
│       │              │               │        │
│       └──────────┬───┘───────────────┘        │
│                  ▼                            │
│         ┌────────────────┐                    │
│         │  Klock Server  │  ← Coordination    │
│         │  (Wait-Die)    │     kernel         │
│         └────────┬───────┘                    │
│                  │                            │
│         ┌────────▼───────┐                    │
│         │  Shared Files  │  ← Never corrupted │
│         └────────────────┘                    │
└──────────────────────────────────────────────┘