🇺🇸 English ｜ 🇯🇵 日本語 ｜ 🇨🇳 简体中文 ｜ 🇹🇭 ไทย
errmeter reports failed or silent AI agents and scheduled jobs, so unnoticed failures across machines reach a shared board and a repair hook.
A shout that is never lost.
🔧 Engineering: architecture ｜ 📘 Reference: contract
Sound familiar? ｜ What it does ｜ What you need ｜ Get started ｜ Why it's safe ｜ Learn more ｜ License
Running jobs on several machines makes silence easy to miss.
- A nightly job stopped a week ago, and you only noticed today.
- An agent failed at 3 a.m.; its error stayed on a machine you rarely open.
- Your laptop was asleep when it was supposed to watch the other agents.
- Someone said it was fixed, but nobody can trace what actually happened.
errmeter gives those machines one shared place to report what happened.
An agent writes its report to local disk first; a forwarder delivers it when the network allows, and a watcher hands failures to your repair hook.
flowchart LR
E[emit] --> P[spool: local disk]
P --> S[sink: GitHub Issues]
S --> W[watch]
W --> D[dispatch hook]
W --> N[notify]
- 📣 Emit — report a failure or send an “I am alive” heartbeat.
- 💾 Spool — keep the report locally until delivery is acknowledged.
- 📮 Sink — forward reports to your private GitHub Issues board.
- 👀 Watch — claim failures, run your repair hook, and escalate to you.
Repeated errors share an Issue, so you can trace occurrences and repair outcomes. You supply the repair hook and notification settings; errmeter does not repair code by itself or merge repair PRs.
The disk-first design has limits: storage exhaustion can lose reports; overflow reduces detail, and its ceiling drops further occurrences. A host without a loop retries for a bounded linger period and at its next emit. If every machine is down, none can notify you. See durability and loss boundaries.
That shared board needs only a runtime, a repository, and a narrowly scoped token.
Start on one agent machine with these three things.
- Node.js 18+ — no package dependencies, build step, or database.
- A private GitHub repository — for example,
owner/errmeter-inbox. - A fine-grained token — limited to that repository's Issues and metadata.
| Environment | Support | What to know |
|---|---|---|
| macOS | ✅ Supported | Native launchd registration |
| Linux, user-scope systemd | Starts at login; boot needs user lingering; real-host validation pending | |
| Linux, system-scope systemd | Requires validation on a real host | |
| Windows | Native Task Scheduler path; real-host validation pending | |
| Node.js 18 / 20 / 22 / 24 | ✅ Local matrix | Tests run locally on macOS (all four majors) and on a Linux VPS (Node 22, 2026-09-09); no GitHub Actions |
| Any process that can run a command | ✅ Command interface | Call errmeter emit |
| Claude Code | ✅ Hook integration | Owner-applied hooks; see integrations |
| Codex | ✅ Notify integration | Owner-applied notify hook; see integrations |
| cron / launchd jobs | ✅ Job wrappers | Preserve the job's exit status |
The local matrix policy describes verification; the integration index explains the owner tools. Monitoring needs watch on an always-on machine; an agent-only host can run the lighter agent-host loop.
With those prerequisites ready, install and send your first report.
Install on one machine first, then connect its report to your private board.
Paste this into the agent you use:
https://github.com/caty-ai/errmeter
Install this with: npm install -g errmeter — then help me configure it.
If npm is missing, follow the README's prerequisites and install guidance.
The command is spelled out so your agent uses the intended npm package and install route.
Open a terminal and install the command:
npm install -g errmeter
errmeter --helpCreate your private inbox repository first. Replace <owner>/<inbox> below with its name (for example, owner/errmeter-inbox); do not type the angle brackets.
errmeter init --repo <owner>/<inbox> --role agent-hostUse init --api-base URL for a custom HTTPS API endpoint (HTTP is allowed only for localhost/127.0.0.1); uninstall and install/uninstall dry-runs need no token, and stale install records are noted in dry-run previews. Linux user status probes linger only with --check or when a registered service's status is degraded.
Save your fine-grained token in ~/.errmeter/github-token as plain text, with file mode 0600 on macOS/Linux (only your user can read and write it). On Windows, use %USERPROFILE%\.errmeter\github-token and restrict its profile ACL to your user. Keep the token out of shell history, messages, and logs.
With that token in place, verify access. This check uses the network, creates the required labels, and creates and closes a probe Issue; it needs a valid token. Review the token's permission page yourself too: the probe cannot prove least privilege.
errmeter status --checkSave a small, non-sensitive log as ./last.log, then send a report:
errmeter emit --agent my-agent --message "something broke" --detail-file ./last.logThe report is queued locally and delivery is attempted separately. Exit 0 does not confirm that the board received it. A fresh board can report degraded status because no watcher is known yet; finish the watcher and heartbeat setup and configure your repair and notification hooks before relying on alerts.
Token setup, file location, or command not found?
A fine-grained personal access token is a GitHub credential whose repositories and permissions you choose. In GitHub's developer settings, select only your private inbox, Issues: Read and write, and Metadata: Read. No Contents or Pull requests permission is needed. See the token boundary.
The default home is ~/.errmeter (%USERPROFILE%\.errmeter on Windows). If you set ERRMETER_HOME, put the token at the sink.token_file path in that home's config.json; ERRMETER_GITHUB_TOKEN takes precedence if set. A file permissions editor can set mode 0600 on POSIX systems; Windows uses profile access controls instead.
If npm is missing, install Node.js 18+ with npm using your operating system's installer or your existing Node version manager, then reopen the terminal. If errmeter is still not found, check that npm's global executable directory is on your PATH. A terminal is the application where you paste commands: Terminal on macOS/Linux, or PowerShell on Windows.
Once the first report is queued, check the boundaries before connecting more jobs.
The contract defines these boundaries.
- Your agent — emit returns fast with exit 0; CLI misuse returns 2 (§11).
- Your token — inbox Issues and metadata only; review its permissions (§8).
- Your logs — a redacted tail leaves; known secrets are masked (§4).
- Your choice —
errmeter uninstallremoves boot registration (§11). - Your machine — only
watchruns long-term; no HTTP server (architecture §9).
The owner hook tools also restore their backups; uninstalling boot registration does not remove hooks or erase your records. No hosted server or paid CI is needed: laptops may run an agent-host loop or emit without one. Redaction is pattern-based, so review sensitive log content before forwarding it; repair hooks run as the watcher's OS user and need their own credentials.
Not for you if you have a single machine and a single agent, or you already have a paid monitoring stack that covers this need.
For configuration, operating limits, and contributions, use the references below.
Choose the reference for the next decision you need to make.
| What you want | Where to look |
|---|---|
| User stories and non-goals | Requirements |
| Data flow and module map | Architecture |
| Configuration, commands, and boundaries | Contract |
| Agent hooks, job wrappers, and heartbeats | Integrations |
| Local tests and contribution process | Contributing |
| Private vulnerability reports | Security policy |
| README editions | English / 日本語 / 简体中文 / ไทย |
Part of the Caty AI family — open tools for running a family of AI agents. The full map, including modules still being prepared for release, lives in Family OS.
| Axis | Module | What it does | State |
|---|---|---|---|
| Map | Family OS | The map of the whole family — every module, its state, and how they fit | published, MIT |
| Rules | Family Dev Handbook | The rules of the road — issues, PRs, worktrees, handoffs, parallel development | published, MIT |
| Vertical · foundation | Caty Agent Harness | Task backbone for AI agents — retries, checkpoints, and honest completion | published, MIT |
| Vertical | context-kit | Six-piece context hygiene kit for one agent — bounded output, delegation briefs, safety guards, recall, worktree snapshots | published, MIT |
| Vertical | Persona Engine | Layers relationship and emotion onto an agent's existing persona | published, MIT |
| Vertical | Persona Growth Loop | Grows the persona itself — minimal, idempotent proposals | published, MIT |
| Vertical | X Collector | Turns X and the web into one daily digest — for people and agents | published, MIT |
| Vertical | Self Growth Loop | Lets an agent grow its own abilities — proposals, governance, adoption records | published, MIT |
| Horizontal · foundation | Family Memory Architecture | The memory bus — how the family shares what it knows | published, MIT |
| Horizontal | Sitter | Babysits delegated agent runs — watches, keeps evidence, restarts only within declared bounds | published, MIT |
| Horizontal | Alpha Nightshift | Nightly autonomous maintenance loop — isolated night lanes behind a deny-by-default guard; humans cherry-pick in the morning | published, MIT |
| Horizontal | errmeter | Reports failed or silent AI agents and scheduled jobs across machines — emit, spool, shared board, repair hook; a shout that is never lost | published, MIT |
| Vertical | Caty Gateway | PC-side gateway for CatyPhone — one-line install; pairs your phone with the agent running on your machine (Claude Code / Codex CLI / OpenClaw / Hermes / OpenAI-compatible) | published, MIT |
MIT, so you can use, modify, and incorporate errmeter into your own tools under its notice and warranty terms.
Zero dependencies ｜ Node 18+ ｜ No CI required