Tkmd – A local CLI task manager and MCP server with AI agent review gates

Open-source developer Tre Harrison released tkmd, a deterministic program engine and governance harness designed to manage local tasks and coordinate autonomous AI coding agents. As detailed in github.com's report, the system stores tasks as Markdown cards with YAML frontmatter and schedules work using mathematical graph algorithms. Built as a single Rust binary with POSIX advisory file locking, the tool operates offline without background daemons, network requests, or telemetry tracking.

This report examines the engine architecture, its verification pipeline, multi-agent orchestration mechanisms, local storage modes, and command line tooling. The software targets engineers pairing with autonomous agents like Claude Code, Codex, Gemini, or OpenCode across local workspaces. Readers will learn how the harness eliminates premature completion claims, surfaces circular deadlocks, coordinates parallel execution, and bridges terminal workflows with Obsidian vaults. The analysis outlines installation options, command flags, metric calculations, and binary collision safeguards for developer workstations.

Tkmd – A local CLI task manager and MCP: what actually changed

The release introduces a deterministic task engine that replaces cloud project boards and mutable state servers with structured local files. Every task lives inside a dedicated repository or vault directory as an individual Markdown card following the tk-XXX-*.md naming pattern. Instead of relying on heuristic queues or external databases, the software implements mathematical Critical Path Method scheduling and Design Structure Matrices. Workstations can run the tool as a standalone command line binary using tk or tkmd, or initialize it as a universal Stdio Model Context Protocol server that directly interfaces with developer agents.

Storage and configuration are divided across two primary operational modes and flexible repository scopes. Users can run an interactive setup wizard with tk init or target an Obsidian 1.14 vault using the obsidian flag, path, base, and daily arguments. This setup generates a tasks.base file containing five pre-configured views, updates property types in the Obsidian configuration without overwriting existing data, and logs finished items under daily notes. Alternatively, standalone CLI mode stores tasks in a local share directory, opens cards inside terminal editors like Helix, Vim, Neovim, or Micro, and disables application URI calls.

Tkmd – A local CLI task manager and MCP: how it works

The operational pipeline organizes multi-agent execution across three distinct phases consisting of planning, guarded execution, and cascading unblocking. A lead architect or human developer initiates the workflow by decomposing specifications into discrete tasks with defined dependency relationships. Running cycle detection through tk dep --dsm evaluates the dependency matrix to identify circular deadlocks before coding begins. The engine then executes the Critical Path Method with tk dep --cpm to calculate early start, early finish, late finish, and schedule buffers, allowing orchestrators to allocate worker agents specifically to zero-buffer critical path items.

During execution, autonomous subagents claim ready tasks using the claim command, which attaches the active session identifier. Write collisions across concurrent terminal sessions are eliminated through POSIX advisory file locking on the card files. Agents cannot transition a task directly to done; they must pass automated shell evaluation through tk eval and submit their work to a review gate using tk r, which marks the task as pending-close. Once a human signs off or designates an agent proxy to approve the work with tk d, the engine automatically unblocks downstream tasks and updates dependent statuses.

Tkmd – A local CLI task manager and MCP: why it matters now

The emergence of autonomous coding tools like Claude Code, Codex, and Gemini has introduced coordination failures across unmanaged software repositories. AI agents frequently hallucinate completion states, prematurely marking complex implementation steps as finished without running test suites or verifying integration boundaries. In parallel setups, multiple agents operating in separate terminal windows often collide when modifying shared state or become trapped in uncoordinated loops. By enforcing shell verification gates and human review before status transitions occur, the engine creates strict mechanical boundaries that prevent unverified code from progressing through the pipeline.

Data sovereignty and operational simplicity represent an equally pressing consideration for modern development teams. The tool issues zero HTTP requests, runs zero background service daemons, and contains no remote telemetry beacons. Historical events are recorded locally in a structured JSON Lines file called .events.jsonl. Built-in Rust commands calculate performance metrics including Little's Law, mean time to complete, and ninetieth-percentile throughput without requiring external analytics infrastructure. Developers who need customized metrics can run standard SQL queries directly against the local event log using DuckDB command line tools.

Tkmd – A local CLI task manager and MCP: who is affected

Individual developers managing complex software backlogs gain an offline organizational system that respects standard text utilities. Users working without Obsidian can manage project backlogs directly in their terminal, configuring tk init -L to generate a local configuration and task directory within a single repository root. Flags allow engineers to restrict operations to repository backlogs with -L, interact with global central vaults using -G, or merge all active scopes into a single view with -A. Stalled terminal sessions can be recovered immediately by invoking tk u with the task identifier to resume agent conversations.

Teams employing multi-agent swarms benefit from structured role delegation between architectural planners and specialized worker subagents. A backend subagent can work concurrently on an API task while a frontend subagent remains parked in a blocked state, receiving automatic promotion to ready the moment human verification clears the dependency. Because the engine runs as a single compiled binary without requiring Python or Node runtimes, it fits into resource-constrained development environments. Developers using Grafana Tanka or wedow/ticket avoid command collisions because tkmd is the authoritative crate name, allowing custom shell aliases.

Tkmd – A local CLI task manager and MCP: what to watch

Adoption will depend on how cleanly development teams integrate Model Context Protocol servers into their existing terminal configurations and editor setups. The installation script provides a standalone binary curl installer alongside source builds distributed through Cargo on crates.io. Shell completion generators support Zsh, Bash, Fish, PowerShell, and Elvish environments, enabling tab completion for both binary targets out of the box. Teams monitoring repository health should observe how effectively automated shell evaluation gates lower bug rates in pull requests produced by autonomous subagent workflows.

System operators must evaluate environment PATH priorities to ensure invocation commands do not conflict with existing tooling. The secondary binary alias tk collides with Grafana Tanka in Homebrew installations and the wedow/ticket repository issue tracker. Users should verify whether calling tkmd directly or configuring a shell alias like tkm provides the most dependable behavior across automated scripts. Observers will also track community adoption of Obsidian 1.14 Base views compared to pure terminal editing workflows in Helix, Neovim, and Vim as local multi-agent governance frameworks mature.