Guide · Agent skill
How to use the Hermes Sidecar Observability agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Hermes skill is an agent skill that lets an AI agent inspect a Hermes sidecar, a separate background assistant install that LifeOS uses for messaging and scheduled tasks. It is for people who run that sidecar and need to find out whether it is healthy, why a task or cron job failed, or what happened inside one session. After this guide you will know how to install the skill, which requests trigger each kind of check, and what the skill will and will not change.
Hermes Sidecar Observabilitydanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Confirm the prerequisites. Check that a Hermes sidecar is installed at $HERMES_HOME (default ~/.hermes) and that LifeOS includes the LIFEOS/HERMES/ tools. Confirm a Bun or TypeScript runtime is available.
- 2Download the skill ZIP. Get the Hermes ZIP from this page and unzip it.
- 3Place the skill folder. Move the unzipped folder into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder.
- 4Or upload it in the Claude apps. Open Settings, then Capabilities, then Skills, and upload the skill there.
- 5Ask a status question. Ask whether the sidecar is healthy to get a one-screen report on process state and soul loading.
- 6Trace a failed task. Describe the task that failed and ask for a trace to see every block and where it stopped.
- 7Triage recurring failures. Ask the agent to triage Hermes failures and act on the worst class first.
What is an agent skill, and what does the Hermes skill do?
An agent skill is a folder of instructions and tools that an AI agent loads when a request matches its purpose. The Hermes skill covers observability over a mounted Hermes sidecar. The sidecar keeps its own records, including a session store, cron execution history, error logs and a guard audit trail, and the skill turns those records into answers.
It answers three kinds of question: whether the sidecar is healthy, what failed and why, and exactly what happened inside one task. Diagnosis changes nothing. The skill makes no config writes, restarts or cron edits when it diagnoses. Only the Update intent is allowed to modify the sidecar.
- Status: process state (up, degraded, flapping, down or absent) and whether sessions actually load the LifeOS soul (persona file)
- Triage: failure classes from the last 7 days with counts, worst first, each with a suggested fix
- Trace: one task rebuilt step by step, from the message that started it to the point where it stopped
- Update: checking whether Hermes is up to date and running a post-update check
What you need before installing
The skill observes an existing install. It does not install Hermes for you. The source lists these requirements: a Hermes sidecar installed at $HERMES_HOME (default ~/.hermes), a LifeOS installation that includes the LIFEOS/HERMES/ tools (Observe.ts, Health.ts, LogAnalysis.ts and Mount.ts), and a Bun or TypeScript runtime to run the .ts tools. Gateway restart steps use launchctl, which is the macOS service manager.
Without a sidecar, the skill reports the state as absent and has nothing to observe.
Install the Hermes skill with the ZIP download
Download the ZIP for the Hermes skill from this page and unzip it. Place the resulting folder in one of two locations. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead, you can upload the skill under Settings, then Capabilities, then Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Ask for what you need in plain language
You do not need to type a command name. The skill loads when your request matches its trigger phrases. The source lists triggers such as "hermes status", "is hermes healthy", "why do hermes tasks fail", "triage hermes", "trace that task", "what happened to my message" and "is hermes up to date". Each phrase routes to one of the four intents.
- "Is the sidecar healthy?" routes to Status
- "Hermes tasks keep failing, triage it" routes to Triage
- "My iMessage task to Hermes failed again, what happened?" routes to Trace
- "Is hermes up to date?" routes to Update
Read the results, and know what the skill checks
Status reports the soul verdict: how many sessions in the last 24 hours loaded the LifeOS constitution and how many started with a blocked prompt. A nonzero blocked count is the lead finding. Mount drift is reported as current or stale, and a stale result names re-running Mount.ts as the next step.
Trace treats a "completed" run as unproven. Cron runs can report completed while every meaningful tool call inside them was blocked, so the skill judges success from the trace itself. Guard blocks that match the sidecar's no-terminal-no-voice rule are marked as by design, not as defects.
- Blocked soul: the lead finding in any report where it appears
- By-design blocks: voice-notification denies that enforce the no-terminal-no-voice rule
- Credential files: .env and auth.json are listed by size and modification time only, never read
Safety notes: scripts and network
The skill runs scripts. The source says it executes the LIFEOS/HERMES/ tools, and it opens every sidecar database read-only so it does not hold a write lock on a live gateway. It does not use the network. Fixes are routed through Policy.ts and Mount.ts, which own the config, rather than hand-edited. Because the skill can restart a gateway service through launchctl during update steps, review those steps before you approve them on a live system.
- Runs local scripts: yes
- Uses network: no
- Diagnosis writes nothing; only the Update intent changes the sidecar
What people use it for
- Finding out why an iMessage task sent to Hermes failed and which step it stopped at
- Checking whether the LifeOS soul (persona file) is loading in sidecar sessions after a change
- Reviewing cron job failures and guard blocks from the past week to find false positives
- Confirming Hermes is up to date and healthy after an upgrade
Frequently asked questions
How do I install the Hermes agent skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for a personal install or in a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
What does the Hermes skill need to work?
It needs a Hermes sidecar installed at $HERMES_HOME (default ~/.hermes), a LifeOS installation with the LIFEOS/HERMES/ tools, and a Bun or TypeScript runtime to run the .ts tools. Gateway restart steps use launchctl, which is macOS service management. Without a sidecar, the skill reports absent.
Is the Hermes skill free, and what is its licence?
The item is listed under the MIT licence. The source does not state any price, so check this page for current terms before you rely on it.
Does the Hermes skill change my sidecar?
Diagnosis does not. The skill makes no config writes, restarts or cron edits during Status, Triage or Trace. Only the Update intent is allowed to modify the sidecar, and fixes are routed through Policy.ts and Mount.ts.
Why does my Hermes task show completed but still fail?
A cron run can report completed while every meaningful tool call inside it was blocked or stopped waiting for approval. The skill judges success from the trace rather than the execution status, so ask for a trace of that task.
Does the Hermes skill handle messaging or LifeOS services?
No. It explicitly excludes general messaging, handled by the communication skill, and LifeOS service management (Services.ts), as well as mounting (Mount.ts in its own intent).
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
Use this skill if you run a Hermes sidecar alongside LifeOS and need to debug failed iMessage or chat tasks, confirm the LifeOS soul is loading, or check that Hermes is current after an upgrade. Pick something else if you do not have a sidecar installed, need general messaging or LifeOS service management, or want an agent to make live fixes without your review.
Download the skill