Skip to content
Back to search

claude-homelab

SkillWorks with Claude CodeGitHub

Comprehensive Agents, Commands, Hooks, and Skills for homelab service management - media automation, infrastructure monitoring, document management, and more

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jmagar--claude-homelab/badge.svg)](/listings/jmagar--claude-homelab)

HTML

<a href="/listings/jmagar--claude-homelab"><img src="/api/listings/jmagar--claude-homelab/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Claude marketplace

/plugin marketplace add jmagar/claude-homelab
/plugin install homelab-core @jmagar-claude-homelab

After install, Claude Code downloads the plugin into `~/.claude/plugins/cache/`. No symlinks are created on this path.

Bash / symlink install

curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/install.sh | bash

Or, if you already have the repo cloned:

./scripts/install.sh

The installer:

1. Checks prerequisites (`git`, `jq`, `curl`) 2. Clones the repo to `~/claude-homelab` (or pulls if it exists) 3. Runs `setup-creds.sh` — creates `~/.claude-homelab/.env` from `.env.example` with `chmod 600` 4. Runs `setup-symlinks.sh` — symlinks skills, agents, and commands into `~/.claude/` 5. Runs `verify.sh` — confirms every symlink and required file is in place 6. Prints next steps

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 346 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "claude-homelab",
  3. "owner": {
  4. "name": "jmagar",
  5. "email": "jmagar@users.noreply.github.com"
  6. },
  7. "metadata": {
  8. "description": "Comprehensive Claude Code skills and agents for homelab service management - media automation, infrastructure monitoring, document management, and more",
  9. "version": "1.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "homelab-core",
  14. "source": "./",
  15. "description": "Core homelab plugin bundling shared agents, commands, setup/health workflows, and the in-repo skill library until a skill graduates into its own standalone plugin repo.",
  16. "version": "1.1.2",
  17. "category": "core",
  18. "tags": [
  19. "agents",
  20. "commands",
  21. "skills",
  22. "orchestration",
  23. "setup",
  24. "health"
  25. ],
  26. "homepage": "https://github.com/jmagar/claude-homelab"
  27. },
  28. {
  29. "name": "overseerr-mcp",
  30. "source": {
  31. "source": "github",
  32. "repo": "jmagar/overseerr-mcp"
  33. },
  34. "description": "Overseerr media requests via MCP tools with HTTP fallback. Search movies and TV shows, submit requests, and monitor failed requests.",
  35. "version": "1.0.0",
  36. "category": "media",
  37. "tags": [
  38. "overseerr",
  39. "media",
  40. "requests",
  41. "plex",
  42. "mcp"
  43. ],
  44. "homepage": "https://github.com/jmagar/overseerr-mcp"
  45. },
  46. {
  47. "name": "unraid-mcp",
  48. "source": {
  49. "source": "github",
  50. "repo": "jmagar/unraid-mcp"
  51. },
  52. "description": "Query, monitor, and manage Unraid servers via GraphQL API through MCP tools with HTTP fallback. Supports system info, Docker, VMs, array/parity, notifications, plugins, rclone, and live telemetry. Requires unraid-mcp MCP server running.",
  53. "version": "1.2.0",
  54. "category": "infrastructure",
  55. "tags": [
  56. "unraid",
  57. "homelab",
  58. "graphql",
  59. "docker",
  60. "nas",
  61. "monitoring"
  62. ],
  63. "homepage": "https://github.com/jmagar/unraid-mcp"
  64. },
  65. {
  66. "name": "unifi-mcp",
  67. "source": {
  68. "source": "github",
  69. "repo": "jmagar/unifi-mcp"
  70. },
  71. "description": "UniFi network management via MCP tools. Monitor devices, clients, network health, firewall rules, and perform management operations.",
  72. "version": "1.0.0",
  73. "category": "infrastructure",
  74. "tags": [
  75. "unifi",
  76. "networking",
  77. "monitoring",
  78. "homelab",
  79. "mcp"
  80. ],
  81. "homepage": "https://github.com/jmagar/unifi-mcp"
  82. },
  83. {
  84. "name": "gotify-mcp",
  85. "source": {
  86. "source": "github",
  87. "repo": "jmagar/gotify-mcp"
  88. },
  89. "description": "Gotify push notifications and management via MCP tools with HTTP fallback. Sends alerts for long-running tasks, plan completions, and blocked states. Requires gotify-mcp MCP server running.",
  90. "version": "1.0.0",
  91. "category": "utilities",
  92. "tags": [
  93. "gotify",
  94. "notifications",
  95. "push",
  96. "homelab",
  97. "mcp"
  98. ],
  99. "homepage": "https://github.com/jmagar/gotify-mcp"
  100. },
  101. {
  102. "name": "swag-mcp",
  103. "source": {
  104. "source": "github",
  105. "repo": "jmagar/swag-mcp"
  106. },
  107. "description": "SWAG reverse proxy configuration management via MCP. Create, edit, view, and manage nginx proxy configurations with auth integration.",
  108. "version": "1.0.0",
  109. "category": "infrastructure",
  110. "tags": [
  111. "swag",
  112. "nginx",
  113. "reverse-proxy",
  114. "homelab",
  115. "mcp"
  116. ],
  117. "homepage": "https://github.com/jmagar/swag-mcp"
  118. },
  119. {
  120. "name": "synapse-mcp",
  121. "source": {
  122. "source": "github",
  123. "repo": "jmagar/synapse-mcp"
  124. },
  125. "description": "MCP server providing Flux (Docker management) and Scout (SSH operations) tools for homelab infrastructure.",
  126. "version": "2.2.1",
  127. "category": "infrastructure",
  128. "tags": [
  129. "synapse",
  130. "flux",
  131. "scout",
  132. "homelab",
  133. "docker",
  134. "ssh",
  135. "infrastructure",
  136. "zfs",
  137. "remote-management"
  138. ],
  139. "homepage": "https://github.com/jmagar/synapse-mcp"
  140. },
  141. {
  142. "name": "arcane-mcp",
  143. "source": {
  144. "source": "github",
  145. "repo": "jmagar/arcane-mcp"
  146. },
  147. "description": "Manage Docker containers, images, volumes, networks, and stacks via the Arcane API.",
  148. "version": "1.1.3",
  149. "category": "infrastructure",
  150. "tags": [
  151. "arcane",
  152. "docker",
  153. "homelab",
  154. "mcp",
  155. "containers"
  156. ],
  157. "homepage": "https://github.com/jmagar/arcane-mcp"
  158. },
  159. {
  160. "name": "syslog-mcp",
  161. "source": {
  162. "source": "github",
  163. "repo": "jmagar/syslog-mcp"
  164. },
  165. "description": "Homelab syslog receiver plus MCP server for searching, tailing, and correlating logs across hosts.",
  166. "version": "1.0.0",
  167. "category": "infrastructure",
  168. "tags": [
  169. "syslog",
  170. "logs",
  171. "observability",
  172. "homelab",
  173. "mcp",
  174. "sqlite"
  175. ],
  176. "homepage": "https://github.com/jmagar/syslog-mcp"
  177. },
  178. {
  179. "name": "plugin-lab",
  180. "source": {
  181. "source": "github",
  182. "repo": "jmagar/plugin-lab"
  183. },
  184. "description": "Agents, commands, skills, and scripts for scaffolding, reviewing, aligning, and deploying homelab MCP server plugins. Includes canonical Python, TypeScript, and Rust server templates.",
  185. "version": "1.0.0",
  186. "category": "dev-tools",
  187. "tags": [
  188. "scaffolding",
  189. "templates",
  190. "mcp",
  191. "plugin-dev",
  192. "plugin-lab",
  193. "python",
  194. "typescript",
  195. "rust",
  196. "agents",
  197. "ci-cd"
  198. ],
  199. "homepage": "https://github.com/jmagar/plugin-lab"
  200. },
  201. {
  202. "name": "bytestash",
  203. "source": "./skills/bytestash",
  204. "description": "ByteStash code snippet management. Store, search, and organize code snippets.",
  205. "version": "1.0.0",
  206. "category": "utilities",
  207. "tags": ["bytestash", "snippets", "code", "homelab"],
  208. "homepage": "https://github.com/jmagar/claude-homelab"
  209. },
  210. {
  211. "name": "gh-address-comments",
  212. "source": "./skills/gh-address-comments",
  213. "description": "Address GitHub PR review comments. Fetch, implement, and verify resolution of PR feedback.",
  214. "version": "1.0.0",
  215. "category": "dev-tools",
  216. "tags": ["github", "pull-requests", "code-review", "automation"],
  217. "homepage": "https://github.com/jmagar/claude-homelab"
  218. },
  219. {
  220. "name": "linkding",
  221. "source": "./skills/linkding",
  222. "description": "Linkding bookmark management. Save, search, tag, and organize bookmarks.",
  223. "version": "1.0.0",
  224. "category": "utilities",
  225. "tags": ["linkding", "bookmarks", "homelab"],
  226. "homepage": "https://github.com/jmagar/claude-homelab"
  227. },
  228. {
  229. "name": "memos",
  230. "source": "./skills/memos",
  231. "description": "Memos note-taking service. Create, search, tag, and manage quick notes and memos.",
  232. "version": "1.0.0",
  233. "category": "utilities",
  234. "tags": ["memos", "notes", "homelab"],
  235. "homepage": "https://github.com/jmagar/claude-homelab"
  236. },
  237. {
  238. "name": "notebooklm",
  239. "source": "./skills/notebooklm",
  240. "description": "Google NotebookLM integration. Create notebooks, add sources, generate podcasts, videos, and research artifacts.",
  241. "version": "1.0.0",
  242. "category": "research",
  243. "tags": ["notebooklm", "research", "ai", "google"],
  244. "homepage": "https://github.com/jmagar/claude-homelab"
  245. },
  246. {
  247. "name": "paperless-ngx",
  248. "source": "./skills/paperless-ngx",
  249. "description": "Paperless-ngx document management. Upload, search, tag, and organize documents.",
  250. "version": "1.0.0",
  251. "category": "utilities",
  252. "tags": ["paperless", "documents", "ocr", "homelab"],
  253. "homepage": "https://github.com/jmagar/claude-homelab"
  254. },
  255. {
  256. "name": "plex",
  257. "source": "./skills/plex",
  258. "description": "Plex Media Server management. Browse libraries, search media, manage playlists, and monitor activity.",
  259. "version": "1.0.0",
  260. "category": "media",
  261. "tags": ["plex", "media", "streaming", "homelab"],
  262. "homepage": "https://github.com/jmagar/claude-homelab"
  263. },
  264. {
  265. "name": "prowlarr",
  266. "source": "./skills/prowlarr",
  267. "description": "Prowlarr indexer management. Add, configure, test, and search indexers.",
  268. "version": "1.0.0",
  269. "category": "media",
  270. "tags": ["prowlarr", "indexers", "search", "homelab"],
  271. "homepage": "https://github.com/jmagar/claude-homelab"
  272. },
  273. {
  274. "name": "qbittorrent",
  275. "source": "./skills/qbittorrent",
  276. "description": "qBittorrent download management. Add, monitor, pause, and manage torrent downloads.",
  277. "version": "1.0.0",
  278. "category": "downloads",
  279. "tags": ["qbittorrent", "torrents", "downloads", "homelab"],
  280. "homepage": "https://github.com/jmagar/claude-homelab"
  281. },
  282. {
  283. "name": "radarr",
  284. "source": "./skills/radarr",
  285. "description": "Radarr movie management. Search, add, monitor, and manage movie collections.",
  286. "version": "1.0.0",
  287. "category": "media",
  288. "tags": ["radarr", "movies", "media", "homelab"],
  289. "homepage": "https://github.com/jmagar/claude-homelab"
  290. },
  291. {
  292. "name": "radicale",
  293. "source": "./skills/radicale",
  294. "description": "Radicale CalDAV/CardDAV server management. Manage calendars, contacts, and address books.",
  295. "version": "1.0.0",
  296. "category": "utilities",
  297. "tags": ["radicale", "caldav", "carddav", "calendar", "homelab"],
  298. "homepage": "https://github.com/jmagar/claude-homelab"
  299. },
  300. {
  301. "name": "sabnzbd",
  302. "source": "./skills/sabnzbd",
  303. "description": "SABnzbd Usenet download management. Add, monitor, and manage NZB downloads.",
  304. "version": "1.0.0",
  305. "category": "downloads",
  306. "tags": ["sabnzbd", "usenet", "downloads", "homelab"],
  307. "homepage": "https://github.com/jmagar/claude-homelab"
  308. },
  309. {
  310. "name": "sonarr",
  311. "source": "./skills/sonarr",
  312. "description": "Sonarr TV series management. Search, add, monitor, and manage TV show collections.",
  313. "version": "1.0.0",
  314. "category": "media",
  315. "tags": ["sonarr", "tv", "series", "media", "homelab"],
  316. "homepage": "https://github.com/jmagar/claude-homelab"
  317. },
  318. {
  319. "name": "tailscale",
  320. "source": "./skills/tailscale",
  321. "description": "Tailscale VPN mesh network management. Monitor devices, manage routes, and check network status.",
  322. "version": "1.0.0",
  323. "category": "infrastructure",
  324. "tags": ["tailscale", "vpn", "networking", "homelab"],
  325. "homepage": "https://github.com/jmagar/claude-homelab"
  326. },
  327. {
  328. "name": "tautulli",
  329. "source": "./skills/tautulli",
  330. "description": "Tautulli Plex monitoring. View activity, history, statistics, and user analytics.",
  331. "version": "1.0.0",
  332. "category": "media",
  333. "tags": ["tautulli", "plex", "monitoring", "analytics", "homelab"],
  334. "homepage": "https://github.com/jmagar/claude-homelab"
  335. },
  336. {
  337. "name": "zfs",
  338. "source": "./skills/zfs",
  339. "description": "ZFS storage management. Monitor pools, datasets, snapshots, scrubs, and replication.",
  340. "version": "1.0.0",
  341. "category": "infrastructure",
  342. "tags": ["zfs", "storage", "snapshots", "homelab"],
  343. "homepage": "https://github.com/jmagar/claude-homelab"
  344. }
  345. ]
  346. }
README.md · README · 545 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Homelab
  2. Current release: 1.4.0.
  3. Homelab plugin hub for Claude Code, Codex, and Gemini. This repository is the source of truth for the `homelab-core` plugin, bundled skill-only integrations, agents, commands, and shared credential bootstrapping.
  4. ## Overview
  5. `claude-homelab` serves three roles at once:
  6. - The `homelab-core` plugin published through the Claude marketplace
  7. - The canonical mono-repo for 16 bundled skill-only service integrations
  8. - The source for Codex and Gemini extension manifests that mirror the same workflow surface
  9. The repo root is the plugin root. Do not edit generated copies in `~/.claude/` or `~/.claude/plugins/cache/` directly.
  10. ## Installation
  11. ### Claude marketplace
  12. ```bash
  13. /plugin marketplace add jmagar/claude-homelab
  14. /plugin install homelab-core @jmagar-claude-homelab
  15. ```
  16. After install, Claude Code downloads the plugin into `~/.claude/plugins/cache/`. No symlinks are created on this path.
  17. ### Bash / symlink install
  18. ```bash
  19. curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 31 on GitHub
  20. ```
  21. Or, if you already have the repo cloned:
  22. ```bash
  23. ./scripts/install.sh
  24. ```
  25. The installer:
  26. 1. Checks prerequisites (`git`, `jq`, `curl`)
  27. 2. Clones the repo to `~/claude-homelab` (or pulls if it exists)
  28. 3. Runs `setup-creds.sh` — creates `~/.claude-homelab/.env` from `.env.example` with `chmod 600`
  29. 4. Runs `setup-symlinks.sh` — symlinks skills, agents, and commands into `~/.claude/`
  30. 5. Runs `verify.sh` — confirms every symlink and required file is in place
  31. 6. Prints next steps
  32. ## Credential Model
  33. All credentials for every service live in a single file:
  34. ```
  35. ~/.claude-homelab/.env
  36. ```
  37. This file is created from `.env.example` at install time and is never committed. Set it up interactively after install:
  38. ```bash
  39. # Interactive wizard (preferred)
  40. # Open Claude Code and run:
  41. /homelab-core:setup
  42. # Or configure manually
  43. $EDITOR ~/.claude-homelab/.env
  44. ```
  45. Security requirements:
  46. - `~/.claude-homelab/.env` must have `chmod 600` (owner read/write only)
  47. - Never commit `.env` — it is gitignored
  48. - Never log credentials, even in debug mode
  49. - Use `.env.example` as the template (tracked in git, placeholder values only)
  50. All service scripts load credentials via `scripts/load-env.sh`:
  51. ```bash
  52. source "${CLAUDE_PLUGIN_ROOT:-$HOME/claude-homelab}/scripts/load-env.sh"
  53. load_env_file || exit 1
  54. validate_env_vars "SERVICE_URL" "SERVICE_API_KEY"
  55. ```
  56. ### Environment Variable Reference
  57. Variables are grouped by service. Copy `.env.example` to `~/.claude-homelab/.env` and replace placeholder values.
  58. #### Media
  59. | Variable | Required | Description |
  60. |---|---|---|
  61. | `PLEX_URL` | yes | Plex server base URL |
  62. | `PLEX_TOKEN` | yes | Plex authentication token |
  63. | `OVERSEERR_URL` | yes | Overseerr base URL (skill) |
  64. | `OVERSEERR_API_KEY` | yes | Overseerr API key (skill) |
  65. | `RADARR_URL` | yes | Radarr base URL |
  66. | `RADARR_API_KEY` | yes | Radarr API key |
  67. | `RADARR_DEFAULT_QUALITY_PROFILE` | no | Default quality profile ID (default: `1`) |
  68. | `SONARR_URL` | yes | Sonarr base URL |
  69. | `SONARR_API_KEY` | yes | Sonarr API key |
  70. | `SONARR_DEFAULT_QUALITY_PROFILE` | no | Default quality profile ID (default: `1`) |
  71. | `PROWLARR_URL` | yes | Prowlarr base URL |
  72. | `PROWLARR_API_KEY` | yes | Prowlarr API key |
  73. | `TAUTULLI_URL` | yes | Tautulli base URL |
  74. | `TAUTULLI_API_KEY` | yes | Tautulli API key |
  75. #### Downloads
  76. | Variable | Required | Description |
  77. |---|---|---|
  78. | `SABNZBD_URL` | yes | SABnzbd base URL |
  79. | `SABNZBD_API_KEY` | yes | SABnzbd API key |
  80. | `QBITTORRENT_URL` | yes | qBittorrent WebUI URL |
  81. | `QBITTORRENT_USERNAME` | yes | qBittorrent username |
  82. | `QBITTORRENT_PASSWORD` | yes | qBittorrent password |
  83. #### Infrastructure
  84. | Variable | Required | Description |
  85. |---|---|---|
  86. | `UNRAID_SERVER1_NAME` | yes | Display name for first Unraid server |
  87. | `UNRAID_SERVER1_URL` | yes | Unraid GraphQL endpoint (skill) |
  88. | `UNRAID_SERVER1_API_KEY` | yes | Unraid API key (skill) |
  89. | `UNRAID_SERVER2_NAME` | no | Display name for second Unraid server |
  90. | `UNRAID_SERVER2_URL` | no | Second Unraid GraphQL endpoint |
  91. | `UNRAID_SERVER2_API_KEY` | no | Second Unraid API key |
  92. | `UNIFI_URL` | yes | UniFi controller URL (skill) |
  93. | `UNIFI_USERNAME` | yes | UniFi username |
  94. | `UNIFI_PASSWORD` | yes | UniFi password |
  95. | `UNIFI_SITE` | no | UniFi site name (default: `default`) |
  96. | `TAILSCALE_API_KEY` | yes | Tailscale API key |
  97. | `TAILSCALE_TAILNET` | yes | Tailscale tailnet name or `-` |
  98. | `ZFS_HOST` | yes | Host where ZFS commands run |
  99. | `SWAG_HOST` | yes | SWAG reverse proxy host |
  100. | `SWAG_CONTAINER_NAME` | no | SWAG container name (default: `swag`) |
  101. | `SWAG_APPDATA_PATH` | no | SWAG appdata path |
  102. | `SWAG_COMPOSE_PATH` | no | SWAG compose file path |
  103. #### Utilities and Document Management
  104. | Variable | Required | Description |
  105. |---|---|---|
  106. | `LINKDING_URL` | yes | Linkding bookmark manager URL |
  107. | `LINKDING_API_KEY` | yes | Linkding API token |
  108. | `MEMOS_URL` | yes | Memos server URL |
  109. | `MEMOS_API_TOKEN` | yes | Memos API token |
  110. | `BYTESTASH_URL` | yes | ByteStash snippet manager URL |
  111. | `BYTESTASH_API_KEY` | yes | ByteStash API key |
  112. | `PAPERLESS_URL` | yes | Paperless-ngx base URL |
  113. | `PAPERLESS_API_TOKEN` | yes | Paperless-ngx API token |
  114. | `RADICALE_URL` | yes | Radicale CalDAV/CardDAV URL |
  115. | `RADICALE_USERNAME` | yes | Radicale username |
  116. | `RADICALE_PASSWORD` | yes | Radicale password |
  117. | `GOTIFY_URL` | yes | Gotify push notification URL (skill) |
  118. | `GOTIFY_TOKEN` | yes | Gotify app token (skill) |
  119. #### Research and Dev Tools
  120. | Variable | Required | Description |
  121. |---|---|---|
  122. | `NOTEBOOKLM_COOKIE` | yes | NotebookLM session cookie |
  123. | `NOTEBOOKLM_AUTH_JSON` | no | Full auth JSON blob (alternative to cookie) |
  124. | `NOTEBOOKLM_LOG_LEVEL` | no | Log verbosity (default: `INFO`) |
  125. | `GITHUB_TOKEN` | yes | GitHub personal access token (gh-address-comments) |
  126. | `GLANCES_URL` | no | Glances web interface URL |
  127. | `GLANCES_USERNAME` | no | Glances username (if auth enabled) |
  128. | `GLANCES_PASSWORD` | no | Glances password (if auth enabled) |
  129. #### MCP Server Variables
  130. Each external MCP plugin has its own block of server-config vars. See `.env.example` for the full list. Key patterns:
  131. | Pattern | Description |
  132. |---|---|
  133. | `*_MCP_TOKEN` | Bearer token for MCP server auth |
  134. | `*_MCP_HOST` | Bind host (default: `0.0.0.0`) |
  135. | `*_MCP_PORT` | Listen port |
  136. | `*_MCP_TRANSPORT` | Transport protocol (`streamable-http` or `http`) |
  137. | `*_MCP_NO_AUTH` | Disable auth (set `true` for local-only installs) |
  138. | `*_MCP_ALLOW_DESTRUCTIVE` | Allow destructive operations (default: `false`) |
  139. | `ALLOW_DESTRUCTIVE` | Shared fallback for MCP repos that read this directly |
  140. | `ALLOW_YOLO` | Shared fallback — skip confirmation prompts |
  141. | `DOCKER_NETWORK` | Shared Docker network name |
  142. | `LOG_LEVEL` | Shared log verbosity |
  143. ## Commands
  144. ### Root Commands
  145. | Command | Argument | Description |
  146. |---|---|---|
  147. | `/check` | `[instructions]` | Read the latest screenshot from `~/Pictures/Screenshots` and describe it. Pass optional instructions (e.g., "extract the text", "what error is shown"). |
  148. | `/deploy` | `[plugin-name]` | Build and start MCP plugin containers via `docker compose up --build -d`. Deploys all external plugins by default. Pass a plugin name to deploy only that one. Reads compose files from `~/.claude/plugins/cache/claude-homelab/<name>/<version>/`. Skips `tests/` subdirs. Reports a status table with notes on failures. |
  149. | `/quick-push` | — | Standardized commit-and-push workflow. Checks branch (creates feature branch if on main), bumps version in all manifests, updates `CHANGELOG.md`, stages all changes, commits with co-authorship signature, pushes, then invokes `save-to-md` and writes Neo4j commit graph entries. |
  150. | `/save-to-md` | `[output-path]` | Document the full session as a Markdown file. Defaults to `docs/sessions/YYYY-MM-DD-description.md`. Creates Neo4j entities and relations for files, services, features, and bugs touched in the session. |
  151. | `/validate-plan` | `<plan-file-or-text>` | Audit a technical implementation plan against homelab standards. Checks for exposed secrets, correct credential loading pattern (`scripts/load-env.sh`), required docs (`README.md`, `SKILL.md`, references), `confirm=True` gate on destructive actions, and standard directory structure. Outputs a compliance table and required changes list. |
  152. ### `/homelab:*` Commands
  153. | Command | Description |
  154. |---|---|
  155. | `/homelab:system-resources` | Snapshot CPU, RAM, temperatures, and load average. Identifies high-CPU processes, memory pressure, temperature anomalies, and provides optimization recommendations. Uses `uptime`, `free`, `top`, and `sensors`. |
  156. | `/homelab:docker-health` | Audit all Docker containers. Flags unexpected exits, restart loops, unhealthy containers, and resource over-use (CPU > 80%, memory > 90%). Provides per-container recommendations. |
  157. | `/homelab:disk-space` | Analyze disk usage across all mount points. Identifies filesystems above 80% or 95% usage, space hogs, log rotation issues, Docker volume orphans, and suggests cleanup targets. |
  158. | `/homelab:zfs-health` | Full ZFS health check. Reports pool state (ONLINE/DEGRADED/FAULTED), device errors, checksum errors, resilvering, scrub status, ARC hit ratio, snapshot accumulation, and per-dataset usage. Outputs a health score and prioritized action list. |
  159. ### `/notebooklm:*` Commands
  160. | Command | Argument | Description |
  161. |---|---|---|
  162. | `/notebooklm:create` | `"Title" [url1] [url2] ...` | Create a new NotebookLM notebook. Optionally add URLs, PDFs, Google Docs, YouTube links, audio, video, or image files as sources. Reports the new notebook ID. |
  163. | `/notebooklm:ask` | `"question"` | Chat with NotebookLM about the current notebook. Options: `--json` for source citations, `-n <id>` to target a specific notebook. |
  164. | `/notebooklm:source` | `add <url\|file> \| list \| wait <id> \| fulltext <id> \| add-research "query"` | Manage notebook sources. Add a URL or file, list current sources, wait for a source to finish processing, retrieve full text, or trigger web research. Supports `-n <id>` for targeting. |
  165. | `/notebooklm:generate` | `<type> ["instructions"]` | Generate an artifact. Types: `audio`, `video`, `quiz`, `report`, `mind-map`, `flashcards`, `slide-deck`, `infographic`, `data-table`. Each type has format, length, style, and difficulty options. |
  166. | `/notebooklm:download` | `<type> [output-path]` | Download a generated artifact to a local file. Supports `--all` and `--format json\|md\|html`. Artifact must be fully generated first. |
  167. | `/notebooklm:list` | `[notebooks\|sources\|artifacts]` | List notebooks (default), sources in the current notebook, or generated artifacts. Presents results in a table with IDs, names, and status. |
  168. | `/notebooklm:research` | `"query" [--mode fast\|deep]` | Run web research and import results as notebook sources. Fast mode: 30 seconds to 2 minutes. Deep mode: 15 to 30+ minutes, use `--no-wait` and follow up with `notebooklm research wait --import-all`. |
  169. #### `/notebooklm:generate` Type Reference
  170. | Type | Key Options | Approximate Time |
  171. |---|---|---|
  172. | `audio` (podcast) | `--format deep-dive\|brief\|critique\|debate`, `--length short\|default\|long` | 10–20 min |
  173. | `video` | `--format explainer\|brief`, `--style auto\|classic\|whiteboard\|kawaii\|...` | 15–45 min |
  174. | `slide-deck` | `--format detailed\|presenter`, `--length default\|short` | 5–15 min |
  175. | `infographic` | `--orientation landscape\|portrait\|square`, `--detail concise\|standard\|detailed` | 5–15 min |
  176. | `report` | `--format briefing-doc\|study-guide\|blog-post\|custom` | 5–15 min |
  177. | `mind-map` | — | Instant |
  178. | `data-table` | description required | 5–15 min |
  179. | `quiz` | `--difficulty easy\|medium\|hard`, `--quantity fewer\|standard\|more` | 5–15 min |
  180. | `flashcards` | `--difficulty easy\|medium\|hard`, `--quantity fewer\|standard\|more` | 5–15 min |
  181. All types support `-s/--source`, `--language`, `--json`, and `--retry N`.
  182. ## Skills
  183. 18 skill directories live under `skills/`. Each is an independent unit with a `SKILL.md` (Claude-facing) and typically a `README.md`, `scripts/`, and `references/` directory.
  184. ### Core Skills (2)
  185. | Skill | Invocation | Purpose |
  186. |---|---|---|
  187. | `homelab-setup` | `/homelab-core:setup` | Interactive credential setup wizard. Guides through configuring `~/.claude-homelab/.env` for each service the user runs. Creates the file from `.env.example` if missing. |
  188. | `homelab-health` | `/homelab-core:health` | Unified service health dashboard. Runs `scripts/check-health.sh` to curl-check every configured service and outputs a JSON health summary. |
  189. ### Service Skills (16)
  190. | Skill | Category | Purpose |
  191. |---|---|---|
  192. | `plex` | media | Browse Plex libraries, search media, check active sessions and streams, view recently added content |
  193. | `radarr` | media | Manage Radarr movie library — search, add, monitor, and track download status |
  194. | `sonarr` | media | Manage Sonarr TV library — search, add series, monitor seasons and episodes |
  195. | `prowlarr` | media | Manage Prowlarr indexers — search across all indexers, test connectivity, view stats |
  196. | `tautulli` | media | Query Tautulli play history, user activity, library stats, and notification logs |
  197. | `sabnzbd` | downloads | Monitor SABnzbd queue, speed, and history; manage download jobs |
  198. | `qbittorrent` | downloads | Manage qBittorrent torrents — list, add, pause, resume, and remove downloads |
  199. | `tailscale` | infrastructure | Query Tailscale network status, list devices, check connectivity, and manage ACLs |
  200. | `zfs` | infrastructure | ZFS pool and dataset management — status, snapshots, scrubs, and space reporting |
  201. | `linkding` | utilities | Manage Linkding bookmarks — search, add, tag, and organize saved links |
  202. | `memos` | utilities | Create and query Memos notes — add quick notes, search by tag or content |
  203. | `bytestash` | utilities | Manage ByteStash code snippets — save, search, and retrieve frequently-used code |
  204. | `paperless-ngx` | utilities | Search and manage Paperless-ngx document archive — query by content, tag, or correspondent |
  205. | `radicale` | utilities | Interact with Radicale CalDAV/CardDAV — list calendars and contacts, query events |
  206. | `notebooklm` | research | NotebookLM CLI wrapper for deep AI research, source management, Q&A, and artifact generation |
  207. | `gh-address-comments` | dev-tools | Address GitHub PR review comments — fetch, triage, and resolve review feedback |
  208. ## Agents
  209. ### `notebooklm-specialist`
  210. **File:** `agents/notebooklm-specialist.md`
  211. **Color:** magenta
  212. **Tools:** `Bash`, `Read`, `Write`, `SendMessage`
  213. **Memory:** user (persistent across sessions)
  214. The `notebooklm-specialist` is a research analyst agent for deep AI-powered research workflows. It is spawned by an orchestrator with a pre-created notebook ID, output directory, and research brief. The agent:
  215. 1. Starts deep web research immediately (`notebooklm source add-research --mode deep --no-wait`) — this is always the first action since it takes 15–30+ minutes
  216. 2. Adds source URLs relayed from the orchestrator as they arrive (max 50 per notebook)
  217. 3. Waits for deep research to complete and auto-imports discovered sources
  218. 4. Conducts an extensive Q&A session (10–20 questions across overview, comparison, technical, critical, practical, and future-directions categories)
  219. 5. Uses `--json` flag to capture citation data with every answer
  220. 6. Writes findings to `{output_dir}/findings/notebooklm-findings.md`
  221. 7. Signals completion to the orchestrator via `SendMessage`
  222. **Critical constraint:** Always use `-n <notebook_id>` or `--notebook <notebook_id>`. Never use `notebooklm use <id>` — that command modifies shared state and is unsafe in parallel workflows.
  223. The agent maintains persistent memory of effective research query patterns, timing benchmarks, and NotebookLM-specific quirks across sessions.
  224. ## Marketplace Scope
  225. The `.claude-plugin/marketplace.json` catalog covers 27 plugins total.
  226. ### 1 core plugin
  227. | Plugin | Source | Description |
  228. |---|---|---|
  229. | `homelab-core` | this repo | Agents, commands, setup/health skills, and the bundled skill library |
  230. ### 10 external MCP repos
  231. | Plugin | Repo | Category |
  232. |---|---|---|
  233. | `overseerr-mcp` | `jmagar/overseerr-mcp` | media |
  234. | `unraid-mcp` | `jmagar/unraid-mcp` | infrastructure |
  235. | `unifi-mcp` | `jmagar/unifi-mcp` | infrastructure |
  236. | `gotify-mcp` | `jmagar/gotify-mcp` | utilities |
  237. | `swag-mcp` | `jmagar/swag-mcp` | infrastructure |
  238. | `synapse-mcp` | `jmagar/synapse-mcp` | infrastructure |
  239. | `arcane-mcp` | `jmagar/arcane-mcp` | infrastructure |
  240. | `syslog-mcp` | `jmagar/syslog-mcp` | infrastructure |
  241. | `plugin-lab` | `jmagar/plugin-lab` | dev-tools |
  242. ### 16 bundled skill-only plugins
  243. `bytestash`, `gh-address-comments`, `linkding`, `memos`, `notebooklm`, `paperless-ngx`, `plex`, `prowlarr`, `qbittorrent`, `radarr`, `radicale`, `sabnzbd`, `sonarr`, `tailscale`, `tautulli`, `zfs`
  244. These are listed individually in the marketplace catalog so users can discover them, but they are sourced from `./skills/*` within this repo. A bundled skill graduates to its own external repo when it gains additional plugin surface area (agents, commands, hooks, MCP servers, output styles, or channels).
  245. ## Symlink Architecture
  246. The bash install path creates symlinks from this repo into `~/.claude/` so Claude Code discovers all skills, agents, and commands. The plugin path uses `~/.claude/plugins/cache/` instead and requires no symlinks.
  247. ```
  248. ~/.claude/
  249. ├── agents/
  250. │ └── notebooklm-specialist.md → ~/claude-homelab/agents/notebooklm-specialist.md
  251. ├── skills/
  252. │ ├── bytestash/ → ~/claude-homelab/skills/bytestash/
  253. │ ├── gh-address-comments/ → ~/claude-homelab/skills/gh-address-comments/
  254. │ ├── homelab-health/ → ~/claude-homelab/skills/homelab-health/
  255. │ ├── homelab-setup/ → ~/claude-homelab/skills/homelab-setup/
  256. │ ├── linkding/ → ~/claude-homelab/skills/linkding/
  257. │ ├── memos/ → ~/claude-homelab/skills/memos/
  258. │ ├── notebooklm/ → ~/claude-homelab/skills/notebooklm/
  259. │ ├── paperless-ngx/ → ~/claude-homelab/skills/paperless-ngx/
  260. │ ├── plex/ → ~/claude-homelab/skills/plex/
  261. │ ├── prowlarr/ → ~/claude-homelab/skills/prowlarr/
  262. │ ├── qbittorrent/ → ~/claude-homelab/skills/qbittorrent/
  263. │ ├── radarr/ → ~/claude-homelab/skills/radarr/
  264. │ ├── radicale/ → ~/claude-homelab/skills/radicale/
  265. │ ├── sabnzbd/ → ~/claude-homelab/skills/sabnzbd/
  266. │ ├── sonarr/ → ~/claude-homelab/skills/sonarr/
  267. │ ├── tailscale/ → ~/claude-homelab/skills/tailscale/
  268. │ ├── tautulli/ → ~/claude-homelab/skills/tautulli/
  269. │ └── zfs/ → ~/claude-homelab/skills/zfs/
  270. └── commands/
  271. ├── check.md → ~/claude-homelab/commands/check.md
  272. ├── deploy.md → ~/claude-homelab/commands/deploy.md
  273. ├── quick-push.md → ~/claude-homelab/commands/quick-push.md
  274. ├── save-to-md.md → ~/claude-homelab/commands/save-to-md.md
  275. ├── validate-plan.md → ~/claude-homelab/commands/validate-plan.md
  276. ├── homelab/ → ~/claude-homelab/commands/homelab/
  277. └── notebooklm/ → ~/claude-homelab/commands/notebooklm/
  278. ~/.claude-homelab/
  279. ├── .env # Credentials (chmod 600, never committed)
  280. └── load-env.sh # Copied from scripts/load-env.sh at install
  281. ```
  282. ### How Slash Commands Work
  283. Slash commands are created by placing `.md` files in `~/.claude/commands/`. Claude Code discovers them automatically.
  284. - `commands/proxy.md` → `/proxy`
  285. - `commands/homelab/docker-health.md` → `/homelab:docker-health`
  286. The directory name becomes the namespace prefix. The file name becomes the command after the colon.
  287. ## Configuration System
  288. ### Command Files (`commands/`)
  289. Each command is a Markdown file with a YAML frontmatter block:
  290. ```yaml
  291. ---
  292. description: Short description shown in autocomplete
  293. argument-hint: <required> [optional]
  294. allowed-tools: Bash(tool:*), mcp__plugin_name__tool
  295. ---
  296. Task instruction using $ARGUMENTS
  297. ```
  298. Key fields:
  299. - `description` — shown in autocomplete menu
  300. - `argument-hint` — hint text for expected arguments
  301. - `allowed-tools` — pre-approved tools (no permission prompts at runtime)
  302. - `$ARGUMENTS` — replaced with user input after the command name
  303. - `` !`command` `` — dynamic context injection: runs the shell command and injects its output at load time
  304. ### Prompts Sidecar System (`prompts/`)
  305. Command prompt bodies can be extracted to `.toml` sidecar files in `prompts/`, keeping command metadata (frontmatter, description) separate from the prompt content. When populated, the directory mirrors the `commands/` structure:
  306. - `prompts/check.toml` — prompt body for `/check`
  307. - `prompts/homelab/docker-health.toml` — prompt body for `/homelab:docker-health`
  308. Format:
  309. ```toml
  310. name = "command-name"
  311. description = "Short description"
  312. prompt = """
  313. Prompt body with instructions and dynamic context injection.
  314. """
  315. ```
  316. The `prompts/` directory is not present by default. Create it if you extract prompts out of command `.md` files.
  317. ### Output Styles (`output-styles/`)
  318. The `output-styles/` directory is reserved for custom response format definitions. It is currently empty (`.gitkeep` placeholder). Add output style files here when commands need to enforce a specific response structure.
  319. ## Development
  320. ### Adding a New Service Skill
  321. 1. Create the skill directory:
  322. ```bash
  323. mkdir -p skills/service-name/{scripts,references,examples}
  324. ```
  325. 2. Create `SKILL.md` with frontmatter (`name`, `description`), a mandatory invocation section, command documentation, and workflow decision trees.
  326. 3. Create `README.md` for user-facing setup instructions.
  327. 4. Implement scripts in `scripts/`. All scripts must:
  328. - Use `source "$REPO_ROOT/scripts/load-env.sh"` for credentials
  329. - Return JSON output
  330. - Handle errors gracefully
  331. - Support `--help`
  332. 5. Add reference docs in `references/` (`api-endpoints.md`, `quick-reference.md`, `troubleshooting.md`).
  333. 6. Create the symlink (bash path):
  334. ```bash
  335. ln -sf ~/claude-homelab/skills/service-name ~/.claude/skills/service-name
  336. ```
  337. Or re-run `./scripts/setup-symlinks.sh` to pick it up automatically.
  338. 7. Add the skill to the marketplace catalog if it should be discoverable:
  339. - Edit `.claude-plugin/marketplace.json`
  340. - Add a `bundled` entry pointing to `./skills/service-name`
  341. 8. Update this README's Skills table.
  342. ### Adding a New Command
  343. Single command (`/new-command`):
  344. ```bash
  345. touch commands/new-command.md
  346. ln -sf ~/claude-homelab/commands/new-command.md ~/.claude/commands/new-command.md
  347. ```
  348. Namespaced command (`/service:action`):
  349. ```bash
  350. mkdir -p commands/service-name
  351. touch commands/service-name/action.md
  352. ln -sf ~/claude-homelab/commands/service-name ~/.claude/commands/service-name
  353. ```
  354. ### Credential Pattern
  355. All scripts must source `scripts/load-env.sh` (see [Credential Model](#credential-model) above for the full pattern and variable naming conventions).
  356. ## Verification
  357. Run after any structural change:
  358. ```bash
  359. ./scripts/verify.sh
  360. ```
  361. The verify script checks:
  362. - All required symlinks exist and point to valid targets
  363. - `~/.claude-homelab/.env` exists
  364. Additional checks:
  365. ```bash
  366. # Run all Justfile validation targets
  367. just validate
  368. # Spot-check section headers across key docs
  369. rtk rg -n "^## " README.md AGENTS.md CLAUDE.md
  370. ```
  371. ## Repository Layout
  372. ```
  373. agents/ Top-level specialist agents
  374. commands/ Slash command definitions (.md files)
  375. commands/homelab/ /homelab:* command definitions
  376. commands/notebooklm/ /notebooklm:* command definitions
  377. docs/ Session logs and reference documentation
  378. docs/references/ Shared reference docs (security-patterns.md)
  379. hooks/ Reserved for future Claude Code hook definitions
  380. output-styles/ Reserved for custom response format definitions
  381. scripts/ Install, setup, credential loading, and verification helpers
  382. skills/ 18 service and core skill directories
  383. .claude-plugin/ Claude marketplace manifest (plugin.json, marketplace.json)
  384. .codex-plugin/ Codex plugin manifest
  385. gemini-extension.json Gemini extension manifest
  386. AGENTS.md Repo-wide development instructions
  387. CLAUDE.md Claude-facing project instructions
  388. CHANGELOG.md Release history
  389. .env.example Shared credential template (tracked, no secrets)
  390. Justfile Validation and maintenance recipes
  391. ```
  392. ## Related Files
  393. - `AGENTS.md` — canonical development and repo-structure guidance
  394. - `CLAUDE.md` — Claude-facing project instructions including symlink architecture, command format, and skill development workflow
  395. - `.env.example` — shared credential template for all 16 services and 10 MCP repos
  396. - `.claude-plugin/marketplace.json` — marketplace source of truth (27 plugin entries)
  397. - `.claude-plugin/plugin.json` — `homelab-core` plugin manifest
  398. - `CHANGELOG.md` — release history
  399. - `docs/references/security-patterns.md` — reusable patterns for input sanitization, injection prevention, and API key protection
  400. ## Related plugins
  401. | Plugin | Category | Description |
  402. |--------|----------|-------------|
  403. | [overseerr-mcp](https://github.com/jmagar/overseerr-mcp) | media | Search movies and TV shows, submit requests, and monitor failed requests via Overseerr. |
  404. | [unraid-mcp](https://github.com/jmagar/unraid-mcp) | infrastructure | Query, monitor, and manage Unraid servers: Docker, VMs, array, parity, and live telemetry. |
  405. | [unifi-mcp](https://github.com/jmagar/unifi-mcp) | infrastructure | Monitor and manage UniFi devices, clients, firewall rules, and network health. |
  406. | [gotify-mcp](https://github.com/jmagar/gotify-mcp) | utilities | Send and manage push notifications via a self-hosted Gotify server. |
  407. | [swag-mcp](https://github.com/jmagar/swag-mcp) | infrastructure | Create, edit, and manage SWAG nginx reverse proxy configurations. |
  408. | [synapse-mcp](https://github.com/jmagar/synapse-mcp) | infrastructure | Docker management (Flux) and SSH remote operations (Scout) across homelab hosts. |
  409. | [arcane-mcp](https://github.com/jmagar/arcane-mcp) | infrastructure | Manage Docker environments, containers, images, volumes, networks, and GitOps via Arcane. |
  410. | [syslog-mcp](https://github.com/jmagar/syslog-mcp) | infrastructure | Receive, index, and search syslog streams from all homelab hosts via SQLite FTS5. |
  411. | [plugin-lab](https://github.com/jmagar/plugin-lab) | dev-tools | Scaffold, review, align, and deploy homelab MCP plugins with agents and canonical templates. |
  412. ## License
  413. MIT
scripts/install.sh · Bundled script · 148 lines · 1 finding marked
  1. #!/bin/bash
  2. # =============================================================================
  3. # Claude Homelab Installer
  4. # =============================================================================
  5. # One-liner: curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 5 on GitHub
  6. #
  7. # What this does:
  8. # 1. Checks prerequisites (git, jq, curl)
  9. # 2. Clones repo to ~/claude-homelab (or git pull if it exists)
  10. # 3. Runs setup-creds.sh (creates ~/.claude-homelab/.env with chmod 600)
  11. # 4. Runs setup-symlinks.sh (symlinks service-plugins/agents/commands into ~/.claude/)
  12. # 5. Runs verify.sh (confirms everything is in place)
  13. # 6. Prints next steps
  14. #
  15. # Non-interactive — safe for curl | bash (no read -p prompts)
  16. # =============================================================================
  17. set -euo pipefail
  18. # Colors
  19. RED='\033[0;31m'
  20. GREEN='\033[0;32m'
  21. YELLOW='\033[1;33m'
  22. BLUE='\033[0;34m'
  23. NC='\033[0m'
  24. REPO_URL="https://github.com/jmagar/claude-homelab.git"
  25. INSTALL_DIR="$HOME/claude-homelab"
  26. HOMELAB_DIR="$HOME/.claude-homelab"
  27. log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
  28. log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
  29. log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
  30. log_error() { echo -e "${RED}[ERR]${NC} $1"; }
  31. # -------------------------------------------------------------------
  32. # Step 1: Check prerequisites
  33. # -------------------------------------------------------------------
  34. check_prereqs() {
  35. local missing=()
  36. for cmd in git jq curl; do
  37. if ! command -v "$cmd" &>/dev/null; then
  38. missing+=("$cmd")
  39. fi
  40. done
  41. if [[ ${#missing[@]} -gt 0 ]]; then
  42. log_error "Missing required tools: ${missing[*]}"
  43. echo "Install them first, then re-run this script."
  44. exit 1
  45. fi
  46. log_success "Prerequisites met (git, jq, curl)"
  47. }
  48. # -------------------------------------------------------------------
  49. # Step 2: Clone or update repo
  50. # -------------------------------------------------------------------
  51. clone_or_pull() {
  52. if [[ -d "$INSTALL_DIR/.git" ]]; then
  53. log_info "Repository already exists at $INSTALL_DIR — pulling latest..."
  54. git -C "$INSTALL_DIR" pull --ff-only || {
  55. log_warn "git pull failed (you may have local changes). Continuing with existing checkout."
  56. }
  57. else
  58. if [[ -e "$INSTALL_DIR" ]]; then
  59. log_error "$INSTALL_DIR exists but is not a git repo. Move or remove it first."
  60. exit 1
  61. fi
  62. log_info "Cloning claude-homelab to $INSTALL_DIR..."
  63. git clone "$REPO_URL" "$INSTALL_DIR"
  64. fi
  65. log_success "Repository ready at $INSTALL_DIR"
  66. }
  67. # -------------------------------------------------------------------
  68. # Step 3: Set up credentials
  69. # -------------------------------------------------------------------
  70. run_setup_creds() {
  71. local script="$INSTALL_DIR/scripts/setup-creds.sh"
  72. if [[ ! -f "$script" ]]; then
  73. log_error "setup-creds.sh not found at $script"
  74. exit 1
  75. fi
  76. chmod +x "$script"
  77. log_info "Setting up credentials..."
  78. bash "$script"
  79. }
  80. # -------------------------------------------------------------------
  81. # Step 4: Run setup-symlinks.sh
  82. # -------------------------------------------------------------------
  83. run_symlinks() {
  84. local script="$INSTALL_DIR/scripts/setup-symlinks.sh"
  85. if [[ ! -f "$script" ]]; then
  86. log_error "setup-symlinks.sh not found at $script"
  87. exit 1
  88. fi
  89. chmod +x "$script"
  90. log_info "Running setup-symlinks.sh..."
  91. bash "$script"
  92. }
  93. # -------------------------------------------------------------------
  94. # Step 5: Verify
  95. # -------------------------------------------------------------------
  96. run_verify() {
  97. local script="$INSTALL_DIR/scripts/verify.sh"
  98. if [[ -f "$script" ]]; then
  99. chmod +x "$script"
  100. log_info "Verifying installation..."
  101. bash "$script" || log_warn "Verification had warnings — see above"
  102. fi
  103. }
  104. # -------------------------------------------------------------------
  105. # Step 6: Print next steps
  106. # -------------------------------------------------------------------
  107. print_next_steps() {
  108. echo ""
  109. echo -e "${GREEN}=== Installation Complete ===${NC}"
  110. echo ""
  111. echo "Next steps:"
  112. echo ""
  113. echo -e " 1. ${YELLOW}Configure credentials (interactive wizard):${NC}"
  114. echo " Open Claude Code and run: /homelab-core:setup"
  115. echo ""
  116. echo -e " Or edit manually: \$EDITOR ~/.claude-homelab/.env"
  117. echo ""
  118. echo -e " 2. ${YELLOW}Restart Claude Code${NC} to pick up the new skills"
  119. echo ""
  120. echo -e " 3. ${YELLOW}Check service health:${NC}"
  121. echo " /homelab-core:health"
  122. echo ""
  123. }
  124. # -------------------------------------------------------------------
  125. # Main
  126. # -------------------------------------------------------------------
  127. echo ""
  128. echo -e "${BLUE}=== Claude Homelab Installer ===${NC}"
  129. echo ""
  130. check_prereqs
  131. clone_or_pull
  132. run_setup_creds
  133. run_symlinks
  134. run_verify
  135. print_next_steps
scripts/verify.sh · Bundled script · 200 lines · 1 finding marked
  1. #!/bin/bash
  2. # =============================================================================
  3. # Verify Claude Homelab Installation
  4. # =============================================================================
  5. # Works for both bash path (symlinks) and plugin path (Claude Code cache).
  6. # Exits 0 if healthy, 1 if critical issues found.
  7. # =============================================================================
  8. set -uo pipefail
  9. RED='\033[0;31m'
  10. GREEN='\033[0;32m'
  11. YELLOW='\033[1;33m'
  12. BLUE='\033[0;34m'
  13. NC='\033[0m'
  14. ok=0
  15. warn=0
  16. err=0
  17. log_ok() { echo -e " ${GREEN}✓${NC} $1"; ((ok++)); }
  18. log_warn() { echo -e " ${YELLOW}⚠${NC} $1"; ((warn++)); }
  19. log_err() { echo -e " ${RED}✗${NC} $1"; ((err++)); }
  20. log_head() { echo ""; echo -e "${BLUE}$1${NC}"; }
  21. REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
  22. HOMELAB_DIR="$HOME/.claude-homelab"
  23. CLAUDE_DIR="$HOME/.claude"
  24. echo ""
  25. echo -e "${BLUE}=== Claude Homelab — Verification ===${NC}"
  26. # -------------------------------------------------------------------
  27. # 1. Credentials
  28. # -------------------------------------------------------------------
  29. log_head "Credentials"
  30. if [[ -f "$HOMELAB_DIR/.env" ]]; then
  31. perm=$(stat -c "%a" "$HOMELAB_DIR/.env" 2>/dev/null || stat -f "%Lp" "$HOMELAB_DIR/.env" 2>/dev/null)
  32. if [[ "$perm" == "600" ]]; then
  33. log_ok ".env exists with correct permissions (600)"
  34. else
  35. log_warn ".env exists but permissions are $perm (should be 600) — run: chmod 600 $HOMELAB_DIR/.env"
  36. fi
  37. if [[ -s "$HOMELAB_DIR/.env" ]]; then
  38. configured=$(grep -c "=.\+" "$HOMELAB_DIR/.env" 2>/dev/null || echo 0)
  39. log_ok "$configured credential lines configured"
  40. else
  41. log_warn ".env is empty — run /homelab-core:setup in Claude Code"
  42. fi
  43. else
  44. log_err ".env missing — run: curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/setup-creds.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 52 on GitHub
  45. fi
  46. if [[ -f "$HOMELAB_DIR/load-env.sh" ]]; then
  47. log_ok "load-env.sh installed at $HOMELAB_DIR/load-env.sh"
  48. else
  49. log_warn "load-env.sh missing — run setup-symlinks.sh"
  50. fi
  51. # -------------------------------------------------------------------
  52. # 2. Bash path — symlinks
  53. # -------------------------------------------------------------------
  54. log_head "Bash Path (symlinks)"
  55. if [[ -d "$CLAUDE_DIR/skills" ]]; then
  56. skill_count=$(find "$CLAUDE_DIR/skills" -maxdepth 1 -type l 2>/dev/null | wc -l)
  57. broken=$(find "$CLAUDE_DIR/skills" -maxdepth 1 -type l ! -e 2>/dev/null | wc -l)
  58. if [[ "$broken" -gt 0 ]]; then
  59. log_warn "$skill_count skill symlinks ($broken broken) — re-run: $REPO_ROOT/scripts/setup-symlinks.sh"
  60. find "$CLAUDE_DIR/skills" -maxdepth 1 -type l ! -e 2>/dev/null | while read -r s; do
  61. echo " broken: $s"
  62. done
  63. else
  64. log_ok "$skill_count skill symlinks (all valid)"
  65. fi
  66. else
  67. log_warn "~/.claude/skills/ missing — run setup-symlinks.sh"
  68. fi
  69. if [[ -d "$CLAUDE_DIR/agents" ]]; then
  70. agent_count=$(find "$CLAUDE_DIR/agents" -maxdepth 1 -type l 2>/dev/null | wc -l)
  71. log_ok "$agent_count agent symlinks"
  72. else
  73. log_warn "~/.claude/agents/ missing"
  74. fi
  75. if [[ -d "$CLAUDE_DIR/commands" ]]; then
  76. cmd_count=$(find "$CLAUDE_DIR/commands" -maxdepth 1 \( -type l -o -type f \) -name "*.md" 2>/dev/null | wc -l)
  77. log_ok "$cmd_count command files"
  78. else
  79. log_warn "~/.claude/commands/ missing"
  80. fi
  81. # -------------------------------------------------------------------
  82. # 3. Plugin path — marketplace + plugin.json
  83. # -------------------------------------------------------------------
  84. log_head "Plugin Path"
  85. if [[ -f "$REPO_ROOT/.claude-plugin/marketplace.json" ]]; then
  86. plugin_count=$(jq '.plugins | length' "$REPO_ROOT/.claude-plugin/marketplace.json" 2>/dev/null || echo "?")
  87. log_ok "marketplace.json valid ($plugin_count plugins listed)"
  88. # Verify local source paths exist; GitHub-backed sources are not local directories.
  89. dead=0
  90. while IFS=$'\t' read -r name source_type source_value; do
  91. if [[ "$source_type" == "string" ]]; then
  92. src="${source_value#./}"
  93. full_path="$REPO_ROOT/$src"
  94. if [[ ! -d "$full_path" && "$source_value" != "./" ]]; then
  95. log_warn "Dead marketplace entry ($name): $source_value"
  96. ((dead++))
  97. fi
  98. fi
  99. done < <(
  100. jq -r '
  101. .plugins[]
  102. | [
  103. .name,
  104. (.source | type),
  105. (if (.source | type) == "string" then .source else .source.repo end)
  106. ]
  107. | @tsv
  108. ' "$REPO_ROOT/.claude-plugin/marketplace.json" 2>/dev/null
  109. )
  110. [[ "$dead" -eq 0 ]] && log_ok "All marketplace source paths exist"
  111. else
  112. log_err ".claude-plugin/marketplace.json missing"
  113. fi
  114. if [[ -f "$REPO_ROOT/.claude-plugin/plugin.json" ]]; then
  115. pname=$(jq -r '.name' "$REPO_ROOT/.claude-plugin/plugin.json" 2>/dev/null || echo "unknown")
  116. log_ok "homelab-core plugin.json valid (name: $pname)"
  117. else
  118. log_err ".claude-plugin/plugin.json missing — homelab-core plugin cannot be installed"
  119. fi
  120. # Check service plugin manifests
  121. missing_manifests=0
  122. total_services=0
  123. if [[ -d "$REPO_ROOT/service-plugins" ]]; then
  124. for d in "$REPO_ROOT/service-plugins"/*/; do
  125. [[ -d "$d" ]] || continue
  126. ((total_services++))
  127. if [[ ! -f "$d.claude-plugin/plugin.json" ]]; then
  128. log_warn "Missing plugin.json: $d"
  129. ((missing_manifests++))
  130. fi
  131. done
  132. if [[ "$total_services" -gt 0 ]]; then
  133. good=$(( total_services - missing_manifests ))
  134. if [[ "$missing_manifests" -eq 0 ]]; then
  135. log_ok "$total_services service plugins with valid manifests"
  136. else
  137. log_warn "$good/$total_services service plugins have plugin.json ($missing_manifests missing)"
  138. fi
  139. else
  140. log_warn "service-plugins/ exists but contains no plugin directories"
  141. fi
  142. else
  143. log_warn "service-plugins/ missing — skipping standalone manifest checks"
  144. fi
  145. # Check homelab-core skills
  146. log_head "Homelab-Core Skills"
  147. for skill in setup health; do
  148. if [[ -f "$REPO_ROOT/skills/$skill/SKILL.md" ]]; then
  149. log_ok "/homelab-core:$skill skill present"
  150. else
  151. log_err "skills/$skill/SKILL.md missing"
  152. fi
  153. done
  154. if [[ -x "$REPO_ROOT/skills/health/scripts/check-health.sh" ]]; then
  155. log_ok "check-health.sh is executable"
  156. else
  157. log_warn "check-health.sh missing or not executable"
  158. fi
  159. # -------------------------------------------------------------------
  160. # Summary
  161. # -------------------------------------------------------------------
  162. echo ""
  163. echo -e "${BLUE}============================${NC}"
  164. echo -e " ${GREEN}✓${NC} OK: $ok"
  165. [[ "$warn" -gt 0 ]] && echo -e " ${YELLOW}⚠${NC} Warnings: $warn"
  166. [[ "$err" -gt 0 ]] && echo -e " ${RED}✗${NC} Errors: $err"
  167. echo ""
  168. if [[ "$err" -gt 0 ]]; then
  169. echo -e "${RED}Critical issues found — fix errors above before using Claude Code skills.${NC}"
  170. echo ""
  171. exit 1
  172. elif [[ "$warn" -gt 0 ]]; then
  173. echo -e "${YELLOW}Setup complete with warnings. Run /homelab-core:setup in Claude Code to configure credentials.${NC}"
  174. echo ""
  175. else
  176. echo -e "${GREEN}All good! Run /homelab-core:health in Claude Code to verify service connectivity.${NC}"
  177. echo ""
  178. fi

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.