Guide · Agent skill
How to use the Vigil Monitoring Log agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Vigil is a central event log for a LifeOS setup. Subsystems and scheduled jobs write events in one format, and a five-minute tick routes them by severity to a text message, a daily digest, or a dashboard. This guide explains what the Vigil skill lets your agent do, how to install it, how to ask for things in plain language, and what to check before you rely on it.
Vigil Monitoring Logdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Confirm your LifeOS layout. Make sure the LifeOS framework folder has LIFEOS/VIGIL and LIFEOS/USER directories, and that Bun is installed.
- 2Install the skill. Download the ZIP from the skill page and unzip it into ~/.claude/skills/ or a project's .claude/skills/. In the Claude apps, upload it under Settings, then Capabilities, then Skills.
- 3Check the tick. Run the heartbeat check. It exits 1 when the last tick is older than twice the cadence or has never run.
- 4Ask for status. Ask your agent "anything I should know?" It will start with the tick's health, then list new high and critical events.
- 5Review the routing policy. Check LIFEOS/USER/VIGIL/policy.json and the daily text limit before you turn the tick on.
- 6Install the tick only when you want it. Ask the agent to install Vigil. It will register com.lifeos.vigil in launchd and report the status output after install.
What the Vigil skill makes the agent do
The skill is the front door to Vigil. It lets an agent read the Vigil log, feed new events into it, and help with the monitoring tick. It has four intents: Status, Emit, Digest and Install.
Status answers questions like "anything I should know?" and opens with the health of the tick, because a quiet log and a dead reader look the same. Emit posts one event to the local outbox that the next tick will route. Digest reports the medium-severity items waiting in the digest and the events held by the daily text limit. Install registers the monitoring tick in launchd.
- Status: what is going on, anything I should know, is the tick alive
- Emit: log this to Vigil, post an event, emit an event
- Digest: pending digest, what got held
- Install: install Vigil, start the tick, register the monitor
Install the Vigil skill from the ZIP or in the Claude apps
You can install the skill in one of two ways. Download the ZIP from the skill page, then either unzip it into your user skills folder or into a project's skills folder. For a single user, use ~/.claude/skills/. For one project, use .claude/skills/ inside that project.
Alternatively, upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ in the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you use it
The skill depends on the LifeOS framework and will not work on its own. It needs the Bun runtime, because the scripts run with bun. Your LifeOS folder must include LIFEOS/VIGIL and LIFEOS/USER directories.
The scheduled tick uses macOS launchd. The VIGIL_URL and VIGIL_TOKEN variables and a Cloudflare D1 setup for the store Worker are optional. The same applies to a notification endpoint for SMS or text delivery. With VIGIL_URL unset, the reader works from the local outbox alone.
- Bun runtime (scripts run with bun)
- LifeOS folder layout with LIFEOS/VIGIL and LIFEOS/USER
- macOS launchd for the scheduled tick
- Optional: VIGIL_URL and VIGIL_TOKEN for the remote store, plus a Cloudflare D1 setup for the store Worker
- Optional: a notification endpoint for SMS or text delivery
bun LIFEOS/VIGIL/Vigil.ts heartbeatTrigger the skill with natural requests
You do not need to type commands. Ask in plain language and the agent picks the matching intent. Phrases such as "what is going on", "is the tick alive", "what got held" and "install vigil" all route to the right intent.
The skill is not for filing complaints about a system, for standing questions and their answers, or for the vulnerability registry. Those belong to other parts of LifeOS.
- "Anything I should know about?"
- "Is the tick alive?"
- "What got held today?"
- "Log this to Vigil: the backup job finished with warnings."
- "Install Vigil."
Examples of what Vigil does in practice
A morning check starts with the tick's health, then lists new high and critical events, then gives the digest count. A scheduled job can report a problem. For example, a job that finds a certificate expiring in six days can post a high-severity event. The emit report counts it as emitted only alongside a fresh heartbeat, and the next tick decides how it is routed.
You can also ask how many rows are in the Vigil D1 database. The answer uses the row count from the last tick's probe and shows when it was taken and whether the store was reachable.
- Morning check: tick health first, then new high and critical events, then the digest count
- Job report: a service posts a high-severity event that the next tick routes by policy
- Store check: the row count from the last tick, with its time and reachability
Safety notes: scripts, network and credentials
The skill runs scripts and uses the network. Store credentials, VIGIL_URL and VIGIL_TOKEN, are kept in the env file the install uses. They are never printed and never placed in a URL.
The skill reads and feeds the log without changing what the tick owns. It does not delete digest lines, move the digest file, edit the plist, or install the tick unless you ask. Events carry no values, names or credentials. Adapters read file times and snapshots, not content, and the emitter refuses restricted data rather than working around it. The tick is headless and must never voice.
- Credentials are never printed or put in URLs
- The skill does not edit the launchd plist by hand
- Install runs only when you ask for the tick to be on
- The policy file is checked before the first live tick, because that tick can send texts
- Do not call the notify endpoint from anything the tick runs
Tips and common gotchas
The first tick against a fresh reader cursor writes a baseline covering the whole backlog and routes nothing. It prints {"baseline":true,...}. A first run that sends texts is a bug, so check before going further. A dry run also writes that baseline on a fresh cursor, and repeated dry runs print the same decisions.
An event held by the daily text limit joins the single held or deferred queue. It is not texted later on its own. Read it with the queue command, the dashboard, or by asking for status. Events from source vigil are stored and shown but never routed, so the log cannot feed itself.
- Read held events with Vigil.ts queue, not by waiting for a later text
- Two dry runs in a row giving identical output is expected
- Check the policy file at LIFEOS/USER/VIGIL/policy.json before installing
- The daily text limit is the interruption budget under enforce mode, and text_ceiling_per_24h under shadow mode
What people use it for
- Asking each morning whether anything needs attention, with the tick's health shown first
- Having a scheduled job post a high-severity event, such as a certificate nearing expiry
- Reading the medium-severity digest grouped by source, with the age of each item
- Checking whether the monitoring tick is still running after a machine restart
- Reviewing events held by the daily text limit in the last 24 hours
Frequently asked questions
Is the Vigil agent skill free to use?
The skill is published under the MIT licence. The source does not list prices, so check the licence file in the repository for the terms.
What do I need before installing Vigil?
You need the LifeOS framework with LIFEOS/VIGIL and LIFEOS/USER folders, and the Bun runtime. The scheduled tick uses macOS launchd. Texts and store uploads need extra credentials and a deployed Worker.
Will Vigil work without LifeOS?
No. The skill depends on the LifeOS folder layout, policy files and launchd setup, so it will not work on its own. It also only routes events that subsystems post to its local log.
Why does my first Vigil tick not send any texts?
A fresh reader cursor writes a baseline covering the whole backlog and routes nothing on that first run. This stops old events from using up the day's text limit at once.
What does it mean when the heartbeat check exits 1?
It means the last tick is older than twice the cadence or has never run. Events will not be routed until the tick is running again.
How is Vigil different from the Errata, Socrates and Achilles parts of LifeOS?
Vigil is the event log and router. Errata handles complaints about a system, the Socrates ledger holds standing questions and answers, and Achilles is the vulnerability registry. The skill's own description lists these as separate things it does not handle.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Vigil suits developers and power users who already run the LifeOS framework and want one place for system alerts and a summary an agent can give them. It is a poor fit for anyone without LifeOS, anyone wanting alerts on arbitrary systems, or anyone who has not set up the texting service and its credentials.
Download the skill