https://github.com/sznicolas/taskmajor
https://github.com/sznicolas/taskmajor
hermes-agent mcp-server task-management taskwarrior taskwarrior3
Last synced: 2 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/sznicolas/taskmajor
- Owner: sznicolas
- Created: 2026-03-31T05:18:49.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T09:23:49.000Z (about 1 month ago)
- Last Synced: 2026-05-25T11:12:00.007Z (about 1 month ago)
- Topics: hermes-agent, mcp-server, task-management, taskwarrior, taskwarrior3
- Language: Python
- Homepage:
- Size: 1.57 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# TaskMajor
[](https://pypi.org/project/taskmajor/)
[](https://www.python.org/)
[](#quick-start)
[](#why-taskmajor)
[](LICENSE)
[](https://codecov.io/gh/sznicolas/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:
```text
"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
```bash
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](docs/quickstart_hermes.md)
**Want a specific workflow?**
```bash
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](docs/getting-started/index.md) — 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:**
```yaml
# ~/.config/myproject/profiles/myprofile/manifest.yaml
extends: [productivity]
# add your own UDAs, contexts, resources, and agent instructions
```
```bash
taskmajor -c ~/.config/myproject
```
→ [Profile System documentation](docs/user-guides/profiles/profile-system.md)
---
## ✨ 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](docs/getting-started/index.md)** |
| 5-minute walkthrough | **[Quick Start guide](docs/getting-started/getting-started.md)** |
| Hermes agent users | **[Hermes Quick Start](docs/quickstart_hermes.md)** |
| Custom workflows | **[Profile System](docs/user-guides/profiles/profile-system.md)** |
| All profiles reference | **[Profile Reference](docs/user-guides/profiles/reference/)** |
| Tools & resources API | **[API Reference](docs/api-reference/index.md)** |
| Config & CLI flags | **[Configuration](docs/getting-started/configuration.md)** |
| Docker / from source | **[Deployment](docs/deployment/build-from-source.md)** |
| Contributing | **[Contributing](docs/developer/contributing.md)** |
---
## 🌐 Community
- **Issues & Features:** [GitHub Issues](https://github.com/sznicolas/taskmajor/issues)
- **Discussions:** [GitHub Discussions](https://github.com/sznicolas/taskmajor/discussions)
---
## 📄 License
MIT — see [LICENSE](LICENSE)
---
Built with [FastMCP](https://github.com/jlowin/fastmcp) · [pytaskwarrior](https://github.com/sznicolas/pytaskwarrior) · [TaskChampion](https://pypi.org/project/taskchampion3-py-dev/) · [Pydantic](https://docs.pydantic.dev/)