Guide · Agent skill
How to use the LifeOSHooks agent skill: install, trigger and debug
Updated · written with AI from the project's own documentation and checked against our catalogue data
LifeOSHooks is an agent skill for maintaining the LifeOS function-hook plugin, a piece of code that runs inside Claude Code and can draw small status lines and banners in the terminal. It is written for maintainers of that plugin, and it lets an agent check whether the plugin is loaded, explain why a line did or did not appear, and keep its generated type declarations and copied helper modules current. After this guide you will know what the skill does, how to install it, how to phrase a request that triggers it, and what it needs to run.
LifeOS Function Hooksdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Confirm the requirements. Check that Claude Code is at or above the build named in hooks/lib/build.ts, that bun is installed, and that your LifeOS install has the plugin directory and LIFEOS/TOOLS/HookBridge.ts.
- 3Validate the plugin. Run claude plugin validate on the plugin directory and confirm it passes.
- 4Run the headless probe. Run the headless probe with --debug-file and grep the log for a settled line and no failed to load line.
- 5Ask in plain words. Describe the problem, such as a missing banner or a Claude Code update, and let the skill check the relevant surface.
- 6Regenerate types if needed. After a Claude Code update, replace the declarations, set TYPES_BUILD, then run the typecheck and tests.
What is an agent skill, and what does LifeOSHooks do?
An agent skill is a folder with a SKILL.md file that tells an agent when to use it and how to work through a task. Once a skill is loaded, Claude Code can read it and follow its steps when a request matches its trigger phrases.
LifeOSHooks covers four jobs for the LifeOS hook plugin: confirming it is armed, explaining why a line or banner was or was not drawn, regenerating its type declarations after a Claude Code update, and syncing pure-core copies under hooks/lib/ with their sources. It also runs the plugin's probes.
- Status check: says whether the plugin is armed, on which build, and what evidence supports that.
- Draw diagnosis: names the surface that owns a line and the cause it found, labelled as a guess when it is one.
- Type regeneration: rebuilds .claude/types/claude-code.d.ts after a Claude Code update and checks the typecheck and tests.
- Core sync: keeps hooks/lib/ copies equal to their sources.
- Validation: runs claude plugin validate on the plugin directory.
Install the LifeOSHooks skill
Download the ZIP for the skill from the LifeOS page on this directory, then unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: unzip into ~/.claude/skills/.
- Project install: unzip into .claude/skills/ inside the project folder.
- Claude apps: Settings → Capabilities → Skills, then upload.
Set up the plugin so the skill has something to inspect
The skill assumes a local LifeOS install that contains the plugin directory and the LIFEOS/TOOLS/HookBridge.ts bridge. Loading the plugin from the skills folder is the simplest route: Claude Code loads it as LifeOSHooks@skills-dir and reloads it on every save.
The plugin's one user setting is forceBackground in its plugin manifest, which is off by default. The Setup.md file in the skill describes how to record your loading setup in an optional Config.md file.
- Simplest route: keep the folder under the skills directory so it loads as LifeOSHooks@skills-dir.
- Folder marketplace route: add it with claude plugin marketplace add <folder>, install it with claude plugin install <name>@<marketplace>, and disable the skills-dir copy so only one version loads.
- Optional config: LIFEOS/USER/CUSTOMIZATIONS/SKILLS/LifeOSHooks/Config.md, under $CLAUDE_CONFIG_DIR or ~/.claude.
claude plugin validate <plugin dir>Trigger the skill with natural requests
The skill activates on phrases about the plugin itself. You do not need to name a command. Describe the problem in plain words, and mention the thing that is wrong.
Requests that match its triggers include asking whether the plugin is loaded, reporting a missing banner or memory line, or asking the agent to regenerate plugin types. Requests about the command hooks under hooks/, the Pulse dashboard, or Relay diagnostics do not belong to this skill.
- "Is the LifeOS plugin loaded in this session?"
- "The banner is missing after my last session. Why was it not drawn?"
- "Claude Code updated, so regenerate the plugin types."
- "Run plugin validate on the LifeOS plugin directory."
- "The memory line is missing. Check the hooks module."
Run the checks the skill uses
The skill relies on a fixed set of commands. You can run them yourself to see what the agent will do. Run the typecheck from inside the plugin directory, and run tests from there too, because running them from the install root hit a file-descriptor limit error (EMFILE) in the source notes.
Sync the pure-core copies after you edit a source file. The headless probe starts a single-turn session with the plugin loaded and writes a debug log you can grep for settled and failed to load.
- Typecheck: cd <plugin dir> && bunx tsc --noEmit -p tsconfig.json
- Tests: cd <plugin dir> && bun test ./tests (source tree only, not in the public release)
- Sync cores: bun <plugin dir>/scripts/SyncCores.ts
- Headless probe: claude -p "Reply OK." --plugin-dir <plugin dir> --debug-file <log> --max-turns 1
claude -p "Reply OK." --plugin-dir <plugin dir> --debug-file <log> --max-turns 1Diagnose a missing banner or line
Many lines you might expect from the plugin are not drawn by it. The banner is the model's own first line, and the closing 🗣️ line is its last. Memory and health lines are logged rather than drawn, and the interview chip sits on the statusline. The skill knows which surface owns each line, so it checks there first.
When you ask about a missing line, the agent should name the evidence it used, such as this session's stamp file, hooks/lib/build.ts, or the probe's debug log. A diagnosis with no evidence is not a finished answer.
- Check whether the plugin is armed in this interactive session.
- Check the build named in hooks/lib/build.ts against your Claude Code version.
- Check which surface owns the line before assuming the plugin drew it.
- For a headless check, look for settled and the absence of failed to load in the debug log.
Regenerate types after a Claude Code update
Plugin type declarations belong to Claude Code and are not shipped with the plugin, so each install generates its own from the build it runs. The /plugin-types command was removed in build 2.1.287, so the skill uses the plugin-authoring skill from the running build instead.
Put the generated declarations at .claude/types/claude-code.d.ts, set TYPES_BUILD in hooks/lib/build.ts, then run the typecheck and tests. Record the old and new build in your answer.
- Declarations file: .claude/types/claude-code.d.ts (its first line names the build).
- Set TYPES_BUILD in hooks/lib/build.ts.
- Run the typecheck and then the tests.
- MCP declarations in .claude/types/claude-code-mcp.d.ts can embed a logged-in Slack user id. Replace it with <slack-user-id> before committing.
What people use it for
- Finding out why a hook-drawn banner did not appear after a session.
- Checking that the plugin is armed on the declared build before a release.
- Regenerating plugin type declarations after upgrading Claude Code and confirming the typecheck passes.
- Keeping pure-core copies under hooks/lib/ equal to their sources after an edit.
Frequently asked questions
Is LifeOSHooks free to use?
The skill is released under the MIT licence. Check the licence file in the repository for the full terms before you reuse or redistribute it.
What do I need to run LifeOSHooks?
You need Claude Code at or above the build named in hooks/lib/build.ts (MIN_BUILD), the bun runtime, and a local LifeOS install with the plugin directory and LIFEOS/TOOLS/HookBridge.ts. The skill does not work on its own without that repository layout.
Does LifeOSHooks use the network?
According to the skill's own assessment, it does not use the network, but it does run scripts. Review the scripts before running them, and note that adding diagnostic output to the live hooks module can flood a session transcript.
How do I check that the plugin is loaded?
Run claude plugin validate on the plugin directory, then run the headless probe and look for a settled line with no failed to load line in the debug log. Ask the skill to check whether the plugin is armed, and it will name the evidence it used.
Why is my banner missing?
The banner is the model's own first line rather than something the plugin draws, so a missing banner is not always a plugin fault. The skill checks which surface owns the line and reports the cause it found, labelling any guess as a guess.
Is LifeOSHooks for general users or maintainers?
It is aimed at maintainers of the LifeOS hook plugin. If you want a general productivity or dashboard tool, this skill is not the right fit, because it excludes the Pulse dashboard and Relay diagnostics.
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
LifeOSHooks is a narrow maintainer tool for debugging and upgrading the LifeOS hook plugin inside Claude Code. Use it if you maintain that plugin, need to work out why a hook-drawn line is missing, or must regenerate type declarations after a Claude Code update. If you want a general productivity tool or dashboard, or you do not have the LifeOS repository layout, pick something else.
Download the skill