Check whether Telegram is logged in, and as whom.

Reports both sessions: the watcher's (the one that must be logged in for monitoring to work) and this server's (needed only for the read tools). Call this before anything else if alerts or reads are failing.

Save the Telegram app credentials needed before any login.

The user gets these from https://my.telegram.org under "API development tools" — they identify the application, not the account, and are not secret in the way a login code is. Stored owner-only in /.env.

Args: api_id: numeric App api_id from my.telegram.org. api_hash: 32-character App api_hash from my.telegram.org.

Start logging in: ask Telegram to send a login code.

Telegram delivers the code in the Telegram app itself if the user is signed in elsewhere, otherwise by SMS. Follow with login_submit_code.

Ask the user for their phone number rather than guessing it.

Args: phone: phone number in international format, e.g. +14155550123. session: which session to log in — 'watcher' (default, the one monitoring needs) or 'mcp' (for this server's read tools).

Finish logging in with the code Telegram sent.

If the account has two-factor authentication, this returns an error asking for the password; call it again with both.

Args: code: the login code the user received. password: two-factor password, only if the account has one. session: the session being logged in; must match login_request_code.

List your Telegram chats/channels, most recently active first.

Use this to find the numeric chat ids you need for alert rule scopes.

Args: limit: max number of dialogs to return. unread_only: only return dialogs with unread messages. include_archived: include archived chats (excluded by default).

Read the most recent messages from a chat/channel.

Args: chat_id: numeric dialog id, as returned by list_dialogs. limit: max number of messages to return (most recent first).

Search your Telegram messages for a keyword.

Searches history, unlike alert rules which only see new messages.

Args: query: text to search for. chat_id: restrict search to one chat; omit to search all chats. limit: max number of results.

Summarize unread chats: for each, the unread count and the last few unread message previews.

Args: limit_per_chat: how many recent messages to preview per chat. max_chats: max number of unread chats to include.

Test a candidate rule against real message history before creating it.

Shows what the rule would have matched, so the user can judge whether it is too broad or too narrow while they are still writing it. Creates nothing. Use this during setup, before add_alert_rule, and show the user the samples — a rule that looks sensible in the abstract often turns out to match mostly noise.

The matched samples are also the right input for testing draft criteria: read them and decide which ones a criterion should keep, then tell the user which would have been surfaced and which filtered out.

Args: pattern: the candidate pattern. match_type: 'substring', 'word', or 'regex'. case_sensitive: match case exactly. chat_ids: restrict to these chats; omit to search everywhere. search_hint: a plain word to search Telegram for when match_type is 'regex' — Telegram cannot search by regex, so this narrows what gets scanned locally. Required for an unscoped regex preview. limit: max samples to return. scan: how many messages to pull and test.

Create an alert rule. The watcher picks it up within a few seconds — no restart needed. Rules only match messages that arrive after they are created; use search_messages to look backwards.

Args: name: unique label for the rule, used in alerts and notifications. pattern: what to look for. match_type: 'substring' (default), 'word' (whole-word only), or 'regex'. case_sensitive: match case exactly (default: case-insensitive). chat_ids: only watch these chats; omit to watch every chat. exclude_chat_ids: never match in these chats; applied before chat_ids. include_outgoing: also match messages you send (default: incoming only). notify: fire a macOS desktop notification on match.

List alert rules with their hit counts.

Args: include_disabled: include rules that are currently turned off.

Turn an alert rule on or off without deleting it or its alerts.

Args: rule_id: id from list_alert_rules. enabled: True to resume matching, False to pause.

Delete an alert rule and every alert it produced. Irreversible — prefer set_alert_rule_enabled(rule_id, False) to just pause it.

Args: rule_id: id from list_alert_rules.

List recorded alerts, newest first.

By default this hides alerts the judge ruled irrelevant — that filtering is the whole point of the judge. Pass include_irrelevant=True to audit what it rejected and why (each one keeps its reasoning).

Args: limit: max number of alerts to return. unacked_only: only alerts you haven't acknowledged yet (default). rule_id: restrict to one prefilter rule. chat_id: restrict to one chat. since_hours: only alerts matched within this many hours. verdict: exact verdict — relevant, irrelevant, pending, skipped, error. min_severity: lowest severity to include (low, medium, high, critical). include_irrelevant: include alerts the judge rejected.

Mark alerts as acknowledged so they drop out of the default list_alerts view. Pass exactly one of the three selectors.

Args: alert_ids: specific alert ids to acknowledge. rule_id: acknowledge every unacked alert from this rule. all_alerts: acknowledge every unacked alert.

Add a natural-language criterion the judge uses to decide whether a prefiltered post actually matters. The watcher picks it up on the next judged alert — no restart needed.

Rules decide what gets looked at; criteria decide what gets surfaced. Write a criterion the way you'd brief someone doing the triage for you: say what qualifies and what doesn't. "A specific open remote backend role that names the company" beats "jobs".

Args: name: short unique label, shown on matching alerts. description: what qualifies, in plain language.

List the judging criteria and how often each has matched.

Args: include_disabled: include criteria that are currently turned off.

Turn a criterion on or off without deleting it.

Args: criterion_id: id from list_criteria. enabled: True to resume judging against it, False to pause.

Delete a criterion. Alerts already judged against it keep their verdicts. Prefer set_criterion_enabled to pause one.

Args: criterion_id: id from list_criteria.

Check whether the watcher daemon is running and what it has seen.

Reports liveness from the daemon's heartbeat, so a 'stale' result means watcher.py has stopped and no new alerts are being recorded.