TaskMajor — Manage Tasks with Any AI Agent

TaskMajor MCP. Coordinate your tasks. Execute with precision.

TaskMajor connects your AI assistants to your task management—organized your way, hosted on your terms.

Ask your assistant:

"Add a task to review the API spec"
"What's on my plate for today?"
"Run my daily review"
"Show me the roadmap for Project X"

Behind this sits TaskWarrior—a remarkably flexible, battle-tested task engine. It runs locally, stores plain text, and bends to almost any organizational style. TaskMajor builds on that foundation and adds its own layer of adaptability: the profile system. Each profile defines a unique contract of exposed tools, views, and behaviors—turning TaskMajor into anything from a simple to-do list to a full GTD system or a multi-agent coordination hub. Explore the built-in profiles or learn how to compose and extend them in the profile documentation.

Ready to transform your task management? Jump straight into the Quick Start to get running in minutes.

🚀 Quick Start

Prerequisites

• TaskWarrior v3.0+ is required.
  • macOS: brew install task
  • Linux/Windows: Download from taskwarrior.org
  • Alternative: If you cannot install TaskWarrior locally, use the Docker option below which includes a bundled version.
• Python 3.10+
• uv (recommended) or pip

Installation & Running

1. Clone and Install

   git clone https://github.com/nschmeltz/taskmajor.git
   cd taskmajor
   uv sync

2. (Optional) Configure

   Important for TaskWarrior users: If you already have a TaskWarrior database, you must edit taskmajor/config/config.yaml if you want to share your existing data directory.

   # taskmajor/config/config.yaml
   taskrc: /path/to/your/.taskrc # default: ~/.taskrc_mcp
   taskdata: /path/to/your/.task # default: ~/.task_mcp/

3. Launch the Server

   uv run -m taskmajor.bootstrap.server --help  # shows overridable options like --transport, --server-port, --server-host
   uv run -m taskmajor.bootstrap.server

   You should see: INFO: TaskMajor MCP Server ready.

4. Connect Your Agent That's it. Now, simply configure your AI agent (Hermes, Copilot, Claude, Cursor, ...) to connect to this local MCP server. See the Connect Your Agent guide for copy-paste snippets for your specific editor.

Docker Option

If you prefer containerization or need a bundled TaskWarrior instance:

docker build -t taskmajor . && mkdir taskdata && docker run -d -v $PWD/taskdata:/home/taskmajor/.task_mcp -p 8888:8888 taskmajor

Remember to mount your config.yaml and TaskWarrior data directory if you want to persist data.

---

📚 Documentation

Section	For
Connect Your Agent	Copilot, Claude Code, Cursor, Hermes
Getting Started	DevOps / Deployment
API Reference	Developers / Integrators
Architecture	System design and concepts
Configuration	Environment variables and setup
Profiles	Workflow methodologies & custom profiles
Docker: Custom Profiles	Mount profiles without overwriting built-ins
Troubleshooting	Common issues and solutions
Contributing	Add a new agent integration

🌐 Community

• Issues & Features: GitHub Issues
• Discussions: GitHub Discussions

---

📄 License

MIT License — See LICENSE for details.

---

🏗 Acknowledgments

Built with:

• FastMCP — Modern MCP framework
• pytaskwarrior — Python TaskWarrior wrapper
• Pydantic — Data validation
• OpenTelemetry — Observability

---