mattermind

Ask natural-language questions about your Mattermost workspace using LLM tool-calling.

Documentation

Tip

Building this with an AI assistant? Hand it one page instead of the whole site: every command and flag, every configuration key and its default, the four tools the model is given, the rules that break a run when they are broken, the mistakes assistants actually make with this CLI, and a map of which page to fetch for the rest. Every docs page is also served as raw Markdown at its own URL, and a Copy page button at the top of each one hands it straight to a chat window.

Features

• Full-text search across your Mattermost team via the REST API v4
• Agentic loop with tool calling (search, get thread, resolve permalink, look up users)
• Follows permalink chains up to a configurable depth
• Cites every claim with clickable permalink links
• Rich terminal UI with progress, answer rendering, and token usage summary
• Interactive TUI chat interface (mattermind chat)
• JSON output mode for scripting (--json)
• Token budget protection with interactive continue prompt
• SSO-compatible: authenticate via session token (MMAUTHTOKEN) or login/password
• Self-signed certificate support (verify_ssl: false)
• Interactive setup wizard (mattermind init)

Installation

uv tool install mattermind
# or from source:
uv sync --extra dev

Quick Start

# Interactive setup
mattermind init

# Or: save your Mattermost session token
mattermind login

# List available teams and save your choice
mattermind teams

# Ask a question
mattermind ask "What was decided about the auth service migration?"

# Interactive TUI chat
mattermind chat

# JSON output
mattermind ask "latest incidents?" --json | jq .answer

Authentication

Mattermind supports two authentication methods:

Token (recommended for SSO environments):

mattermind login
# Follow the instructions to copy MMAUTHTOKEN from browser DevTools

Or set in config:

mattermost:
  token: ${MM_TOKEN}

Login / Password:

mattermost:
  login: user@company.com
  password: ${MM_PASSWORD}

Configuration

Priority (lowest to highest): defaults → ~/.config/mattermind/config.yaml → env vars → CLI flags.

# ~/.config/mattermind/config.yaml
mattermost:
  url: https://mm.company.com
  token: ${MM_TOKEN}          # env interpolation supported
  team: engineering
  verify_ssl: true             # set false for self-signed certs

llm:
  base_url: https://api.openai.com/v1
  api_key: ${OPENAI_API_KEY}
  model: gpt-4o-mini
  verify_ssl: true

agent:
  max_iterations: 15
  total_token_budget: 200000
  max_threads_per_query: 20

output:
  format: markdown             # markdown | plain | json
  show_thread_tree: true
  show_token_usage: true
  show_timings: true

logging:
  level: INFO                  # DEBUG | INFO | WARNING | ERROR | CRITICAL

Unknown keys are rejected rather than ignored, so a typo fails validation with the key named in the error.

Environment Variables

Variable	Description
MATTERMIND_MM_URL	Mattermost server URL
MATTERMIND_MM_TOKEN	Personal Access Token / MMAUTHTOKEN
MATTERMIND_MM_LOGIN	Login (email or username)
MATTERMIND_MM_PASSWORD	Password
MATTERMIND_TEAM	Team slug
MATTERMIND_MM_VERIFY_SSL	Verify Mattermost TLS (true/false)
MATTERMIND_LLM_BASE_URL	LLM API base URL (OpenAI-compatible)
MATTERMIND_LLM_API_KEY	LLM API key
MATTERMIND_MODEL	Model name
MATTERMIND_LLM_VERIFY_SSL	Verify LLM gateway TLS (true/false)

Commands

mattermind ask <question>   Ask a question about your Mattermost workspace
mattermind chat             Launch interactive TUI chat interface
mattermind teams            List available teams and save your selection
mattermind login            Save a session token (MMAUTHTOKEN) to config
mattermind init             Interactive config setup wizard
mattermind config show      Print resolved config (secrets masked)
mattermind config validate  Validate config and check both endpoints are reachable
mattermind version          Print version

Global flags

Accepted before or after the subcommand:

-c / --config PATH    Path to config YAML file
-v / --verbose        Enable verbose output (shows tool calls)
-q / --quiet          Print the answer as plain text, without the UI chrome
--json                Output result as JSON (machine-readable)
--no-color            Disable colour output

Development

make install    # install deps
make fmt        # format + fix lint
make check      # lint + type-check
make test       # run unit tests with coverage
make test-all   # unit + integration tests (needs a real MM and LLM)

Architecture

src/mattermind/
├── cli/        — Typer CLI app, commands, app context
├── config/     — Pydantic models, YAML loader, env interpolation, wizard
├── mattermost/ — Async httpx client, Mattermost REST API v4, domain models
├── agent/      — Agentic loop, tool definitions, system prompt, state
└── ui/         — Rich rendering, Textual TUI, error panels