Skip to content
Get packs

Guide · Agent skill

How to use the Smoke Test Health Checker agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The smoke-test skill lets an AI agent run a set of health checks on a gbrain setup, and on OpenClaw services when they are present. It is useful after a machine or container restart, or when something seems broken. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to watch for before you let it change anything.

Smoke Test Health Checkergarrytan/gbrain · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Confirm your gbrain setup. Make sure the gbrain CLI with the smoke-test command is installed, and that GBRAIN_DATABASE_URL or .env is configured with a database connection and an embedding API key.
  3. 3Ask the agent to run the check. Say something like "run smoke tests" or "did the restart break anything?" after a restart or when something seems broken.
  4. 4Read the summary line. Check the Results line for passed, auto-fixed and skipped counts. Any unfixed failure is named with the attempted fix.
  5. 5Handle failures. For a database failure with a GBRAIN_DB_ACCESS marker, the agent runs gbrain db-repair and re-tests, but the rewrite tier needs your agreement. For a missing embedding key, set it in .env.
  6. 6Review the log if needed. Open /tmp/gbrain-smoke-test.log, or the path in GBRAIN_SMOKE_LOG, to see the timestamped record of the run.

What is an agent skill and what does smoke-test make the agent do?

An agent skill is a folder containing a SKILL.md file. The file tells an AI agent when to use a capability and how to carry it out. This skill is named smoke-test and is part of the gbrain plugin.

When it runs, the agent executes gbrain smoke-test. The script tests 8 core items: the Bun runtime, the gbrain CLI, the gbrain database, the gbrain worker process, the OpenClaw Codex plugin, the OpenClaw gateway, the embedding API key, and the brain repo. OpenClaw tests are skipped when OpenClaw is not installed. For some bounded local failures the script tries a simple fix and then re-tests. It reports each check as passed, failed, fixed or skipped.

  • Tests 1 to 3 and 5 can attempt automatic fixes, such as installing Bun, reinstalling dependencies, or running gbrain db-repair --yes.
  • Worker repair is not automatic. The skill reports worker status and duplicate detection instead.
  • The skill can also run your own check scripts from ~/.gbrain/smoke-tests.d/.

Install the smoke-test skill

Download the ZIP from this page and unzip it into one of two places. For a personal skill available everywhere, use ~/.claude/skills/. For a skill that only applies to one project, unzip it into that project's .claude/skills/ folder.

You can also upload the ZIP in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload it there.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills

Make sure your setup meets the requirements

The skill checks a setup. It does not install gbrain for you. You need gbrain installed with the smoke-test command available. You also need a database connection set through GBRAIN_DATABASE_URL or a .env file, and an embedding API key in .env for test 7.

OpenClaw with its Codex plugin and gateway is optional and is needed only for tests 5 and 6. A brain repo path is optional and is used by test 8. If GBRAIN_BRAIN_PATH is not set, test 8 is skipped rather than failed.

  • gbrain CLI with the smoke-test command
  • Bun runtime (test 1 checks it and the script can install it)
  • GBRAIN_DATABASE_URL or .env database connection
  • Embedding API key in .env (test 7)
  • Optional: OpenClaw Codex plugin and gateway (tests 5 and 6)
  • Optional: brain repo path for test 8, set via GBRAIN_BRAIN_PATH

Trigger the skill with natural requests

The skill responds to phrases such as the ones below. You do not need the exact wording, but these are the trigger phrases the skill lists. Use them after a restart or when something stops working.

You can also run the check yourself from a terminal or a startup script. The skill's documentation gives these forms.

  • "Run smoke tests"
  • "Did the container restart break anything?"
  • "Health check"
  • "Container restart check"
gbrain smoke-test

Read the results and act on them

The script prints one line per check with a status marker and a final summary in the form Results: N/M passed, F auto-fixed, S skipped. Each run also appends a timestamped log to /tmp/gbrain-smoke-test.log by default. You can change that path with GBRAIN_SMOKE_LOG.

The exit code equals the number of unfixed failures, so 0 means all tests passed. A skipped test is not a failure, but it also does not count as a pass. Do not read an all-green result as complete if some tests were skipped.

  • Each failure is reported by name with the attempted fix.
  • Skipped tests are reported separately from failures.
  • If the embedding API key is missing, the skill tells you search runs keyword-only until it is set.

Add your own checks

Put executable .sh scripts in ~/.gbrain/smoke-tests.d/. Exit 0 means pass and any non-zero exit means fail. The filename becomes the test name, so check-redis.sh appears as check-redis. Tests run in alphabetical order.

Keep each check under 10 seconds and wrap any command that could hang in timeout N. Read environment variables such as HOME and GBRAIN_DATABASE_URL instead of hardcoding paths.

  • Example from the docs: a script that runs redis-cli ping and checks for PONG
  • Keep tests fast (under 10 seconds each)
  • Use timeout N around commands that might hang
#!/bin/bash redis-cli ping | grep -q PONG

What people use it for

  • Checking gbrain on a local machine after a reboot
  • Running a startup check from a login hook or ensure-services.sh script in an OpenClaw deployment
  • Diagnosing why search or the worker stopped working
  • Adding your own check, such as confirming a Redis server responds, to the smoke test run

Frequently asked questions

Is the smoke-test skill free?

The source describes the skill as MIT licensed. The source does not list prices, so check the repository for the license text before you rely on it.

What do I need before I install smoke-test?

You need gbrain installed with the smoke-test command, Bun, a database connection via GBRAIN_DATABASE_URL or .env, and an embedding API key in .env for test 7. OpenClaw and a brain repo path are optional.

Where do I put the skill files?

Unzip the downloaded ZIP into ~/.claude/skills/ for a personal install or into .claude/skills/ in a project folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Will the skill change my database or packages?

Yes, it can. The skill is marked as mutating. It can install Bun, reinstall dependencies, run npm install zod@4 --force for the OpenClaw Codex plugin, and run gbrain db-repair --yes. The source warns that database repair can be risky on production data without a backup.

Why did a test show as skipped instead of failed?

Skips are used when a prerequisite is missing, such as OpenClaw not being installed or GBRAIN_BRAIN_PATH not being set. Skips do not count as failures, but you should not treat an all-green run as complete if tests were skipped.

Does smoke-test work if I don't use gbrain?

No. Most checks are specific to gbrain, so the source says it is not useful for people who do not use gbrain and may report misleading skips.

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 smoke-test if you run gbrain on a local machine or container, restart it often, or run OpenClaw services that need a startup check. Skip it if you do not use gbrain, or if you do not want an agent to make automatic changes to packages or the database, especially on production data without a backup.

Download the skill