TICK.md

February 19, 2026 · View on GitHub

Multi-agent task coordination via Git-backed Markdown

Coordinate work across human and AI agents using structured TICK.md files. Built on Git, designed for natural language interaction, optimized for multi-agent workflows.

100% open source. Protocol, CLI, dashboard, MCP server — all free forever.

💡 Why tick-md?

AI agents speak Markdown. So does your documentation, your notes, and your Git history. tick-md turns that into a coordination protocol — no databases, no APIs, no vendor lock-in. Just a TICK.md file that humans can read and bots can parse.

When you have multiple agents (or humans) working on a project, they need a shared source of truth. tick-md gives you that through Git: every claim, every status change, every completion is a commit. Conflicts resolve the same way code conflicts do. History is built in.

✨ Features

🤖 AI-Native: MCP server for seamless bot integration
📝 Human-Readable: Plain Markdown with YAML frontmatter
🔄 Git-Backed: Full version control and audit trail
🎯 Dependency Tracking: Automatic task unblocking
🔍 Advanced Filtering: Find tasks by status, priority, tags
📊 Visualization: Dependency graphs (ASCII and Mermaid)
👀 Real-Time Monitoring: Watch mode for live updates
🌐 Local-First: No cloud required, works offline

🚀 Quick Start

# Install
npm install -g tick-md

# Initialize in your project
cd your-project
tick init

# Add a task
tick add "Build authentication" --priority high --tags backend

# Claim it and get to work
tick claim TASK-001 @yourname

# Mark it done (auto-unblocks dependent tasks)
tick done TASK-001 @yourname

# See your progress
tick status

That's it. Your tasks live in TICK.md — human-readable, Git-tracked, AI-compatible.

🤖 For AI Agents

Install MCP Server

npm install -g tick-mcp-server

Configure (see INSTALL.md for editor-specific setup)

Add to your MCP config:

{
  "mcpServers": {
    "tick": {
      "command": "tick-mcp",
      "args": []
    }
  }
}

Install via ClawHub (for OpenClaw Bots)

clawhub install tick-md

OpenClaw bots can now coordinate tasks through natural conversation!

📖 Documentation

CLI Commands - Complete command reference
MCP Server - API for AI agents
ClawHub Skill - Bot coordination guide
Changelog - Release highlights
Build Sessions - Development notes

🆕 Latest Release Highlights

tick-md `1.2.1`

Shared @tick/core package introduced as the single source of truth for parser, serializer, types, validation, and atomic file I/O.
CLI reliability improvements (archive, backup, broadcast, notify queue, conflict helpers, parse cache, completion, repair).
Safer destructive operations: tick delete now creates a backup before mutation.
Concurrency hardening with stale-write detection in core file writes.

tick-mcp-server `1.1.1`

MCP server now uses @tick/core directly (no dist-bridge imports).
Cleaner type safety and reduced build coupling.
Improved compatibility for bundling and plugin distribution.

ClawHub Plugin

Added native Nix plugin package in clawhub-plugin/ with prebuilt MCP bundle.
Added orchestrator/worker role instructions for agent coordination.
Added plugin test and bundle update scripts for release workflow.

🎯 Core Workflow

# Project setup
tick init                          # Initialize TICK.md
tick agent register @bot --type bot # Register agent

# Task management
tick add "Task title" --priority high
tick list --status todo            # Filter tasks
tick graph                         # Visualize dependencies

# Work coordination
tick claim TASK-001 @bot           # Claim task
tick comment TASK-001 @bot --note "Making progress"
tick done TASK-001 @bot            # Complete (auto-unblocks dependents)

# Real-time monitoring
tick watch                         # Watch for changes

# Git integration
tick sync --push                   # Commit and push

🏗️ Project Structure

tick-md/
├── packages/tick-core/   # Shared core logic (types/parser/serializer/validator/I-O)
├── cli/                  # Command-line interface (npm: tick-md)
├── mcp/                  # MCP server (npm: tick-mcp-server)
├── clawhub-skill/        # ClawHub skill package
├── clawhub-plugin/       # Native Nix plugin for OpenClaw
├── src/                  # Website, docs, dashboard (Next.js)
├── TICK.md              # This project's own task tracking
└── LICENSE              # MIT License

📋 Command Reference

Command	Description
`tick init`	Initialize new project
`tick status`	Show project overview
`tick list`	List/filter tasks
`tick add`	Create task
`tick claim`	Claim task
`tick done`	Complete task
`tick reopen`	Reopen completed task
`tick delete`	Delete a task
`tick edit`	Direct field edits
`tick undo`	Undo last operation
`tick import`	Bulk import from YAML
`tick batch`	Batch mode (start/commit/abort)
`tick graph`	Visualize dependencies
`tick watch`	Monitor changes in real-time
`tick validate`	Check for errors
`tick sync`	Git integration
`tick agent`	Manage agents (register/list)

🤝 Use Cases

For Development Teams

Coordinate work across multiple developers
Track dependencies and blockers
Maintain audit trail via Git
Natural language task management

For AI Agent Swarms

Multi-bot task coordination
Transparent work tracking
Prevent duplicate effort
Enable bot-to-bot handoffs

For Solo Developers

Structure your work
Track progress visually
Integrate with Git workflow
Command-line productivity

🌟 Example Workflows

Bot Creates and Claims Task

// Via MCP
await tick_add({
  title: "Refactor authentication system",
  priority: "high",
  tags: ["backend", "security"]
});

await tick_claim({ taskId: "TASK-023", agent: "@bot" });
await tick_comment({ 
  taskId: "TASK-023", 
  agent: "@bot",
  note: "Analyzing current implementation"
});
await tick_done({ taskId: "TASK-023", agent: "@bot" });

Human Monitors Progress

tick watch
# [20:15:32] ✓ Added: TASK-023 - Refactor authentication system
# [20:15:35] 🔒 TASK-023 claimed by @bot
# [20:17:42] ⟳ TASK-023: in_progress → done

🔧 Advanced Features

Dependency Management

tick add "Deploy to production" --priority high
tick add "Run tests" --blocks TASK-001
tick add "Update docs" --blocks TASK-001

# When tests and docs complete, deploy automatically unblocks

Task Filtering

tick list --status blocked         # Find blockers
tick list --priority urgent --json # Export data
tick list --claimed-by @bot        # Bot's tasks
tick list --tag security           # Security tasks

Dependency Visualization

tick graph                         # ASCII tree
tick graph --format mermaid        # For documentation

🛠️ Development

# Clone repo
git clone https://github.com/Purple-Horizons/tick-md.git
cd tick-md

# Build CLI
cd cli
npm install
npm run build

# Build MCP server
cd ../mcp
npm install
npm run build

# Test locally
npm link
tick init