majordomo 0.1.4

Read and report Google Chat task activity from the cache mirror.

majordomo

A command-line tool that reads Google Chat and reports task activity. The command line is the primary interface; an MCP server is a secondary interface for AI agents. Both are thin front doors over one shared core.

What it does

When someone creates a task through Google Chat's "Create a task for @Person (via Tasks)", that task cannot be retrieved through the Google Tasks API; the only durable signal is the chat message itself (see GOOGLE_CHAT_TASKS_LIMITATIONS.md). majordomo reconstructs task activity from those messages and reports who holds which tasks across spaces over a date range.

• Tasks by assignee, space, and date; "assigned to me" and "assigned by me".
• Spaces, people (participants with message and task counts), and raw messages by space or thread.
• Three modes, one shape. The fast path reads an existing server-side cache of Chat (the data model). --live is up-to-dateness: it serves the cache and tops it up from the Chat API with anything newer. --nocache reads the Chat API directly and decodes tasks itself, so the tool also works without the cache. Every result is tagged with its source; an unforced read uses the cache and falls back to the direct API automatically when the cache is unreachable.
• A privacy sieve in the core drops blocked spaces (and assignees) before any caller (CLI or MCP) can see them.
• Output as a rich console table, --json, or --csv.

Install

The simplest cross-platform install is from PyPI:

pip install majordomo                  # CLI, reads the Chat cache
pip install "majordomo[nocache,mcp]"   # plus the live Chat API path and the MCP server

With uv, uvx majordomo ... runs it without installing and uv tool install majordomo installs it permanently.

Homebrew (macOS or Linux):

brew tap overseers-desk/od
brew install majordomo

Python 3.11+.

Run directly, no virtualenv, with Ubuntu/Debian packages:

sudo apt-get install python3-typer python3-rich python3-pymysql
# for the API path (majordomo login, --live top-up, --nocache) also:
sudo apt-get install python3-googleapi python3-google-auth python3-google-auth-oauthlib

Then run from the repo without installing the package:

PYTHONPATH=src python3 -m majordomo spaces

Or install the package (puts majordomo on your PATH):

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[nocache,mcp]"   # drop the extras you don't need
majordomo --help

The MCP server (majordomo mcp) needs the mcp PyPI package, which is not in apt; install it through the virtualenv above (the mcp extra).

Configuration

majordomo reads two files from ~/.config/majordomo/:

config.toml (hand-edited):

[me]
user_id = "users/1234567890"      # your Chat id, for --to-me / --by-me
                                   # (find it with `majordomo people`)

[sieve]
block_spaces = ["spaces/AAAA"]     # never shown through any front door
block_assignees = ["users/9999"]   # drop these assignees from every report

[nocache]                          # optional; defaults shown (OAuth for the API path)
token_file = "~/.config/majordomo/token.json"
client_file = "~/.config/majordomo/client_secret.json"

.env (the cache database connection, when using the cache path):

MYSQL_HOST=…
MYSQL_PORT=3306
MYSQL_USER=…
MYSQL_PASSWORD=…
MYSQL_DATABASE=…

Authenticating (OAuth for the API path)

majordomo login opens a browser OAuth flow and writes ~/.config/majordomo/token.json (read-only Chat scopes), used by --live (for the top-up) and --nocache. It needs a Desktop OAuth client with the Google Chat API enabled, saved as client_secret.json in the config directory.

majordomo login

Commands

majordomo spaces
majordomo people --window year
majordomo tasks --to-me --window month
majordomo tasks --assignee-name '*Alice*' --since 2026-01-01
majordomo messages --space spaces/AAAA --window 7d
majordomo messages --thread spaces/AAAA/messages/BBBB
majordomo mcp                       # run the MCP server (stdio)

• Source: default cache with an automatic direct-API fallback. --cache forces the cache; --live adds a freshness top-up from the API; --nocache reads the API directly.
• Window: 7d | 30d | month | year | all, or --since / --until (ISO dates).
• Output: default console, --json, or --csv.

Not yet (deferred)

• Task completion and stats. Google Chat does not reliably carry task completion, so every task is reported as open; completion-rate reporting waits on a later signal.
• Directory name resolution. Names come from the chat message and the Chat API directly; a bare users/<id> with no name attached is shown as the id.

License

See LICENSE.