┌──────────────────┐   HTTP   ┌───────────────────┐
│ tasks CLI / TUI  │ ────────▶│  Flask REST API   │  :2999 (container) / :3101 (host)
│ (bin/tasks)      │          │  (task_api/)      │──┐
└──────────────────┘          └───────────────────┘  │   ┌──────────────┐   ┌───────────────────┐
                                                     ├──▶│  task_lib/   │──▶│  Markdown files   │
┌──────────────────┐   MCP    ┌───────────────────┐  │   │ (in-process) │   │  /data/tasks/     │
│ AI assistant     │ ────────▶│  MCP server       │──┘   └──────────────┘   └───────────────────┘
│ (Claude etc.)    │          │ (mcp_task_service)│  :3003                     ▲
└──────────────────┘          └───────────────────┘                             │ same folder
                                                     Tasks.md web app ──────────┘

task.md-utilities/
├── bin/
│   ├── tasks               # CLI — TUI (no args) or subcommands (scripting)
│   └── tag-utility.py      # One-time tag format migration utility
├── docs/
│   └── screenshot.svg      # TUI kanban board screenshot
├── task_lib/
│   ├── api_client.py       # Shared HTTP helpers (used by CLI and TUI)
│   ├── cli_config.py       # CLI settings (~/.config/tasks/config.yaml)
│   ├── config.py           # Configuration (YAML)
│   ├── lane_order.py       # Per-machine lane (column) order for CLI and TUI
│   ├── errors.py           # Typed errors: not_found, exists, invalid, conflict
│   ├── sections.py         # Partial edits: append, upsert section, check items
│   ├── task.py             # Task model and file I/O
│   └── task_manager.py     # Lane, task and trash operations
├── task_tui/               # Textual TUI package
│   ├── app.py              # KanbanApp — main board, keybindings, workers
│   ├── api.py              # Sync API wrappers for use in workers
│   ├── screens.py          # Detail, form, confirm, filter, move screens
│   └── widgets.py          # LaneColumn, TaskItem, FunctionKeyBar
├── task_api/               # Flask REST API service
│   ├── app.py
│   ├── config.py
│   ├── models.py           # Pydantic request/response schemas
│   ├── routes/             # tasks, trash, lanes, operations, health
│   ├── gunicorn.conf.py
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── README.md
├── mcp_task_service/       # FastMCP server for AI assistants
│   ├── server.py
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── README.md
├── tests/                  # pytest suite (conftest.py isolates $HOME)
├── config.yaml             # Task data location (baked into Docker images)
├── tasks.config.example.yaml  # Every CLI setting with its default
├── docker-compose.yml      # Deploys both services together
├── Makefile                # build / push / deploy / test / lint
└── .mcp.json               # Connects Claude Code in this repo to the MCP server

make push      # build and push both images (make build to only build)
make release   # run the tests first, then build and push
make deploy    # recreate the containers in /opt/stacks/mcp-task

# Single service, or another registry/tag
make push-mcp
make push-api REGISTRY=registry.example:5000 TAG=0.3.0

make deploy    # docker compose pull && up -d --force-recreate in /opt/stacks/mcp-task

volumes:
  - /mnt/raid1/lib/tasks.md/tasks:/data/tasks

base_dir: /data/tasks

cd task_api && docker-compose up -d       # REST API only
cd mcp_task_service && docker-compose up -d  # MCP only

poetry install
poetry run bin/tasks --help

alias tasks='poetry -C ~/Working/task.md-utilities run ~/Working/task.md-utilities/bin/tasks'

api_url: http://your-server:3101

tasks

tasks [--api-url URL] [--config PATH] COMMAND

Commands:
  show         List tasks (--lane, --tag, --string, --query, --due-before,
               --due-after, --sort lane|title|due|modified)
  find         Search titles and bodies, showing the matching text
  get          Show a single task in full
  add          Create a new task (lane must exist unless --create-lane)
  update       Update task fields
  append       Append text to the end of a task
  section      Replace (or add) one "## Heading" section of a task
  check        Tick "- [ ]" checklist items (--uncheck to untick)
  delete       Move a task to Trash
  move         Change a task's lane (--create-lane for a new lane)
  trash        Manage the Trash
    list       List trashed cards, newest first
    restore    Restore a card into a lane
    empty      Permanently delete Trash (--dry-run, --yes)
  empty-trash  Same as `trash empty`
  split        Split tasks containing [[split]] marker
  lanes        Manage lanes
    list       List lanes with task counts
    order      Show or set the column order (--reset)
    add        Create a new lane
  stats        Show statistics summary

# List all tasks
tasks show

# Filter by lane, tag, or title substring (all case-insensitive)
tasks show --lane "In Progress"
tasks show --tag urgent
tasks show --string "login"

# Show full task detail
tasks get "Implement login"

# Create a task (prompts for missing fields)
tasks add --title "Fix bug" --content "Reproduce and fix" --lane Backlog --tags "bug,urgent"

# Update fields (only provided fields change)
tasks update "Fix bug" --tags "bug,urgent,p1" --due-date 2026-06-01

# Search titles and bodies; sort by due date
tasks find "books db"
tasks show --sort due --due-before 2026-06-30

# Edit part of a card without resending the whole body
tasks section "Fix bug" Progress "Reproduced on staging"
tasks append --no-blank-line "Fix bug" -- "- [ ] write regression test"
tasks check "Fix bug" "regression test"
echo "Patch the null check" | tasks section "Fix bug" "Next action" -

# Move between lanes
tasks move "Fix bug" "In Progress"

# Delete (moves to Trash, prompts for confirmation)
tasks delete "Fix bug"

# Trash: list, restore, preview, then permanently delete (prompts for confirmation)
tasks trash list
tasks trash restore "Fix bug" Backlog
tasks trash empty --dry-run
tasks trash empty

# Lane management
tasks lanes list
tasks lanes add "Sprint 3"

# Column order: named lanes first, the rest keep their order after them
tasks lanes order                 # show it
tasks lanes order Doing Backlog   # set it
tasks lanes order --reset         # back to alphabetical

# Split a task (divides on [[split]] marker)
tasks split

# Statistics
tasks stats

{
  "mcpServers": {
    "task-manager": {
      "type": "http",
      "url": "http://localhost:3003/mcp"
    }
  }
}

# Health check
curl http://localhost:3101/health

# List tasks
curl "http://localhost:3101/tasks"
curl "http://localhost:3101/tasks?lane=Backlog&tag=urgent"
curl "http://localhost:3101/tasks?search=login"          # title substring
curl "http://localhost:3101/tasks?query=books%20db&sort=due"  # title or body

# Create a task
curl -X POST http://localhost:3101/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"My Task","content":"Details","lane":"Backlog","tags":["urgent"]}'

# Move a task
curl -X POST "http://localhost:3101/tasks/My%20Task/move" \
  -H 'Content-Type: application/json' \
  -d '{"lane":"In Progress"}'

# Trash: list, preview emptying
curl http://localhost:3101/trash
curl -X DELETE "http://localhost:3101/operations/trash?dry_run=true"

# Statistics
curl http://localhost:3101/operations/statistics

[tag:frontend]
[tag:urgent]
[due:2026-06-01]

Task body text goes here.

/data/tasks/
├── Backlog/
│   └── Implement login.md
├── In Progress/
│   └── Fix auth bug.md
├── Done/
│   └── Setup CI.md
└── Trash/
    └── old-task~20261014-120102.md   # timestamp suffix keeps same-named cards apart

poetry install --extras dev   # adds black, mypy and type stubs

make test   # pytest with coverage for task_lib, task_api, mcp_task_service
make lint   # black --check and mypy on the modules kept clean so far

mkdir -p /tmp/tasks-dev && echo "base_dir: /tmp/tasks-dev" > /tmp/tasks-dev.yaml

TASK_CONFIG_PATH=/tmp/tasks-dev.yaml poetry run gunicorn --config task_api/gunicorn.conf.py "task_api.app:create_app()"
TASK_CONFIG_PATH=/tmp/tasks-dev.yaml poetry run python mcp_task_service/server.py