mattermind

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

Documentation

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

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