TICK.md

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

🤝 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

📦 Packages

• tick-md - CLI tool (v1.2.1)
• tick-mcp-server - MCP server for AI agents (v1.1.1)
• tick-md - ClawHub skill for OpenClaw bots

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Ways to contribute:

• 🐛 Report bugs
• 💡 Suggest features
• 📖 Improve documentation
• 🔧 Submit pull requests

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• commander.js - CLI framework
• chalk - Terminal styling
• gray-matter - YAML frontmatter
• Model Context Protocol - AI agent integration

🔗 Links

• Website: tick.md
• npm: tick-md · tick-mcp-server
• ClawHub: tick-md skill
• Documentation: Full Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

💬 Community

• Share your workflows and integrations
• Ask questions in Discussions
• Join the coordination revolution!

❤️ Support

TICK.md is 100% free and open source. If it helps you, consider supporting development:

• Sponsor on GitHub
• ⭐ Star this repo

Created by @giannidalerta and his mass of agents

Coordinate smarter, not harder.