A generic, config-driven web scraper that monitors websites for changes and sends email notifications. Define what to scrape using CSS selectors in a JSON config file, and format notifications with Liquid templates.

Designed to run as a cron job. Each rule has its own schedule (cron expression), so the script can be invoked frequently (e.g. every 5 minutes) and each rule runs only when its schedule is due.

Configuration works best with AI agents like OpenClaw, ClaudeCode, OpenCode, or Codex.

Installation

From PyPI

pip install mutimon

This installs the mon command.

From source

git clone https://github.com/jcubic/mutimon.git
cd mutimon
pip install .

This installs the mon command from the local source, including all dependencies.

First run

On the first run, the tool creates ~/.mutimon/ with a skeleton config and example rules (Hacker News + Bitcoin price alerts):

mon
# Config not found at /home/user/.mutimon/config.json
# Creating skeleton configuration in /home/user/.mutimon...
# Done. Edit /home/user/.mutimon/config.json to configure your scraping rules.

Edit ~/.mutimon/config.json with your SMTP credentials and scraping rules, then run again.

Usage

mon                    # process rules; only prints notifications and errors
mon --force            # ignore schedules, run all rules now
mon --force <rule> ... # ignore schedule, run only the named rule(s)
mon --init             # seed state for all rules without sending notifications
mon --init <rule> ...  # seed state for specific rule(s) without sending notifications
mon --reset <rule> ... # delete all stored data (state, last-run, saved email) for the named rule(s)
mon --dry-run          # fetch and display data, bypass schedules, no state changes
mon --save-email       # save email to file instead of sending via SMTP
mon --validate         # validate config against schema and exit
mon --list             # list all rule names (usable with --force <rule>)
mon --ai-guide         # print the AI instruction guide for adding websites
mon --cron             # print a cron entry with resolved path (default: every 5 min)
mon --cron "0 8 * * *" # print a cron entry with a custom schedule
mon --completion bash  # output shell completion script (bash, zsh, or fish)
mon -v, --verbose      # show detailed progress (page fetches, counts, skipped rules)
mon -q, --quiet        # suppress all output including errors

Cron setup

Use --cron to generate a cron entry with the correct resolved path (works with pyenv, virtualenvs, etc.):

mon --cron                  # default: every 5 minutes
mon --cron "0 * * * *"      # custom: every hour

Install it directly:

(crontab -l 2>/dev/null; mon --cron) | crontab -

Each rule's schedule field controls when it actually executes, so running mon frequently (e.g. every 5 minutes) is safe — rules only fire when their cron expression matches.

Seeding state (--init)

Use --init to populate state files without sending any notifications. This is useful when adding new rules — without --init, the first run would send emails for all existing items on the page:

mon --init             # seed state for all rules
mon --init my-rule     # seed state for a specific rule

Like --force, --init bypasses schedules. All items are fetched, validated, and saved to state, but no emails are sent.

Resetting state (--reset)

Use --reset to delete all stored data for one or more rules — the state file, the last-run timestamp, and any saved email. The next run then treats every item as new:

mon --reset my-rule            # clear one rule
mon --reset rule-a rule-b      # clear several rules

At least one rule name is required (there is deliberately no "reset everything" form). Unknown rule names are rejected with an error, and nothing is fetched or sent.

Shell completion

Tab completion is available for bash, zsh, and fish. It completes long options and rule names for --force, --init, and --reset.

Generate the completion script:

mon --completion bash  # or zsh, fish

Install for your shell:

# bash — add to ~/.bashrc
eval "$(mon --completion bash)"

# zsh — add to ~/.zshrc
eval "$(mon --completion zsh)"

# fish — add to ~/.config/fish/config.fish
mon --completion fish | source

File structure

~/.mutimon/
  config.json              # main configuration
  templates/               # Liquid email templates
    hackernews
  data/                    # state files (tracked items per rule)
    hackernews
    .lastrun_hackernews    # last run timestamp for schedule tracking
    emails/                # saved copies of sent emails
  logs/                    # per-rule debug logs (when log: true)
    rule_name.log

Configuration

A JSON Schema is provided for editor autocompletion and validation. Add "$schema": "./config.schema.json" to your config file, or point to the raw URL if hosted on GitHub.

The config is validated against the schema on every run. If the config is invalid, an error email with all validation errors is sent to all rule recipients and the script exits.

The config file (~/.mutimon/config.json) has three sections:

email -- SMTP server

"email": {
  "server": {
    "host": "smtp.example.com",
    "port": 587,
    "password": "your-password",
    "email": "you@example.com"
  }
}

defs -- Reusable scraping definitions and commands

Each definition describes how to fetch and parse data from a website. The optional commands key defines reusable Liquid tag commands (see Commands).

"hackernews": {
  "url": "https://news.ycombinator.com",
  "pagination": { ... },
  "query": {
    "type": "list",
    "selector": "tr.athing.submission",
    "id": { ... },
    "filter": { ... },
    "variables": { ... }
  }
}

Fields:

rules -- What to run

Each rule references a definition and can override params, email recipient, template, etc.

{
  "ref": "hackernews",
  "name": "hackernews",
  "schedule": "0 */6 * * *",
  "subject": "Hacker News: {{count}} new stories",
  "template": "./templates/hackernews",
  "email": "you@example.com"
}

Fields:

Variable extraction

Each variable in query.variables defines how to extract a value from a matched element:

"title": {
  "selector": ".titleline > a",
  "value": {
    "type": "text"
  }
}

Value types

Optional value modifiers

Optional variable fields

Special selectors

Example with all options

"url": {
  "selector": "a.job__title-link",
  "value": {
    "type": "attribute",
    "name": "href",
    "regex": "^(/.*)",
    "prefix": "https://useme.com"
  }
}

This selects the href attribute from a.job__title-link, extracts the path with a regex, then prepends the domain.

Collecting multiple values

When an item contains repeated elements (e.g. skill tags, categories), use collect: true to extract all matches as a list:

"skills": {
  "selector": ".skill-tag",
  "value": { "type": "text" },
  "collect": true
}

This finds all .skill-tag elements inside the item container and returns a list like ["TypeScript", "React", "Node.js"]. Use a loop in the template:

{% for skill in item.skills %}{{ skill }}{% unless forloop.last %}, {% endunless %}{% endfor %}

Self-referencing the container

When the container element itself holds the data you need (e.g. an <a> tag with an href), use :self:

"url": {
  "selector": ":self",
  "value": {
    "type": "attribute",
    "name": "href",
    "prefix": "https://example.com"
  }
}

DOM traversal (find)

For complex pages where the data you need isn't inside the item container, use find to navigate the DOM with chainable traversal steps. This works like jQuery methods — each step takes the result of the previous one as input.

Traversal methods

Steps are applied in order. The result of each step becomes the input for the next.

Example: Wikipedia discussion threads

Wikipedia discussion pages use DiscussionTools markup where thread content is spread across sibling elements rather than nested inside a container. The find chain navigates from the heading to the reply button, collecting everything in between:

"content": {
  "selector": "div.mw-heading2",
  "find": [
    ["until", ".ext-discussiontools-init-replylink-buttons"]
  ],
  "transform": [
    ["remove", ".ext-discussiontools-init-replylink-buttons"],
    ["remove_after", "[data-mw-comment-sig]"]
  ],
  "value": { "type": "html" }
}

This selects the heading container, collects all siblings until the reply button, then transforms the result by removing UI elements and stripping signatures before extracting the raw HTML.

DOM transformation (transform)

Use transform to modify a DOM fragment before extracting its value. Each step mutates a copy of the element (the original is never modified). Combine with find to first locate, then clean up content.

Transform methods

Example: stripping signatures

Wikipedia comments end with signature markup. Use remove_after to cut everything from the signature marker onward:

"transform": [
  ["remove", ".reply-button"],
  ["remove_after", "[data-mw-comment-sig]"]
]

HTML value type and html2text filter

Use type: "html" to extract the raw inner HTML of an element instead of plain text. This preserves the full markup including links, code blocks, and formatting.

To convert HTML to readable plain text in email templates, use the built-in html2text Liquid filter:

{{ item.content | html2text | truncate: 1000 }}

The html2text filter converts HTML to Markdown-like plain text, preserving code blocks and link URLs. The truncate filter can be chained to limit output length.

JSON extraction

Some websites embed structured data as JSON inside <script> tags (e.g. Next.js apps use <script id="__NEXT_DATA__">). When the HTML elements don't contain all the data you need, you can extract it from the embedded JSON instead.

Use parse: "json" combined with a query to navigate the JSON structure using JMESPath expressions.

Basic structure

"locations": {
  "selector": "script#__NEXT_DATA__",
  "value": {
    "type": "text",
    "parse": "json",
    "query": {
      "type": "list",
      "path": "props.pageProps.data.items[?id == `{{id}}`].offers[]",
      "variables": {
        "city": { "path": "displayWorkplace" },
        "url": { "path": "offerAbsoluteUri" }
      }
    }
  }
}

How it works:

1. selector selects the element containing JSON (e.g. a <script> tag) — standard CSS selector
2. type: "text" extracts the text content — same as any other variable
3. parse: "json" parses the text as a JSON object
4. query navigates the parsed JSON and extracts variables:

The path supports Liquid variable interpolation, so you can match JSON entries to the current HTML item. For example, {{id}} is replaced with the item's extracted ID before the JMESPath query runs.

JMESPath syntax

JMESPath is a query language for JSON. Common patterns:

Note: literal values in JMESPath filters use backticks (`), not quotes. See the JMESPath tutorial for full syntax.

Template usage

When query.type is "list", the variable is a list of objects accessible in templates:

{% for loc in item.locations %}
* {{ loc.city }}: {{ loc.url }}
{% endfor %}

When query.type is "single", the variable is a flat object:

{{ item.metadata.author }} - {{ item.metadata.date }}

Works with attributes too

JSON can also appear in HTML attributes. Use type: "attribute" with parse: "json":

"config": {
  "selector": "[data-config]",
  "value": {
    "type": "attribute",
    "name": "data-config",
    "parse": "json",
    "query": {
      "type": "single",
      "variables": {
        "status": { "path": "status" },
        "count": { "path": "meta.count" }
      }
    }
  }
}

Example: Next.js multi-location job offers

Pracuj.pl (a Next.js app) lists job offers with multi-location variants. The HTML card only shows the title, but the city-specific URLs are in __NEXT_DATA__:

"url_list": {
  "selector": "script#__NEXT_DATA__",
  "value": {
    "type": "text",
    "parse": "json",
    "query": {
      "type": "list",
      "path": "props.pageProps.dehydratedState.queries[0].state.data.groupedOffers[?offers[0].partitionId == `{{id}}`].offers[]",
      "variables": {
        "city": { "path": "displayWorkplace" },
        "url": { "path": "offerAbsoluteUri" }
      }
    }
  }
}

The {{id}} in the path is the item's ID extracted from the HTML (data-test-offerid attribute). JMESPath filters the groupedOffers array to find the matching entry, then flattens its offers[] sub-array. Each offer's displayWorkplace and offerAbsoluteUri are extracted as city and url.

Item identity (deduplication)

The id field in the query spec controls how the scraper identifies items it has already seen.

From a variable with regex

"id": {
  "source": "url",
  "regex": ",(\\d+)/$"
}

Takes the url variable value and extracts the ID using a regex. The source can reference either a variable name (from variables) or a param name (from input/params). When using input, params are merged into items before ID extraction, so "source": "symbol" works if symbol is a param.

From an HTML attribute

"id": {
  "type": "attribute",
  "name": "id"
}

Reads the id attribute directly from the matched element (e.g. <tr id="47415919">).

Fallback

If no id spec is provided, the url variable is used as the identity. If there's no url either, a hash of all variables is used.

Field-based deduplication

Sometimes the same listing appears multiple times with different IDs (e.g. a job offer posted under multiple categories gets a different URL slug for each). Use dedupe on the rule to collapse these based on extracted field values:

{
  "ref": "job-site",
  "name": "jobs",
  "dedupe": ["title", "company"],
  "subject": "{{count}} new offer(s)",
  "template": "./templates/jobs",
  "email": "you@example.com"
}

Items with identical values for all listed fields are collapsed — only the first occurrence is kept. This runs after ID-based deduplication and before state comparison.

Filtering

The filter field excludes items based on CSS class:

"filter": {
  "selector": ".job__header-details--date",
  "exclude_class": "job__header-details--closed"
}

This finds .job__header-details--date within each item and skips the item if it has the class job__header-details--closed. Items where the filter selector doesn't match any element are also excluded.

Expected structure

The expect field on a query spec lists CSS selectors that must exist on the page. If any are missing, the scraper sends an error email about HTML structure changes instead of silently producing empty results.

"query": {
  "expect": [".text-center img[alt='Linux']", ".pagination"],
  "selector": "...",
  ...
}

This is checked on the first page only. Useful for detecting when a website redesigns and your selectors break.

Reject selectors

The reject field is the inverse of expect — it lists CSS selectors that indicate the page has no real results. If any selector matches, the page returns 0 items. This is useful for sites that show recommended or unrelated content when there are no actual matches for the search query.

"query": {
  "reject": ["nfj-no-offers-found-header"],
  "selector": "...",
  ...
}

For example, nofluffjobs.com shows a "Brak wyników wyszukiwania" message and recommended jobs when a language has no remote offers. The reject selector detects the no-results element and prevents those recommendations from being treated as real results.

Multiple inputs

The input field allows a single rule to scrape multiple pages with different parameters and combine the results into one email. This is useful for monitoring multiple items on the same website (e.g. multiple stock symbols).

input can be a single object or an array:

{
  "ref": "bankier",
  "name": "akcje",
  "subject": "[bankier.pl] Zmiany Akcji",
  "template": "./templates/bankier",
  "email": "you@example.com",
  "input": [
    { "params": { "symbol": "BIOMAXIMA" }, "validator": { "test": "{{price}} > 10" } },
    { "params": { "symbol": "AGORA" }, "validator": { "test": "{{price}} > 9.5" } },
    { "params": { "symbol": "ASSECOPOL" } },
    { "params": { "symbol": "POLTREG" } }
  ]
}

Each entry fetches the URL with its own params. If input is omitted, the rule's params field is used directly (backward compatible).

Params from each input entry are merged into the extracted items, so they're available in templates (e.g. {{symbol}}).

Input expansion with each

When multiple inputs share the same structure and only differ by one parameter, use each to avoid repeating the same object:

"input": {
  "each": { "var": "subreddit", "values": ["Python", "JavaScript", "scheme"] },
  "params": { "feed_url": "https://www.reddit.com/r/{{subreddit}}/new.rss" },
  "validator": { "@id": "hiring-posts" }
}

This expands into three input entries, one per value, each with its own params where {{subreddit}} is replaced. The validator (or track) is shared across all entries.

The each.values array can also contain objects, accessed via dot notation:

"input": {
  "each": {
    "var": "data",
    "values": [
      { "category": "electronics", "type": "phones" },
      { "category": "computers", "type": "laptops" }
    ]
  },
  "params": { "url": "https://example.com/{{data.category}}/type/{{data.type}}" }
}

Grouped items (flatten)

By default, when a rule has multiple input entries, all fetched items are merged into a single flat list. Set "flatten": false on the rule to keep items grouped by input entry — items becomes a nested list (list of lists), one group per input.

{
  "ref": "wiki",
  "name": "wiki-monitoring",
  "flatten": false,
  "input": [
    { "params": { "page": "SEO" } },
    { "params": { "page": "UKEN" } }
  ],
  ...
}

In the template, iterate over groups and items within each group:

{% for group in items %}
{% assign first = group | first %}
============================================================
{{ first._input.page }}
============================================================

{% for item in group %}
{{ item.title }}
{% endfor %}

{{ first._search_url }}
{% endfor %}

Each item in grouped mode gets additional metadata:

{{ count }} is the total number of items across all groups. {{ search_url }} is the URL of the first input entry.

When flatten is true (default) or there is only one input entry, the template works as usual with a flat items list.

Empty groups are automatically filtered out — if an input produces zero items, it won't appear in the template.

Aggregating multiple sources into one email (ref per input)

To combine results from different definitions into a single email, give each input entry its own ref (overriding the rule's default) plus an optional friendly label. Each item gets _label for use in the template.

{
  "name": "python-jobs",
  "schedule": "0 9 * * *",
  "subject": "[Jobs] {{count}} new Python offer(s)",
  "template": "./templates/jobs-aggregated",
  "email": "you@example.com",
  "flatten": false,
  "dedupe": ["title", "company"],
  "input": [
    {
      "ref": "justjoin",
      "label": "justjoin.it",
      "params": {"keyword": "Python"},
      "validator": {"@id": "job-board-python"}
    },
    {
      "ref": "pracuj",
      "label": "pracuj.pl",
      "params": {"url": "https://..."}
    },
    {
      "ref": "nofluffjobs",
      "label": "nofluffjobs.com",
      "params": {"language": "Python"},
      "validator": {"@id": "job-board-python"}
    }
  ]
}

Template using _label:

{% for group in items %}
=== {{ group[0]._label }} ({{ group.size }}) ===
{% for item in group %}
{{ forloop.index }}. {{ item.title }} — {{ item.company }}
{% endfor %}
{% endfor %}

When inputs use different refs, IDs are automatically namespaced as <ref>:<id> to prevent state collisions. dedupe still applies across all sources, so the same listing appearing on multiple sites is collapsed.

The rule's top-level ref becomes optional in this mode — either provide it as a fallback default, or omit it and require every input to specify its own.

Validators

Each input entry can have a validator object that filters extracted items. The validator supports two condition types. If both are present, both must pass (AND logic).

test -- Expression

A general-purpose expression evaluated by expression-py. Supports arithmetic, comparisons, regex matching with =~, boolean operators, array operations, and Liquid variable placeholders. Item variables are available directly by name (no {{ }} needed); use Liquid placeholders only when you need a Liquid filter or custom command.

"validator": {
  "test": "price > 9.5"
}

Supported operations:

Empty arrays are falsy, so skills & ["AI", "ML"] directly evaluates to true/false: true if skills contains "AI" or "ML", false otherwise. See expression-py docs for the full operator list and precedence.

You can still use {{ }} placeholders when you need Liquid pre-processing (e.g. filters or custom commands):

{ "test": "{{ date | date: \"%Y%m%d\" }} == {{ \"now\" | date: \"%Y%m%d\" }}" }
{ "test": "{% fresh date 604800 %}" }

match -- List membership match

Checks whether a variable's value is in (or not in) a list of strings. For regex matching, use test with the =~ operator instead.

"validator": {
  "match": {
    "var": "skills",
    "exclude": ["Angular", "C#", ".NET", "Java"]
  }
}

Match condition fields:

When the variable is a list (from collect: true), each element is compared as an exact match — "Java" matches the skill "Java" but not "JavaScript". For plain string values, substring matching is used by default; set strict: true for exact equality.

match can also be an array of match objects (AND logic — all must pass):

"validator": {
  "match": [
    { "var": "skills", "include": ["Python"] },
    { "var": "skills", "exclude": ["Angular", "C#"] }
  ]
}

Combined example

Both conditions must pass (AND logic within a single object):

"validator": {
  "test": "price > 80 && company =~ /Asseco/",
  "match": {
    "var": "skills",
    "exclude": ["Java", "C#"]
  }
}

Array of validators (OR logic)

The validator can also be an array. The item is included if any validator in the array passes. This is useful for defining price thresholds or notification steps:

"validator": [
  { "test": "{{price}} > 8" },
  { "test": "{{price}} > 9" },
  { "test": "{{price}} > 9.5" }
]

Each entry in the array is a full validator object that can use test, match, or both.

Required validators (require)

In a validator array, set "require": true to make a validator mandatory. Required validators must ALL pass (AND logic), while the remaining validators use OR logic (at least one must pass). If only required validators exist, the OR check is skipped.

This is useful for combining a baseline filter with threshold alerts:

"validator": [
  { "require": true, "test": "{{score_num}} > 50" },
  { "test": "{{price}} > 75000" },
  { "test": "{{price}} > 80000" },
  { "test": "{{price}} > 100000" }
]

The require validator acts as a gate — items must pass it before the OR thresholds are even considered.

Reusable validators (@id)

Define shared validators in defs.validators and reference them by name using {"@id": "name"}. This eliminates duplication when multiple rules use the same filter:

"defs": {
  "validators": {
    "job-board": {
      "require": true,
      "match": [
        {"var": "title", "exclude": ["Angular", "C#", ".NET"]},
        {"var": "skills", "exclude": ["Angular", "C#", ".NET", "Java"]}
      ]
    }
  }
}

Then reference it in rules:

"input": {
  "validator": {"@id": "job-board"}
}

@id references work anywhere a validator is expected — as a standalone validator, or as an element in a validator array:

"validator": [
  {"@id": "job-board"},
  { "require": true, "test": "!(salary =~ /Undisclosed/)" }
]

Commands

Commands are reusable Liquid tags defined in defs.commands. Each command becomes a custom {% tag %} that can be used in validator test and match expressions, replacing verbose Liquid expressions with short, readable tags.

Defining commands

Commands are defined in the commands key under defs:

"defs": {
  "commands": {
    "fresh": {
      "args": ["field", "seconds"],
      "template": "{{ field | date: \"%s\" }} > {{ \"now\" | date: \"%s\" | minus: seconds }}"
    },
    "today": {
      "args": ["field"],
      "template": "{{ field | date: \"%Y%m%d\" }} == {{ \"now\" | date: \"%Y%m%d\" }}"
    }
  },
  ...
}

Using commands

Use commands as {% name arg1 arg2 %} in any validator test or match expression:

"validator": {
  "test": "{% fresh date 604800 %}"
}

This is equivalent to writing the full Liquid expression:

"test": "{{ date | date: \"%s\" }} > {{ \"now\" | date: \"%s\" | minus: 604800 }}"

Arguments are matched positionally to the args list in the command definition. Word arguments (like date) are resolved as variables from the item context. Numeric arguments (like 604800) are passed as literal values.

Built-in commands in skeleton

The skeleton config includes two commands:

{% fresh <field> <seconds> %} — checks whether a date field is newer than a given number of seconds. Useful for filtering stale items from feeds that return non-deterministic results:

"input": {
  "validator": {
    "test": "{% fresh date 604800 %}"
  }
}

This filters out any items where the date field is older than 7 days (604800 seconds).

{% today <field> %} — checks whether a date field matches today's date:

"input": {
  "validator": {
    "require": true,
    "test": "{% today date %}"
  }
}

Filters

Custom Liquid filters defined in defs.filters. Each key becomes a filter usable as {{ value | name }} in templates. Filters are defined using standard Liquid filter expression syntax — the input value is piped through the expression chain.

Defining filters

"defs": {
  "filters": {
    "clean": "replace_regex: '\\s+', ' ' | strip"
  }
}

The expression uses standard Liquid pipe syntax. Built-in Liquid filters (strip, downcase, replace, etc.) and the additional replace_regex filter are available:

Filters can be chained with | — the output of one becomes the input of the next. Custom filters can also reference other custom filters defined earlier.

Using filters

Use filters with the standard Liquid pipe syntax in any template:

{{ item.snippet | clean }}

The clean filter above collapses all whitespace (newlines, tabs, spaces) into a single space and trims leading/trailing whitespace.

Pagination

Two pagination types are supported:

next_link -- Follow a "next" link

For sites with a single "More" or "Next" link (e.g. Hacker News):

"pagination": {
  "type": "next_link",
  "selector": "a.morelink",
  "base_url": "https://news.ycombinator.com/",
  "max_pages": 2
}

numbered -- Follow numbered page buttons

For sites with numbered pagination (e.g. useme.com):

"pagination": {
  "type": "numbered",
  "selector": ".pagination .pagination__page",
  "active_class": "pagination__page--active",
  "base_url": "https://useme.com/pl/jobs/",
  "max_pages": 5
}

Finds the active page button and follows the link of the next one.

Common fields

Schedule

Each rule can have a schedule field with a standard cron expression or an array of expressions (any match triggers the rule). The script is designed to be invoked frequently (e.g. every 5 minutes via system cron), and it decides internally which rules are due based on their schedule.

The schedule uses croniter to parse standard 5-field cron expressions:

 ┌───────────── minute (0-59)
 │ ┌───────────── hour (0-23)
 │ │ ┌───────────── day of month (1-31)
 │ │ │ ┌───────────── month (1-12)
 │ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
 │ │ │ │ │
 * * * * *

Examples

Array of schedules

When a single cron expression can't cover your needs, use an array. The rule runs if any expression matches:

"schedule": ["0,30 9 * * *", "0 16 * * *"]

This runs at 9:00, 9:30, and 16:00 — something not expressible in a single 5-field cron string.

How it works

The script is designed to be invoked periodically by system cron (e.g. every 5 minutes or every hour). On each invocation:

1. The current time is truncated to the start of the minute (e.g. 14:03:27 becomes 14:03:00)
2. Each rule's cron expression is checked against that time using croniter.match
3. If it matches and the rule hasn't already run in this minute window, it executes
4. After a successful run, a timestamp is saved to ~/.mutimon/data/.lastrun_<rule_name> to prevent duplicate runs if the script is triggered again within the same minute
5. If no schedule is set, the rule runs every time
6. Use --force to bypass all schedules

Email templates

Templates use Liquid syntax via python-liquid. The following variables are available:

Liquid supports conditionals, filters, and logic — see the Liquid docs.

Example template

Hacker News - New Stories
Checked at: {{ now }}

Number of new stories: {{ count }}
============================================================
{% for item in items %}

{{ item.rank }} {{ item.title }}
     Score: {{ item.score }} point{% if item.score != 1 %}s{% endif %} | {{ item.age }}
     URL:   {{ item.url }}
     HN:    {{ item.comments_url }}
{% endfor %}

============================================================

The subject field in a rule is also a Liquid template with access to the same variables.

How it works

1. On each run, all rules in the config are processed sequentially
2. For each rule, the scraper fetches the URL (with pagination) and extracts items using CSS selectors
3. For parse: "money", the page language is detected from <html lang> or the Content-Language header, and used for locale-aware currency parsing via babel
4. Items are compared against the saved state in ~/.mutimon/data/<rule_name>
5. New items, or items that crossed a validator threshold (previously failed, now pass), trigger an email notification
6. ALL items are saved in state with a _valid flag (or _state index for track mode), so threshold crossings are detected on subsequent runs

Threshold crossing detection

When a rule has validators, the scraper tracks whether each item passed or failed on the previous run. This enables re-notifications when a value crosses a threshold boundary:

1. Price rises to $75k → validator >= 75000 passes → notify, save _valid: true
2. Price drops to $72k → validator fails → no notification, save _valid: false
3. Price rises to $76k → validator passes, previous _valid was false → notify again
4. Price stays at $76k → validator passes, previous _valid was true → no notification

This works for both upward thresholds (>=) and downward thresholds (<=). The state file stores all fetched items (not just those passing the validator) with a _valid boolean.

State-machine tracking (track)

For more granular threshold monitoring, use track instead of validator on an input entry. While validator stores a single pass/fail boolean, track implements a state machine that tracks which threshold an item is in and notifies on every state transition.

track and validator are mutually exclusive on the same input entry.

Configuration

"input": {
  "params": { "symbol": "ASSECOPOL" },
  "track": {
    "value": "{{price}}",
    "states": [
      { "test": "{{price}} > 200", "name": "above 200 zł" },
      { "test": "{{price}} > 190", "name": "above 190 zł" },
      { "test": "{{price}} > 180", "name": "above 180 zł" },
      { "test": "{{price}} <= 180", "silent": true }
    ]
  }
}

How it works

States are evaluated top-down — the first matching test expression determines the item's current state (by index). On each run:

1. New item — notify if the current state is not silent
2. State changed (index differs from previous run) — notify if the new state is not silent
3. State unchanged — no notification

Example: stock price monitoring

"track": {
  "value": "{{price}}",
  "states": [
    { "test": "{{price}} > 200", "name": "above 200 zł" },
    { "test": "{{price}} > 190", "name": "above 190 zł" },
    { "test": "{{price}} > 180", "name": "above 180 zł" },
    { "test": "{{price}} <= 180", "silent": true }
  ]
}

Template variables

In track mode, the following variables are available in templates:

When to use track vs validator

• validator — binary filter: include/exclude items. Good for "notify me about new Hacker News posts with score > 100" or "exclude job offers with Angular".
• track — state machine: notify on every threshold crossing. Good for "notify me each time ASSECOPOL crosses above 190 zł, and again when it crosses above 200 zł".

Health checks

Definitions without a query section act as health checks. Instead of parsing HTML/XML/JSON, Mutimon makes an HTTP request and returns a single item with response metadata. This is useful for monitoring website uptime.

HTTP response variables

When query is omitted, the returned item has an http object with the following fields:

The item's id is set to the requested URL automatically.

Example: monitor website uptime

Definition (reusable for any URL):

{
  "defs": {
    "health": {
      "url": "{{ url }}"
    }
  }
}

Rule with track for up/down state notifications:

{
  "name": "my-sites",
  "ref": "health",
  "schedule": "*/15 * * * *",
  "input": [
    { "params": { "url": "https://example.com/" } },
    { "params": { "url": "https://api.example.com/" } }
  ],
  "track": [
    { "name": "down", "test": "({{ http.code }} >= 400) | ({{ http.code }} == 0)" },
    { "name": "up", "test": "{{ http.code }} >= 200", "silent": true }
  ],
  "subject": "Site down: example.com",
  "template": "./templates/health",
  "email": "you@example.com"
}

With "silent": true on the "up" state, you only get notified when a site goes down. Remove "silent" to also get notified when it recovers.

Example template (~/.mutimon/templates/health):

Health check at {{ now }}
============================================================
{% for item in items %}
{{ item.url }}
  Status: {{ item._state_name }} (HTTP {{ http.code }})
  Response time: {{ http.response_time }}s{% if http.error %}
  Error: {{ http.error }}{% endif %}
{% endfor %}

Validating headers

Use match with a value Liquid template to check response headers:

{
  "validator": {
    "match": {
      "value": "{{ http.headers['content-type'] }}",
      "regex": "^application/json"
    }
  }
}

Header names are always lowercase in the http.headers dict, regardless of how the server returns them.

Definition-level validator and track

Definitions can include a validator and/or track that act as defaults for all rules referencing that definition. This avoids repeating the same filter across multiple rules or input entries.

Validator inheritance

A definition-level validator is AND-merged with input-level validators. The def validator becomes a require: true gate — items must pass it before the input-level validators are considered.

"defs": {
  "atom": {
    "url": "{{feed_url}}",
    "format": "xml",
    "query": { ... },
    "validator": { "test": "{% fresh date 604800 %}" }
  }
}

Any rule using the atom def automatically filters out items older than 7 days. If a rule adds its own validator (e.g. a title regex), both must pass — freshness AND the title match.

When an input entry has its own track, the def-level validator is ignored (since track and validator are mutually exclusive).

Track inheritance

A definition-level track provides a default state machine for all rules. Input-level track overrides the def-level track entirely (no merging).

"defs": {
  "health": {
    "url": "{{ url }}",
    "track": {
      "states": [
        { "name": "down", "test": "({{ http.code }} >= 400) | ({{ http.code }} == 0)" },
        { "name": "up", "test": "{{ http.code }} >= 200", "silent": true }
      ]
    }
  }
}

Rules using the health def get the default up/down tracking. An input entry can override with a custom track (e.g. a CORS proxy that returns 400 normally):

"input": [
  { "params": { "url": "https://example.com/" } },
  {
    "params": { "url": "https://proxy.example.com/" },
    "track": {
      "states": [
        { "name": "down", "test": "({{ http.code }} >= 500) | ({{ http.code }} == 0)" },
        { "name": "up", "test": "{{ http.code }} > 0", "silent": true }
      ]
    }
  }
]

The first entry uses the def's default track. The second overrides it with a custom threshold.

When an input entry has its own validator, the def-level track is ignored.

Error handling

The scraper sends error emails for four types of failures. The error email function (send_error_email) uses only Python's standard library (no third-party deps), so it works even when the error is caused by a missing dependency.

Error emails are sent to all unique recipient addresses found across all rules in the config.

Examples

The skeleton/ directory contains ready-to-use examples that are copied to ~/.mutimon/ on first run.

Hacker News — New stories

Monitors the Hacker News front page for new stories. Uses pagination to fetch 2 pages (60 stories), sibling element extraction for scores, and data-test attribute-based IDs.

Files: skeleton/config.json (hackernews def + rule), skeleton/templates/hackernews

Bitcoin price alerts — CoinMarketCap

Monitors Bitcoin price on CoinMarketCap with threshold-based alerts. Demonstrates:

• Price going up: notify when Bitcoin crosses above $75k, $80k, $90k, $100k
• Price going down: notify when Bitcoin drops below $60k, $50k, $40k
• Threshold crossing detection: if price rises above $75k (notify), drops to $72k (no notify), then rises back above $75k (notify again)
• Locale-aware money parsing: $70,528.40 is correctly parsed as 70528.40 using parse: "money" (US English format detected from <html lang="en">)
• Structure validation: expect field checks that [data-test='text-cdp-price-display'] exists on the page

Files: skeleton/config.json (coinmarketcap def + rule), skeleton/templates/coinmarketcap

The bitcoin rule uses two input entries — one for upward thresholds (>=), one for downward thresholds (<=):

"input": [
  {
    "params": { "coin": "bitcoin" },
    "validator": [
      { "test": "{{price}} >= 75000" },
      { "test": "{{price}} >= 80000" },
      { "test": "{{price}} >= 100000" }
    ]
  },
  {
    "params": { "coin": "bitcoin" },
    "validator": [
      { "test": "{{price}} <= 60000" },
      { "test": "{{price}} <= 50000" }
    ]
  }
]

Tip: For more granular notifications (e.g. notify each time the price crosses a specific level, not just when it re-enters a "passing" state), use track instead of validator.

Stock price tracking — State machine

Monitors stock prices with per-threshold notifications using track. Unlike the Bitcoin example which uses validator (binary pass/fail), track notifies on every state transition — e.g. when a stock crosses above 190 zł, then again when it crosses 200 zł.

"input": [
  {
    "params": { "symbol": "ASSECOPOL" },
    "track": {
      "value": "{{price}}",
      "states": [
        { "test": "{{price}} > 200", "name": "above 200 zł" },
        { "test": "{{price}} > 190", "name": "above 190 zł" },
        { "test": "{{price}} > 180", "name": "above 180 zł" },
        { "test": "{{price}} <= 180", "silent": true }
      ]
    }
  }
]

The silent state at the bottom acts as a "reset" — when the price drops below 180, no notification is sent, but the state is saved. When the price rises back above 180, it's detected as a state change and triggers a new notification.

Reddit subreddit — RSS/Atom feed

Monitors a Reddit subreddit via its Atom feed (Reddit serves .rss URLs as Atom XML). Demonstrates:

• XML format: format: "xml" switches from HTML to XML parsing, so CSS selectors target XML elements (entry, title, link) instead of HTML
• Custom User-Agent: Reddit blocks default scrapers, so a Liferea RSS reader User-Agent is used
• Parameterized subreddit: the subreddit param lets the same definition monitor any subreddit
• Atom-specific selectors: entry for items, link[href] for URLs (Atom uses <link href="..."/> instead of <link>text</link>)

Files: skeleton/config.json (reddit-atom def + rule), skeleton/templates/reddit

"reddit-atom": {
  "params": ["subreddit"],
  "format": "xml",
  "userAgent": "Liferea/1.15.6 (Linux; https://lzone.de/liferea/) AppleWebKit (KHTML, like Gecko)",
  "url": "https://www.reddit.com/r/{{subreddit}}.rss",
  "query": {
    "type": "list",
    "selector": "entry",
    "id": { "source": "entry_id" },
    "variables": {
      "title":    { "selector": "title", "value": { "type": "text" } },
      "url":      { "selector": "link", "value": { "type": "attribute", "name": "href" } },
      "entry_id": { "selector": "id", "value": { "type": "text" } },
      "date":     { "selector": "updated", "value": { "type": "text" }, "default": "" },
      "author":   { "selector": "author name", "value": { "type": "text" }, "default": "" }
    }
  }
}

Multiple Reddit subreddits — Hiring posts with each

Monitors multiple subreddits for posts about hiring Python or JavaScript developers. Demonstrates:

• each expansion: a single input object expands into multiple fetches, one per subreddit — no need to repeat the same params/validator for each
• Reusable validator: defs.validators defines a named validator referenced by @id across all expanded entries
• Combined results: all matching posts from all subreddits land in one email

Definition: uses the same reddit-atom def from the previous example.

Reusable validator:

"validators": {
  "reddit-hiring": [
    { "test": "{% fresh date 604800 %}", "require": true },
    { "test": "title =~ /\\b(hiring|hire|looking for)\\b.*(Python|JavaScript)/i" }
  ]
}

Rule:

{
  "ref": "reddit-atom",
  "name": "reddit-hiring-dev",
  "schedule": "0 */4 * * *",
  "subject": "[Reddit] {{count}} new hiring post(s)",
  "template": "./templates/reddit",
  "email": "you@example.com",
  "input": {
    "each": { "var": "subreddit", "values": ["Python", "JavaScript"] },
    "params": { "subreddit": "{{subreddit}}" },
    "validator": { "@id": "reddit-hiring" }
  }
}

Files: skeleton/config.json (reddit-atom def + rule), skeleton/templates/reddit

Configuring with AI

Mutimon ships with an AI instruction file that teaches any AI assistant how to add websites. Get its path with:

mon --ai-guide

Use it with Claude Code in batch mode:

claude -p "$(mon --ai-guide) Add https://github.com/trending to mutimon. Extract repo name, description, URL, language, and stars. Email me daily at 8am at user@example.com."

Or with any AI assistant — just paste the output of mon --ai-guide as context along with your request.

Example prompts

Monitor a website for new content

Add a rule to monitor Hacker News (https://news.ycombinator.com) for new stories. Extract the title, URL, score, and age. Send me an email every 6 hours at user@example.com with the new stories. Read the AI guide with mon --ai-guide for config format reference.

Price alerts with thresholds

Add Bitcoin price monitoring using https://coinmarketcap.com/currencies/bitcoin/. Notify me when the price crosses above $75,000 or drops below $60,000. Check every 4 hours. Send alerts to user@example.com. Read the AI guide with mon --ai-guide for config format reference.

Stock price tracking with state machine

Monitor ASSECOPOL stock on https://www.bankier.pl/inwestowanie/profile/quote.html?symbol=ASSECOPOL. Use track (not validator) to notify me each time the price crosses above 180, 190, or 200 zł. Add a silent state for below 180 so I only get notified when it rises back above thresholds. Check twice daily during market hours. Read the AI guide with mon --ai-guide for config format reference.

Monitor for a feature release

Monitor https://soloterm.com/download for Linux support. The page currently shows "Coming soon" next to Linux. Notify me when that label disappears (use the match validator with exist: false). Also add an expect check so I get an error email if the page structure changes. Read the AI guide with mon --ai-guide for config format reference.

Monitor an RSS/Atom feed

Add a rule to monitor the r/scheme subreddit via its RSS feed at https://www.reddit.com/r/scheme.rss. Reddit serves Atom XML, so use format "xml" and a Liferea User-Agent. Extract the title, URL, author, and date. Check every 6 hours and email me at user@example.com. Read the AI guide with mon --ai-guide for config format reference.

Filter content with regex

Add a rule to monitor Hacker News for "Ask HN" posts only. Use the existing hackernews definition with a match validator that filters titles starting with "Ask HN". Read the AI guide with mon --ai-guide for config format reference.

Filter RSS feed with a command

Add a rule to monitor the r/scheme subreddit via its Atom feed. Use the {% fresh date 604800 %} command to filter out posts older than 7 days, since Reddit's feed sometimes returns stale posts. Read the AI guide with mon --ai-guide for config format reference.

Monitor multiple subreddits with each

Monitor r/Python and r/JavaScript subreddits for posts about hiring developers. Use the each input expansion to avoid duplicating the input entry for each subreddit. Filter titles containing "hiring", "hire", or "looking for" combined with "Python" or "JavaScript". Use a reusable validator in defs.validators. Check every 4 hours. Read the AI guide with mon --ai-guide for config format reference.

Extract data from Next.js JSON (embedded JSON)

Add a rule to monitor job offers on https://it.pracuj.pl. The site is a Next.js app — some data (like city-specific URLs for multi-location offers) is only in the <script id="__NEXT_DATA__"> JSON, not in the HTML. Use parse: "json" with a JMESPath query to extract city and URL from the embedded JSON. Read the AI guide with mon --ai-guide for config format reference.

Monitor website uptime (health check)

Add a health check rule to monitor https://example.com and https://api.example.com. Use a definition without query to get HTTP response metadata. Use track states to notify when a site goes down (status >= 400 or connection error) and stay silent when it's up. Check every 15 minutes. Read the AI guide with mon --ai-guide for config format reference.

Extract content from complex page structure

Add a rule to monitor a Wikipedia discussion page for new threads. The page uses MediaWiki DiscussionTools where thread content is spread across sibling elements, not nested in a container. Use find with until to collect siblings between headings and reply buttons, transform to strip signatures and UI elements, and type: "html" with the html2text Liquid filter to convert the content to plain text in the template. Read the AI guide with mon --ai-guide for config format reference.

Acknowledge

The logo was created as a combination of clipart from OpenClipart:

• Time Attendance by petr.gajdusek
• Notification logo by laftello
• Internet Graphic Chart 02 by cset_paper

It also uses Lovelo font.

Name Origin

Mutimon is a concise Latin portmanteau formed from mutare (“to change”) + monere (“to warn / monitor”).

License

Copyright (C) 2026 Jakub T. Jankiewicz
Released under GPL-3.0 license