tkmd Brings Deterministic Governance to AI Multi-Agent Teams

Overview

A new open-source tool named tkmd is emerging to address the growing complexity of coordinating multiple AI coding agents within software development workflows. Designed as a deterministic program engine, it introduces a governance layer that prevents common failure modes in multi-agent systems, such as premature task completion claims and circular dependency deadlocks.

The project positions itself as a privacy-first, local-only solution. Unlike many modern AI development tools that rely on cloud infrastructure or continuous telemetry, tkmd operates as a single Rust binary with zero network requests. It utilizes plain Markdown files for task storage and mathematical graph algorithms to schedule work, offering developers a transparent and auditable control plane for autonomous agent teams.

Core Functionality and Governance

At its foundation, tkmd manages tasks as standard Markdown cards with YAML frontmatter. This design choice ensures that task data remains human-readable and portable, stored in simple .md files rather than proprietary databases. The engine leverages two key mathematical concepts—Critical Path Method (CPM) and Design Structure Matrices (DSM)—to analyze dependencies and schedule execution.

By running algorithms like tk dep --cpm, the system calculates early start times, late finish times, and schedule buffers for each task. This deterministic scheduling allows an orchestrator to prioritize subagents working on the critical path, where any delay would directly impact the project timeline. Simultaneously, the DSM module detects circular deadlocks in dependency graphs before code generation begins, a common bottleneck in loosely coordinated agent teams.

The tool enforces a strict lifecycle for task completion. AI subagents cannot arbitrarily mark tasks as finished. Instead, they must pass automated shell verification gates using eval commands and submit their work for review by transitioning the status to pending-close. Only a human operator, or an agent explicitly instructed as a proxy, can perform the final sign-off via the done command. This guardrail ensures that autonomous coding agents do not falsely claim success.

Operational Modes and Privacy Architecture

Tkmd supports two primary operational modes to fit different user preferences. The Obsidian + CLI Mode is recommended for users who prefer visual project management. It syncs 1:1 with an Obsidian .base Kanban board, updating metadata and logging completed tasks directly into daily notes. This bridges the gap between AI automation and traditional note-taking workflows.

For developers who prefer a pure command-line experience, the Standalone CLI Mode operates independently of any external applications. Tasks are managed as plain-text cards in local directories, opening directly in terminal editors like nvim, vim, or micro. This mode emphasizes minimalism and speed, removing the overhead of graphical user interfaces.

Privacy and data ownership are central to the project’s architecture. The software makes zero HTTP requests and contains no telemetry beacons. All event logs are stored locally as standard JSONL files, giving users full control over their operational data. While the tool includes built-in metrics computation—such as Little’s Law and mean time to completion—users can also query these logs with external tools like DuckDB for deeper analysis without relying on internal cloud services.

Multi-Agent Orchestration Lifecycle

The workflow for multi-agent execution is structured into three distinct phases: autonomous planning, guarded subagent execution, and automatic blocker cascading. This structure is designed to handle the coordination challenges inherent in parallel AI coding sessions.

"Tkmd acts as a deterministic scheduling and harness for teams of AI subagents, solving the hardest problems in multi-agent execution: deadlocks, uncoordinated parallel writes, and premature completion claims."

In the planning phase, a lead architect agent or human user decomposes a high-level specification into individual tasks. Dependencies are declared explicitly, and the system validates the graph for circular logic. Once approved, subagents can claim independent tasks using the claim command, which attaches a unique session ID to the process. This allows multiple agents to work concurrently in separate terminal panes without write collisions, thanks to POSIX advisory file locking.

When a subagent completes its assigned work, it triggers the verification gate. Automated tests run to validate the code changes. If the tests pass, the task moves to a review state rather than closing immediately. This interim step is crucial for maintaining quality control in autonomous systems.

The final phase involves cascade unblocking. When a human reviewer approves a previously blocked task, tkmd automatically promotes downstream dependencies to the ready state. This eliminates the manual overhead of updating task statuses across a dependency chain, allowing subsequent subagents to begin work immediately upon resource availability. Session resumption is also supported, enabling users to reopen the exact terminal environment attached to any specific task using a simple command, preserving context and history for iterative debugging.