Metadata-Version: 2.4
Name: taskmajor
Version: 1.0.0
Summary: TaskMajor MCP. Coordinate your tasks. Execute with precision.
Requires-Python: <3.14,>=3.10
Requires-Dist: fastmcp<4.0.0,>=3.0.0
Requires-Dist: pydantic<3.0.0,>=2.8
Requires-Dist: pytaskwarrior<4.0.0,>=3.0.1
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Provides-Extra: telemetry
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.39.1; extra == 'telemetry'
Requires-Dist: opentelemetry-instrumentation-httpx<1.0.0,>=0.60b1; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.39.1; extra == 'telemetry'
Description-Content-Type: text/markdown

# TaskMajor

[![PyPI](https://img.shields.io/pypi/v/taskmajor)](https://pypi.org/project/taskmajor/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet)](#quick-start)
[![Local‑First](https://img.shields.io/badge/local--first-%E2%9C%93-brightgreen)](#why-taskmajor)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![codecov](https://codecov.io/gh/sznicolas/taskmajor/branch/main/graph/badge.svg)](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.

**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

<!-- TODO: Add a screenshot or animated GIF here showing TaskMajor in action with an MCP client -->
> *Screenshot or animated demo coming soon.*

---

## 🎭 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)** |
| 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/)
