TaskMajor

Your tasks. Your rules. Your agents.

A local-first MCP server that gives AI agents native access to a full TaskWarrior-compatible engine.
No cloud. No binary to install. No lock-in. Just a pip install and your agents are in control.

Ask your agent:

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

---

Why TaskMajor?

Most task managers are cloud-first and agent-hostile. TaskMajor is neither.

• 🔒 100% local & private — all data stays on your machine, stored as plain text via the embedded TaskChampion engine
• ⚙️ Full TaskWarrior power — projects, priorities, due dates, tags, UDAs, dependencies, contexts — all accessible by your agent
• 🎭 Profile System — the feature no other task MCP has: define exactly what your agent can see and do, adapted to your methodology
• ⚡ Zero friction — one command installs and starts a fully functional MCP server

---

🚀 Quick Start

pip install taskmajor   # or: uv tool install taskmajor
taskmajor               # starts at http://localhost:8888

Point your MCP client (Claude Desktop, Hermes, Continue, or any MCP-compatible agent) at http://localhost:8888.

That's it. No TaskWarrior binary to install — the engine is embedded.

🤖 Hermes user in a hurry? → 5-minute Hermes setup

Want a specific workflow?

taskmajor --profile standard      # task CRUD + agenda (default)
taskmajor --profile productivity  # GTD: reviews, energy levels, contexts
taskmajor --profile project-mgmt  # sprints, effort tracking, blockers queue

→ Full installation options — uv, Docker, from source

---

📸 Demo

---

🎭 Profile System — TaskMajor's Killer Feature

Profiles are the heart of TaskMajor. Each profile defines a complete behavioral contract for your agent: what tools it can call, what data structures exist, what views it can read, and how it should reason about your tasks.

| Profile | Extends | What it unlocks | |---|---|---| | minimal | — | Bare CRUD: add, query, complete, delete | | standard | minimal | Agenda views, date tools, metadata, organization prompts | | productivity | standard | GTD: energy levels (low/medium/high), daily & weekly reviews, capture workflow, context tags (+@) | | project-mgmt | standard | Sprint planning, effort analytics, blockers queue | | your-profile | any built-in | Extend any profile without touching the package |

Custom profile in 3 lines:

# ~/.config/myproject/profiles/myprofile/manifest.yaml
extends: [productivity]
# add your own UDAs, contexts, resources, and agent instructions

taskmajor -c ~/.config/myproject

→ Profile System documentation

---

✨ Key Features

• 🔒 Private by design — plain-text storage, TaskChampion engine, runs entirely on your machine
• 🧠 Profile-shaped agents — agents see only what you expose; switch workflows with one flag
• ⚡ Energy-aware scheduling — low / medium / high energy UDA lets your agent suggest tasks that match your current state
• 🏷️ Safe context tags — +@work, +@home, +@focus filter tasks without breaking TaskWarrior's native context system
• 📅 Flexible date expressions — natural language dates resolved before any write operation
• 📋 Daily & weekly reviews — structured review resources and prompts built into the productivity profile
• 🔄 Optional sync — periodic or manual sync to a TaskChampion server (local or remote)
• 🔌 Any MCP client — works with Claude Desktop, Hermes, Continue, or any MCP-compatible agent
• 🐳 Docker-ready — official Dockerfile for containerized deployments
• 📊 Built-in analytics — stats by project, priority, and status; effort and sprint tracking in project-mgmt

---

📚 Documentation

| For | Start here | |---|---| | First install | Getting Started | | 5-minute walkthrough | Quick Start guide | | Hermes agent users | Hermes Quick Start | | Custom workflows | Profile System | | All profiles reference | Profile Reference | | Tools & resources API | API Reference | | Config & CLI flags | Configuration | | Docker / from source | Deployment | | Contributing | Contributing |

---

🌐 Community

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

---

📄 License

MIT — see LICENSE

---

Built with FastMCP · pytaskwarrior · TaskChampion · Pydantic