New advertisers: 50% off your first month with code FIRSTMONTHSee slots
toolpath avatar

chatter

toolpath/chatter

Setup, machine-connection repair, alert authoring, and history reports for the Chatter CNC monitor.

GitHub stars
5
View on GitHub

What it does

  • Adds /set-up-chatter, /debug-machine-connection, /alert-query, and /machine-report skills for Chatter shops
  • Guides installation on a computer with Docker or a Raspberry Pi card, then Admin, machines, and users
  • Diagnoses machines that show Offline, Connecting, or no program files, and explains the fix
  • Turns plain-language alert requests into simple rules or custom MetricsQL queries tested on real history

Set up Chatter, fix a machine that does not connect, write alert rules, and report on machine history.

Add marketplace

/plugin marketplace add toolpath/chatter

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install chatter@toolpath-chatter

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Write a Chatter alert rule

Chatter checks each alert rule on one machine every 15 seconds (docs: https://toolpath.github.io/chatter/guide/alerts). You write the rule. The user adds it in the app, because only an Admin can save rules.

Connect to Chatter

Chatter has an HTTP API that takes HTTP Basic logins (docs: https://toolpath.github.io/chatter/api/). Ask the user to set these in the terminal, so the password does not go in the chat:

export CHATTER_URL=http://<chatter address>:3001
export CHATTER_USERNAME=<username>
read -rs CHATTER_PASSWORD && export CHATTER_PASSWORD

Each request: curl -s -u "$CHATTER_USERNAME:$CHATTER_PASSWORD" "$CHATTER_URL/api/...". A Viewer account can do steps 1 to 3. Step 4 needs an Admin account. Stop after the first 401 and ask the user: after 10 wrong passwords, the address must wait 15 minutes.

1. Get the check in plain words

Get from the user: the machine (or machines), what to check, the limit, how long it must stay true, and the level (warning or critical). Find the machine id with GET /api/machines.

2. Use a simple rule when one fits

A simple rule needs no query. It checks one of: spindle-speed, spindle-load or part-count (above or below a limit), or not-connected, in-alarm or emergency-stop (a state). If the check is one of these, give the user the simple rule and go to step 5.

3. Write the query

Write MetricsQL, the query language of VictoriaMetrics. Put {machine="$machine"} after each metric name: Chatter puts the machine id there, and it does not save a query without $machine.

MetricWhat it isHistory value
chatter_connectedChatter can reach the machine (1 or 0)connected
chatter_runningA program runs (1 or 0)running
chatter_alarmThe machine has an alarm (1 or 0)alarm
chatter_emergencyThe emergency stop is pushed (1 or 0)emergency
chatter_spindle_speedRPMspindle-speed
chatter_spindle_load%spindle-load
chatter_feedratethe machine's unitfeedrate
chatter_part_countpartspart-count
chatter_part_goalpartspart-goal
chatter_tool_numbertool numbertool-number

How a query alerts: the check is true when the query gives a result. A compare such as > 90 keeps a value only while it is true. Join two checks with and, or or unless. For a time, use avg_over_time(...[10m]), max_over_time, min_over_time, or increase(...[30m]) for a counter. A query that looks back with [10m] often needs 0 minutes in the rule. More examples: https://toolpath.github.io/chatter/guide/custom-alert-queries

Make sure that the machine sends each value in the query: GET /api/machine/<id>/history/<history value>?range=-1d. An empty data list means that the machine does not send it, so the query never gives a result. Tell the user, and find another value.

4. Test the query

With an Admin login, run the query one time:

curl -s -u "$CHATTER_USERNAME:$CHATTER_PASSWORD" -H 'Content-Type: application/json' \
  -d '{"machineId":"<id>","query":"<query>"}' "$CHATTER_URL/api/alert-rules/test"

{ ok: true, resultCount: 0 } is a correct query that is not true now. { ok: false, error } is a query with an error: fix it and test again. Without an Admin login, the user clicks Test in the app in step 5.

Do not save rules through the API: PUT /api/machine/<id>/alert-rules puts the new list in place of all the rules of the machine.

5. Give the rule to the user

Give the user:

  • Name, short, for example Slow spindle while running.
  • Query, in a code block, or the words of the simple rule.
  • Minutes (0 to 1440) and level.
  • In one sentence, what makes it fire.
  • The steps: open the machine, click the Alert rules tab, click + Add rule, then Custom query (or Simple rule). Paste the name and the query, click Test, set the minutes and the level, and click Save changes.
  • For more machines: Copy rules to other machines on the same tab. Because of $machine, each copy checks its own machine.

From the toolpath/chatter README

Chatter by Toolpath

See the live status of your CNC machines from any browser on your shop network.
Chatter runs in your shop, on a computer or a Raspberry Pi.

Read the docs

The Machines page of Chatter, with four machines and their state, program, parts, spindle speed and tool

Features

  • Live machine status: running, idle, alarm, or offline, with the program, tool, spindle speed, spindle load, and part count
  • Machines: Brother, Haas, FANUC, Siemens SINUMERIK, and any machine with an MTConnect agent. Chatter can scan your network to find them.
  • History and reports: one year of machine history, with charts, running time, parts made, and alarms
  • File transfer: browse, send, download, and delete the program files on the machines, with an upload history
  • Users and roles: Viewer, Operator, and Admin accounts
  • Alerts: your own alert rules on the machine history
  • Notifications: text messages (Twilio), Discord, Telegram, ntfy, webhooks (Slack, Home Assistant), and Apprise (Teams, email, Pushover, and more) when an alert starts and ends
  • Updates: on the Raspberry Pi card, an Admin updates Chatter from Settings > Updates

Install

Open the newest release on the GitHub Releases page. The table Which file do I need? tells which file is for your computer or Raspberry Pi.

Docs

SectionPages
GuideGet started · AI agent skills · FANUC machines · Siemens machines · Alerts · Custom alert queries · Notifications · Update Chatter · Server logs · Use HTTPS · Security
Hardware3D printed case
DevelopRun from source · Fake machines · Pi card image
APIOverview · Login and settings · Machines and files · History and alerts · Notifications · FANUC library and updates · Live events

Security

Chatter is made for a shop network that you trust. Do not make it open to the internet. To report a security problem, see SECURITY.md. For the known limits, see Security in the docs.

Contributing

To report a bug or send a change, see CONTRIBUTING.md.

License

MIT. See LICENSE.

Details

Marketplace
toolpath/chatter
Source
plugins/chatter
Category
Community

Similar to chatter

More Development Tools