taskmajor 0.3.3rc1

TaskMajor MCP. Coordinate your tasks. Execute with precision.

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

• Python 3.10+

• uv (recommended) or pip

• No external TaskWarrior binary required — TaskMajor bundles the TaskChampion engine via taskchampion3-py-dev (PyO3/Rust). Install and go.

  Advanced: If you want to use an existing task CLI installation instead of the embedded engine, ensure TaskWarrior v3.x is on your PATH. See the pytaskwarrior docs for details.

Installation & Running

1. Clone and Install

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

   Optional: OpenTelemetry / OTLP export Telemetry (traces, metrics, log export) is an optional extra. Install it only if you have an OTLP-compatible backend (Jaeger, Grafana, etc.):

   pip install taskmajor[telemetry]
   # or
   uv sync --extra telemetry
   

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 something like: INFO Starting TaskMajor (taskrc=~/.taskrc_mcp, ...).

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 Agent Configuration guide for copy-paste snippets for your specific editor.

Docker Option

If you prefer containerization or need a self-contained environment:

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

Remember to mount your config.yaml if you want to customise TaskWarrior paths or profiles.

---

📚 Documentation

Section	For
Agent Configuration	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 bindings for TaskWarrior / TaskChampion
• taskchampion3-py-dev — Embedded TaskChampion engine (PyO3/Rust, no external binary needed)
• Pydantic — Data validation
• OpenTelemetry — Observability

---