This is for raw evidence only. It writes under ai/inbox/mattermost-mirror/; durable project memory still belongs in project-knowledge/ after normal promotion rules.

Why this exists

Mattermost Team Edition 11.4.2 exposes normal /api/v4 REST and WebSocket traffic. When Mattermost Desktop is launched with Chromium/Electron's --proxy-server flag, mitmproxy can capture only that app without changing the macOS system proxy.

Setup

Install mitmproxy.
Trust the mitmproxy certificate if HTTPS interception is not already working:
- Start scripts/mattermost-proxy/run-mirror.sh
- Open http://mitm.it
- Install/trust the certificate in Keychain.
Optional: copy .env.example to .env and set MATTERMOST_MIRROR_HOST_ALLOW to the exact Mattermost host.

Run day to day

Terminal 1:

scripts/mattermost-proxy/run-mirror.sh

Terminal 2:

scripts/mattermost-proxy/launch-mattermost.sh

This launches Mattermost Desktop through macOS LaunchServices with:

--proxy-server=http://127.0.0.1:8080

No global macOS proxy is required.

The helper intentionally uses open -n /Applications/Mattermost.app --args ... instead of invoking /Applications/Mattermost.app/Contents/MacOS/Mattermost directly. Direct binary launch can crash sandboxed Electron apps with Mach rendezvous errors because their expected app/container parent process is missing.

Output layout

ai/inbox/mattermost-mirror/
  latest.jsonl              # bounded AI-readable window
  latest.md                 # bounded Markdown view
  state.json                # last seen by channel and user cache
  index.json                # date/channel file map
  messages/YYYY/MM/YYYY-MM-DD.jsonl
  raw/YYYY/MM/YYYY-MM-DD-websocket.jsonl     # only if MATTERMOST_MIRROR_WRITE_RAW=1
  raw/YYYY/MM/YYYY-MM-DD-rest-flows.jsonl    # only if MATTERMOST_MIRROR_WRITE_RAW=1

Use latest.md or latest.jsonl for quick AI context. Use date-rotated messages/... files for previous-workday or channel/date-specific analysis.

The mirror writes any post payload it sees, including older messages returned when the desktop app loads channel history or a thread. It dedupes by post_id, so scrolling back through useful history is a safe way to backfill missing local evidence without creating repeated entries.

Normalized message schema

Each line in the normalized JSONL contains:

{
  "source": "websocket|rest",
  "captured_at": "2026-05-19T...Z",
  "created_at": "2026-05-19T...Z",
  "created_at_ms": 1779190000000,
  "channel_id": "...",
  "channel_name": "fidelity-preguntas",
  "post_id": "...",
  "root_id": "...",
  "thread_id": "...",
  "user_id": "...",
  "username": "jeff",
  "message": "...",
  "type": "channel_post|thread_reply",
  "raw_event": "posted|posts|post"
}

Safety rules

The addon allowlists Mattermost hosts and /api/v4 traffic only.
Headers such as Authorization, Cookie, Set-Cookie, and CSRF are redacted in optional raw output.
Optional raw output is disabled by default to prevent large files.
Attachments are not downloaded by this mirror.
The mirror is evidence, not canonical memory.

Useful environment variables

MATTERMOST_MIRROR_HOST_ALLOW: exact host or parent domain to capture.
MATTERMOST_MIRROR_DIR: output directory, default ai/inbox/mattermost-mirror.
MATTERMOST_MIRROR_LATEST_LIMIT: number of messages in latest.*, default 200.
MATTERMOST_MIRROR_CHANNEL_IDS: optional comma-separated channel ID allowlist.
MATTERMOST_MIRROR_WRITE_RAW: set to 1 to save compact raw REST/WebSocket evidence.
MATTERMOST_APP_PATH: Mattermost Desktop .app bundle path.