# tkmd

> A local Markdown task manager and program engine that uses CPM scheduling and verification gates to govern developers and AI coding agents.

tkmd (CLI: `tk` / `tkmd`) is a Rust command-line task and project manager built by Ken Harrison (ktreharrison). It stores each task as a plain Markdown card with YAML frontmatter, schedules work with Critical Path Method and Design Structure Matrix algorithms, and acts as a governance harness for AI coding agents. The latest listed release is v0.1.2.

## What It Is

tkmd is a deterministic program engine for developers and AI agents. Tasks live as `tasks/tk-XXX-*.md` files, and state transitions are recorded in an append-only `.events.jsonl` stream. It runs locally as a single binary, and the README states it makes no network requests and has no telemetry.

## How the Agent Governance Works

Agents claim tasks (`tk c`), attaching a session ID so the conversation can be resumed later (`tk u`). Before submitting work, an agent must pass the card's shell `eval` command, then move the task to `pending-close` (`tk r`). Only human sign-off (`tk d`) moves a task to `done`, which then auto-promotes downstream blocked tasks to `ready`. POSIX advisory file locking prevents write collisions between concurrent agents.

## Scheduling and Analysis

`tk dep --cpm` computes early start, late finish, schedule buffers and the critical path. `tk dep --dsm` detects circular dependencies, and tree, Gantt and AON views are also available. `tk st` computes flow telemetry such as Little's Law, MTTC and TPM90 natively, and the JSONL event log can optionally be queried with DuckDB.

## Setup and Storage Modes

Install via a shell script or `cargo install tkmd`. `tk init` supports an Obsidian mode that syncs with a `.base` Kanban board and Daily Notes, a standalone CLI mode, and a per-repository local backlog (`tk init -L`). Local, global and merged scopes can be selected with flags. Shell completions are generated for Zsh, Bash, Fish, PowerShell and Elvish.

## MCP and Agent Skill

`tkmd mcp` runs a JSON-RPC 2.0 MCP server over stdio. The README lists compatibility with Claude Desktop, Codex, Gemini CLI, Cursor, Zed, OpenCode and Pi. A bundled agent skill in `skills/tkmd` enforces the review-gate workflow.

## Features
- Markdown task cards with YAML frontmatter
- Critical Path Method scheduling (tk dep --cpm)
- Design Structure Matrix cycle detection
- Eval shell verification gates
- pending-close human sign-off workflow
- Automatic blocker cascade unblocking
- Session resume for AI agent sessions
- Stdio MCP server
- Obsidian Base Kanban sync
- Local, global and merged scopes
- Append-only JSONL event log and flow telemetry
- Fuzzy task search
- Shell completions
- Bundled agent skill

## Integrations
Obsidian, Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Zed, Claude Desktop, Pi, DuckDB, fzf, bat

## Platforms
MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.2

## Links
- Website: https://github.com/ktreharrison/tkmd
- Documentation: https://github.com/ktreharrison/tkmd
- Repository: https://github.com/ktreharrison/tkmd
- EveryDev.ai: https://www.everydev.ai/tools/tkmd