
chatter
Setup, machine-connection repair, alert authoring, and history reports for the Chatter CNC monitor.
- GitHub stars
- 5
What it does
- Adds
/set-up-chatter,/debug-machine-connection,/alert-query, and/machine-reportskills 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/chatterRun it inside Claude Code once, then install the plugin below.
Install
/plugin install chatter@toolpath-chatterRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceWrite 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.
| Metric | What it is | History value |
|---|---|---|
chatter_connected | Chatter can reach the machine (1 or 0) | connected |
chatter_running | A program runs (1 or 0) | running |
chatter_alarm | The machine has an alarm (1 or 0) | alarm |
chatter_emergency | The emergency stop is pushed (1 or 0) | emergency |
chatter_spindle_speed | RPM | spindle-speed |
chatter_spindle_load | % | spindle-load |
chatter_feedrate | the machine's unit | feedrate |
chatter_part_count | parts | part-count |
chatter_part_goal | parts | part-goal |
chatter_tool_number | tool number | tool-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
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.
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.
- Install on a computer: Windows, Mac, or Linux, with Docker
- Install on a Raspberry Pi: flash the Chatter card image
- Get started: create the Admin login, add machines, set up FTP, add users
Docs
| Section | Pages |
|---|---|
| Guide | Get started · AI agent skills · FANUC machines · Siemens machines · Alerts · Custom alert queries · Notifications · Update Chatter · Server logs · Use HTTPS · Security |
| Hardware | 3D printed case |
| Develop | Run from source · Fake machines · Pi card image |
| API | Overview · 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
reamorluto/rea466.8K starsReverse engineer anything with agents, from app behavior down to native binaries.
superpowersobra/superpowers319.5K starsCore skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
claude-apianthropics/skills196.9K starsClaude API and SDK documentation skill for building LLM-powered applications
prompts.chatf/prompts.chat178.2K starsAccess thousands of AI prompts and skills directly in your AI coding assistant. Search prompts, discover skills, save your own, and improve prompts with AI.
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
ui-ux-pro-maxnextlevelbuilder/ui-ux-pro-max-skill152.6K starsProfessional UI/UX design intelligence for AI coding assistants. Includes searchable databases of styles, colors, typography, charts, and UX guidelines for Reac