claude-homelab
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.
Badge for your README
Markdown
[](/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
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)
- {
- "name": "claude-homelab",
- "owner": {
- "name": "jmagar",
- "email": "jmagar@users.noreply.github.com"
- },
- "metadata": {
- "description": "Comprehensive Claude Code skills and agents for homelab service management - media automation, infrastructure monitoring, document management, and more",
- "version": "1.1.0"
- },
- "plugins": [
- {
- "name": "homelab-core",
- "source": "./",
- "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.",
- "version": "1.1.2",
- "category": "core",
- "tags": [
- "agents",
- "commands",
- "skills",
- "orchestration",
- "setup",
- "health"
- ],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "overseerr-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/overseerr-mcp"
- },
- "description": "Overseerr media requests via MCP tools with HTTP fallback. Search movies and TV shows, submit requests, and monitor failed requests.",
- "version": "1.0.0",
- "category": "media",
- "tags": [
- "overseerr",
- "media",
- "requests",
- "plex",
- "mcp"
- ],
- "homepage": "https://github.com/jmagar/overseerr-mcp"
- },
- {
- "name": "unraid-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/unraid-mcp"
- },
- "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.",
- "version": "1.2.0",
- "category": "infrastructure",
- "tags": [
- "unraid",
- "homelab",
- "graphql",
- "docker",
- "nas",
- "monitoring"
- ],
- "homepage": "https://github.com/jmagar/unraid-mcp"
- },
- {
- "name": "unifi-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/unifi-mcp"
- },
- "description": "UniFi network management via MCP tools. Monitor devices, clients, network health, firewall rules, and perform management operations.",
- "version": "1.0.0",
- "category": "infrastructure",
- "tags": [
- "unifi",
- "networking",
- "monitoring",
- "homelab",
- "mcp"
- ],
- "homepage": "https://github.com/jmagar/unifi-mcp"
- },
- {
- "name": "gotify-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/gotify-mcp"
- },
- "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.",
- "version": "1.0.0",
- "category": "utilities",
- "tags": [
- "gotify",
- "notifications",
- "push",
- "homelab",
- "mcp"
- ],
- "homepage": "https://github.com/jmagar/gotify-mcp"
- },
- {
- "name": "swag-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/swag-mcp"
- },
- "description": "SWAG reverse proxy configuration management via MCP. Create, edit, view, and manage nginx proxy configurations with auth integration.",
- "version": "1.0.0",
- "category": "infrastructure",
- "tags": [
- "swag",
- "nginx",
- "reverse-proxy",
- "homelab",
- "mcp"
- ],
- "homepage": "https://github.com/jmagar/swag-mcp"
- },
- {
- "name": "synapse-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/synapse-mcp"
- },
- "description": "MCP server providing Flux (Docker management) and Scout (SSH operations) tools for homelab infrastructure.",
- "version": "2.2.1",
- "category": "infrastructure",
- "tags": [
- "synapse",
- "flux",
- "scout",
- "homelab",
- "docker",
- "ssh",
- "infrastructure",
- "zfs",
- "remote-management"
- ],
- "homepage": "https://github.com/jmagar/synapse-mcp"
- },
- {
- "name": "arcane-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/arcane-mcp"
- },
- "description": "Manage Docker containers, images, volumes, networks, and stacks via the Arcane API.",
- "version": "1.1.3",
- "category": "infrastructure",
- "tags": [
- "arcane",
- "docker",
- "homelab",
- "mcp",
- "containers"
- ],
- "homepage": "https://github.com/jmagar/arcane-mcp"
- },
- {
- "name": "syslog-mcp",
- "source": {
- "source": "github",
- "repo": "jmagar/syslog-mcp"
- },
- "description": "Homelab syslog receiver plus MCP server for searching, tailing, and correlating logs across hosts.",
- "version": "1.0.0",
- "category": "infrastructure",
- "tags": [
- "syslog",
- "logs",
- "observability",
- "homelab",
- "mcp",
- "sqlite"
- ],
- "homepage": "https://github.com/jmagar/syslog-mcp"
- },
- {
- "name": "plugin-lab",
- "source": {
- "source": "github",
- "repo": "jmagar/plugin-lab"
- },
- "description": "Agents, commands, skills, and scripts for scaffolding, reviewing, aligning, and deploying homelab MCP server plugins. Includes canonical Python, TypeScript, and Rust server templates.",
- "version": "1.0.0",
- "category": "dev-tools",
- "tags": [
- "scaffolding",
- "templates",
- "mcp",
- "plugin-dev",
- "plugin-lab",
- "python",
- "typescript",
- "rust",
- "agents",
- "ci-cd"
- ],
- "homepage": "https://github.com/jmagar/plugin-lab"
- },
- {
- "name": "bytestash",
- "source": "./skills/bytestash",
- "description": "ByteStash code snippet management. Store, search, and organize code snippets.",
- "version": "1.0.0",
- "category": "utilities",
- "tags": ["bytestash", "snippets", "code", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "gh-address-comments",
- "source": "./skills/gh-address-comments",
- "description": "Address GitHub PR review comments. Fetch, implement, and verify resolution of PR feedback.",
- "version": "1.0.0",
- "category": "dev-tools",
- "tags": ["github", "pull-requests", "code-review", "automation"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "linkding",
- "source": "./skills/linkding",
- "description": "Linkding bookmark management. Save, search, tag, and organize bookmarks.",
- "version": "1.0.0",
- "category": "utilities",
- "tags": ["linkding", "bookmarks", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "memos",
- "source": "./skills/memos",
- "description": "Memos note-taking service. Create, search, tag, and manage quick notes and memos.",
- "version": "1.0.0",
- "category": "utilities",
- "tags": ["memos", "notes", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "notebooklm",
- "source": "./skills/notebooklm",
- "description": "Google NotebookLM integration. Create notebooks, add sources, generate podcasts, videos, and research artifacts.",
- "version": "1.0.0",
- "category": "research",
- "tags": ["notebooklm", "research", "ai", "google"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "paperless-ngx",
- "source": "./skills/paperless-ngx",
- "description": "Paperless-ngx document management. Upload, search, tag, and organize documents.",
- "version": "1.0.0",
- "category": "utilities",
- "tags": ["paperless", "documents", "ocr", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "plex",
- "source": "./skills/plex",
- "description": "Plex Media Server management. Browse libraries, search media, manage playlists, and monitor activity.",
- "version": "1.0.0",
- "category": "media",
- "tags": ["plex", "media", "streaming", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "prowlarr",
- "source": "./skills/prowlarr",
- "description": "Prowlarr indexer management. Add, configure, test, and search indexers.",
- "version": "1.0.0",
- "category": "media",
- "tags": ["prowlarr", "indexers", "search", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "qbittorrent",
- "source": "./skills/qbittorrent",
- "description": "qBittorrent download management. Add, monitor, pause, and manage torrent downloads.",
- "version": "1.0.0",
- "category": "downloads",
- "tags": ["qbittorrent", "torrents", "downloads", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "radarr",
- "source": "./skills/radarr",
- "description": "Radarr movie management. Search, add, monitor, and manage movie collections.",
- "version": "1.0.0",
- "category": "media",
- "tags": ["radarr", "movies", "media", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "radicale",
- "source": "./skills/radicale",
- "description": "Radicale CalDAV/CardDAV server management. Manage calendars, contacts, and address books.",
- "version": "1.0.0",
- "category": "utilities",
- "tags": ["radicale", "caldav", "carddav", "calendar", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "sabnzbd",
- "source": "./skills/sabnzbd",
- "description": "SABnzbd Usenet download management. Add, monitor, and manage NZB downloads.",
- "version": "1.0.0",
- "category": "downloads",
- "tags": ["sabnzbd", "usenet", "downloads", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "sonarr",
- "source": "./skills/sonarr",
- "description": "Sonarr TV series management. Search, add, monitor, and manage TV show collections.",
- "version": "1.0.0",
- "category": "media",
- "tags": ["sonarr", "tv", "series", "media", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "tailscale",
- "source": "./skills/tailscale",
- "description": "Tailscale VPN mesh network management. Monitor devices, manage routes, and check network status.",
- "version": "1.0.0",
- "category": "infrastructure",
- "tags": ["tailscale", "vpn", "networking", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "tautulli",
- "source": "./skills/tautulli",
- "description": "Tautulli Plex monitoring. View activity, history, statistics, and user analytics.",
- "version": "1.0.0",
- "category": "media",
- "tags": ["tautulli", "plex", "monitoring", "analytics", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- },
- {
- "name": "zfs",
- "source": "./skills/zfs",
- "description": "ZFS storage management. Monitor pools, datasets, snapshots, scrubs, and replication.",
- "version": "1.0.0",
- "category": "infrastructure",
- "tags": ["zfs", "storage", "snapshots", "homelab"],
- "homepage": "https://github.com/jmagar/claude-homelab"
- }
- ]
- }
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)
- # Claude Homelab
- Current release: 1.4.0.
- 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.
- ## Overview
- `claude-homelab` serves three roles at once:
- - The `homelab-core` plugin published through the Claude marketplace
- - The canonical mono-repo for 16 bundled skill-only service integrations
- - The source for Codex and Gemini extension manifests that mirror the same workflow surface
- The repo root is the plugin root. Do not edit generated copies in `~/.claude/` or `~/.claude/plugins/cache/` directly.
- ## Installation
- ### Claude marketplace
- ```bash
- /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
- ```bash
- 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
- ```
- Or, if you already have the repo cloned:
- ```bash
- ./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
- ## Credential Model
- All credentials for every service live in a single file:
- ```
- ~/.claude-homelab/.env
- ```
- This file is created from `.env.example` at install time and is never committed. Set it up interactively after install:
- ```bash
- # Interactive wizard (preferred)
- # Open Claude Code and run:
- /homelab-core:setup
- # Or configure manually
- $EDITOR ~/.claude-homelab/.env
- ```
- Security requirements:
- - `~/.claude-homelab/.env` must have `chmod 600` (owner read/write only)
- - Never commit `.env` — it is gitignored
- - Never log credentials, even in debug mode
- - Use `.env.example` as the template (tracked in git, placeholder values only)
- All service scripts load credentials via `scripts/load-env.sh`:
- ```bash
- source "${CLAUDE_PLUGIN_ROOT:-$HOME/claude-homelab}/scripts/load-env.sh"
- load_env_file || exit 1
- validate_env_vars "SERVICE_URL" "SERVICE_API_KEY"
- ```
- ### Environment Variable Reference
- Variables are grouped by service. Copy `.env.example` to `~/.claude-homelab/.env` and replace placeholder values.
- #### Media
- | Variable | Required | Description |
- |---|---|---|
- | `PLEX_URL` | yes | Plex server base URL |
- | `PLEX_TOKEN` | yes | Plex authentication token |
- | `OVERSEERR_URL` | yes | Overseerr base URL (skill) |
- | `OVERSEERR_API_KEY` | yes | Overseerr API key (skill) |
- | `RADARR_URL` | yes | Radarr base URL |
- | `RADARR_API_KEY` | yes | Radarr API key |
- | `RADARR_DEFAULT_QUALITY_PROFILE` | no | Default quality profile ID (default: `1`) |
- | `SONARR_URL` | yes | Sonarr base URL |
- | `SONARR_API_KEY` | yes | Sonarr API key |
- | `SONARR_DEFAULT_QUALITY_PROFILE` | no | Default quality profile ID (default: `1`) |
- | `PROWLARR_URL` | yes | Prowlarr base URL |
- | `PROWLARR_API_KEY` | yes | Prowlarr API key |
- | `TAUTULLI_URL` | yes | Tautulli base URL |
- | `TAUTULLI_API_KEY` | yes | Tautulli API key |
- #### Downloads
- | Variable | Required | Description |
- |---|---|---|
- | `SABNZBD_URL` | yes | SABnzbd base URL |
- | `SABNZBD_API_KEY` | yes | SABnzbd API key |
- | `QBITTORRENT_URL` | yes | qBittorrent WebUI URL |
- | `QBITTORRENT_USERNAME` | yes | qBittorrent username |
- | `QBITTORRENT_PASSWORD` | yes | qBittorrent password |
- #### Infrastructure
- | Variable | Required | Description |
- |---|---|---|
- | `UNRAID_SERVER1_NAME` | yes | Display name for first Unraid server |
- | `UNRAID_SERVER1_URL` | yes | Unraid GraphQL endpoint (skill) |
- | `UNRAID_SERVER1_API_KEY` | yes | Unraid API key (skill) |
- | `UNRAID_SERVER2_NAME` | no | Display name for second Unraid server |
- | `UNRAID_SERVER2_URL` | no | Second Unraid GraphQL endpoint |
- | `UNRAID_SERVER2_API_KEY` | no | Second Unraid API key |
- | `UNIFI_URL` | yes | UniFi controller URL (skill) |
- | `UNIFI_USERNAME` | yes | UniFi username |
- | `UNIFI_PASSWORD` | yes | UniFi password |
- | `UNIFI_SITE` | no | UniFi site name (default: `default`) |
- | `TAILSCALE_API_KEY` | yes | Tailscale API key |
- | `TAILSCALE_TAILNET` | yes | Tailscale tailnet name or `-` |
- | `ZFS_HOST` | yes | Host where ZFS commands run |
- | `SWAG_HOST` | yes | SWAG reverse proxy host |
- | `SWAG_CONTAINER_NAME` | no | SWAG container name (default: `swag`) |
- | `SWAG_APPDATA_PATH` | no | SWAG appdata path |
- | `SWAG_COMPOSE_PATH` | no | SWAG compose file path |
- #### Utilities and Document Management
- | Variable | Required | Description |
- |---|---|---|
- | `LINKDING_URL` | yes | Linkding bookmark manager URL |
- | `LINKDING_API_KEY` | yes | Linkding API token |
- | `MEMOS_URL` | yes | Memos server URL |
- | `MEMOS_API_TOKEN` | yes | Memos API token |
- | `BYTESTASH_URL` | yes | ByteStash snippet manager URL |
- | `BYTESTASH_API_KEY` | yes | ByteStash API key |
- | `PAPERLESS_URL` | yes | Paperless-ngx base URL |
- | `PAPERLESS_API_TOKEN` | yes | Paperless-ngx API token |
- | `RADICALE_URL` | yes | Radicale CalDAV/CardDAV URL |
- | `RADICALE_USERNAME` | yes | Radicale username |
- | `RADICALE_PASSWORD` | yes | Radicale password |
- | `GOTIFY_URL` | yes | Gotify push notification URL (skill) |
- | `GOTIFY_TOKEN` | yes | Gotify app token (skill) |
- #### Research and Dev Tools
- | Variable | Required | Description |
- |---|---|---|
- | `NOTEBOOKLM_COOKIE` | yes | NotebookLM session cookie |
- | `NOTEBOOKLM_AUTH_JSON` | no | Full auth JSON blob (alternative to cookie) |
- | `NOTEBOOKLM_LOG_LEVEL` | no | Log verbosity (default: `INFO`) |
- | `GITHUB_TOKEN` | yes | GitHub personal access token (gh-address-comments) |
- | `GLANCES_URL` | no | Glances web interface URL |
- | `GLANCES_USERNAME` | no | Glances username (if auth enabled) |
- | `GLANCES_PASSWORD` | no | Glances password (if auth enabled) |
- #### MCP Server Variables
- Each external MCP plugin has its own block of server-config vars. See `.env.example` for the full list. Key patterns:
- | Pattern | Description |
- |---|---|
- | `*_MCP_TOKEN` | Bearer token for MCP server auth |
- | `*_MCP_HOST` | Bind host (default: `0.0.0.0`) |
- | `*_MCP_PORT` | Listen port |
- | `*_MCP_TRANSPORT` | Transport protocol (`streamable-http` or `http`) |
- | `*_MCP_NO_AUTH` | Disable auth (set `true` for local-only installs) |
- | `*_MCP_ALLOW_DESTRUCTIVE` | Allow destructive operations (default: `false`) |
- | `ALLOW_DESTRUCTIVE` | Shared fallback for MCP repos that read this directly |
- | `ALLOW_YOLO` | Shared fallback — skip confirmation prompts |
- | `DOCKER_NETWORK` | Shared Docker network name |
- | `LOG_LEVEL` | Shared log verbosity |
- ## Commands
- ### Root Commands
- | Command | Argument | Description |
- |---|---|---|
- | `/check` | `[instructions]` | Read the latest screenshot from `~/Pictures/Screenshots` and describe it. Pass optional instructions (e.g., "extract the text", "what error is shown"). |
- | `/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. |
- | `/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. |
- | `/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. |
- | `/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. |
- ### `/homelab:*` Commands
- | Command | Description |
- |---|---|
- | `/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`. |
- | `/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. |
- | `/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. |
- | `/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. |
- ### `/notebooklm:*` Commands
- | Command | Argument | Description |
- |---|---|---|
- | `/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. |
- | `/notebooklm:ask` | `"question"` | Chat with NotebookLM about the current notebook. Options: `--json` for source citations, `-n <id>` to target a specific notebook. |
- | `/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. |
- | `/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. |
- | `/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. |
- | `/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. |
- | `/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`. |
- #### `/notebooklm:generate` Type Reference
- | Type | Key Options | Approximate Time |
- |---|---|---|
- | `audio` (podcast) | `--format deep-dive\|brief\|critique\|debate`, `--length short\|default\|long` | 10–20 min |
- | `video` | `--format explainer\|brief`, `--style auto\|classic\|whiteboard\|kawaii\|...` | 15–45 min |
- | `slide-deck` | `--format detailed\|presenter`, `--length default\|short` | 5–15 min |
- | `infographic` | `--orientation landscape\|portrait\|square`, `--detail concise\|standard\|detailed` | 5–15 min |
- | `report` | `--format briefing-doc\|study-guide\|blog-post\|custom` | 5–15 min |
- | `mind-map` | — | Instant |
- | `data-table` | description required | 5–15 min |
- | `quiz` | `--difficulty easy\|medium\|hard`, `--quantity fewer\|standard\|more` | 5–15 min |
- | `flashcards` | `--difficulty easy\|medium\|hard`, `--quantity fewer\|standard\|more` | 5–15 min |
- All types support `-s/--source`, `--language`, `--json`, and `--retry N`.
- ## Skills
- 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.
- ### Core Skills (2)
- | Skill | Invocation | Purpose |
- |---|---|---|
- | `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. |
- | `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. |
- ### Service Skills (16)
- | Skill | Category | Purpose |
- |---|---|---|
- | `plex` | media | Browse Plex libraries, search media, check active sessions and streams, view recently added content |
- | `radarr` | media | Manage Radarr movie library — search, add, monitor, and track download status |
- | `sonarr` | media | Manage Sonarr TV library — search, add series, monitor seasons and episodes |
- | `prowlarr` | media | Manage Prowlarr indexers — search across all indexers, test connectivity, view stats |
- | `tautulli` | media | Query Tautulli play history, user activity, library stats, and notification logs |
- | `sabnzbd` | downloads | Monitor SABnzbd queue, speed, and history; manage download jobs |
- | `qbittorrent` | downloads | Manage qBittorrent torrents — list, add, pause, resume, and remove downloads |
- | `tailscale` | infrastructure | Query Tailscale network status, list devices, check connectivity, and manage ACLs |
- | `zfs` | infrastructure | ZFS pool and dataset management — status, snapshots, scrubs, and space reporting |
- | `linkding` | utilities | Manage Linkding bookmarks — search, add, tag, and organize saved links |
- | `memos` | utilities | Create and query Memos notes — add quick notes, search by tag or content |
- | `bytestash` | utilities | Manage ByteStash code snippets — save, search, and retrieve frequently-used code |
- | `paperless-ngx` | utilities | Search and manage Paperless-ngx document archive — query by content, tag, or correspondent |
- | `radicale` | utilities | Interact with Radicale CalDAV/CardDAV — list calendars and contacts, query events |
- | `notebooklm` | research | NotebookLM CLI wrapper for deep AI research, source management, Q&A, and artifact generation |
- | `gh-address-comments` | dev-tools | Address GitHub PR review comments — fetch, triage, and resolve review feedback |
- ## Agents
- ### `notebooklm-specialist`
- **File:** `agents/notebooklm-specialist.md`
- **Color:** magenta
- **Tools:** `Bash`, `Read`, `Write`, `SendMessage`
- **Memory:** user (persistent across sessions)
- 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:
- 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
- 2. Adds source URLs relayed from the orchestrator as they arrive (max 50 per notebook)
- 3. Waits for deep research to complete and auto-imports discovered sources
- 4. Conducts an extensive Q&A session (10–20 questions across overview, comparison, technical, critical, practical, and future-directions categories)
- 5. Uses `--json` flag to capture citation data with every answer
- 6. Writes findings to `{output_dir}/findings/notebooklm-findings.md`
- 7. Signals completion to the orchestrator via `SendMessage`
- **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.
- The agent maintains persistent memory of effective research query patterns, timing benchmarks, and NotebookLM-specific quirks across sessions.
- ## Marketplace Scope
- The `.claude-plugin/marketplace.json` catalog covers 27 plugins total.
- ### 1 core plugin
- | Plugin | Source | Description |
- |---|---|---|
- | `homelab-core` | this repo | Agents, commands, setup/health skills, and the bundled skill library |
- ### 10 external MCP repos
- | Plugin | Repo | Category |
- |---|---|---|
- | `overseerr-mcp` | `jmagar/overseerr-mcp` | media |
- | `unraid-mcp` | `jmagar/unraid-mcp` | infrastructure |
- | `unifi-mcp` | `jmagar/unifi-mcp` | infrastructure |
- | `gotify-mcp` | `jmagar/gotify-mcp` | utilities |
- | `swag-mcp` | `jmagar/swag-mcp` | infrastructure |
- | `synapse-mcp` | `jmagar/synapse-mcp` | infrastructure |
- | `arcane-mcp` | `jmagar/arcane-mcp` | infrastructure |
- | `syslog-mcp` | `jmagar/syslog-mcp` | infrastructure |
- | `plugin-lab` | `jmagar/plugin-lab` | dev-tools |
- ### 16 bundled skill-only plugins
- `bytestash`, `gh-address-comments`, `linkding`, `memos`, `notebooklm`, `paperless-ngx`, `plex`, `prowlarr`, `qbittorrent`, `radarr`, `radicale`, `sabnzbd`, `sonarr`, `tailscale`, `tautulli`, `zfs`
- 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).
- ## Symlink Architecture
- 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.
- ```
- ~/.claude/
- ├── agents/
- │ └── notebooklm-specialist.md → ~/claude-homelab/agents/notebooklm-specialist.md
- ├── skills/
- │ ├── bytestash/ → ~/claude-homelab/skills/bytestash/
- │ ├── gh-address-comments/ → ~/claude-homelab/skills/gh-address-comments/
- │ ├── homelab-health/ → ~/claude-homelab/skills/homelab-health/
- │ ├── homelab-setup/ → ~/claude-homelab/skills/homelab-setup/
- │ ├── linkding/ → ~/claude-homelab/skills/linkding/
- │ ├── memos/ → ~/claude-homelab/skills/memos/
- │ ├── notebooklm/ → ~/claude-homelab/skills/notebooklm/
- │ ├── paperless-ngx/ → ~/claude-homelab/skills/paperless-ngx/
- │ ├── plex/ → ~/claude-homelab/skills/plex/
- │ ├── prowlarr/ → ~/claude-homelab/skills/prowlarr/
- │ ├── qbittorrent/ → ~/claude-homelab/skills/qbittorrent/
- │ ├── radarr/ → ~/claude-homelab/skills/radarr/
- │ ├── radicale/ → ~/claude-homelab/skills/radicale/
- │ ├── sabnzbd/ → ~/claude-homelab/skills/sabnzbd/
- │ ├── sonarr/ → ~/claude-homelab/skills/sonarr/
- │ ├── tailscale/ → ~/claude-homelab/skills/tailscale/
- │ ├── tautulli/ → ~/claude-homelab/skills/tautulli/
- │ └── zfs/ → ~/claude-homelab/skills/zfs/
- └── commands/
- ├── check.md → ~/claude-homelab/commands/check.md
- ├── deploy.md → ~/claude-homelab/commands/deploy.md
- ├── quick-push.md → ~/claude-homelab/commands/quick-push.md
- ├── save-to-md.md → ~/claude-homelab/commands/save-to-md.md
- ├── validate-plan.md → ~/claude-homelab/commands/validate-plan.md
- ├── homelab/ → ~/claude-homelab/commands/homelab/
- └── notebooklm/ → ~/claude-homelab/commands/notebooklm/
- ~/.claude-homelab/
- ├── .env # Credentials (chmod 600, never committed)
- └── load-env.sh # Copied from scripts/load-env.sh at install
- ```
- ### How Slash Commands Work
- Slash commands are created by placing `.md` files in `~/.claude/commands/`. Claude Code discovers them automatically.
- - `commands/proxy.md` → `/proxy`
- - `commands/homelab/docker-health.md` → `/homelab:docker-health`
- The directory name becomes the namespace prefix. The file name becomes the command after the colon.
- ## Configuration System
- ### Command Files (`commands/`)
- Each command is a Markdown file with a YAML frontmatter block:
- ```yaml
- ---
- description: Short description shown in autocomplete
- argument-hint: <required> [optional]
- allowed-tools: Bash(tool:*), mcp__plugin_name__tool
- ---
- Task instruction using $ARGUMENTS
- ```
- Key fields:
- - `description` — shown in autocomplete menu
- - `argument-hint` — hint text for expected arguments
- - `allowed-tools` — pre-approved tools (no permission prompts at runtime)
- - `$ARGUMENTS` — replaced with user input after the command name
- - `` !`command` `` — dynamic context injection: runs the shell command and injects its output at load time
- ### Prompts Sidecar System (`prompts/`)
- 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:
- - `prompts/check.toml` — prompt body for `/check`
- - `prompts/homelab/docker-health.toml` — prompt body for `/homelab:docker-health`
- Format:
- ```toml
- name = "command-name"
- description = "Short description"
- prompt = """
- Prompt body with instructions and dynamic context injection.
- """
- ```
- The `prompts/` directory is not present by default. Create it if you extract prompts out of command `.md` files.
- ### Output Styles (`output-styles/`)
- 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.
- ## Development
- ### Adding a New Service Skill
- 1. Create the skill directory:
- ```bash
- mkdir -p skills/service-name/{scripts,references,examples}
- ```
- 2. Create `SKILL.md` with frontmatter (`name`, `description`), a mandatory invocation section, command documentation, and workflow decision trees.
- 3. Create `README.md` for user-facing setup instructions.
- 4. Implement scripts in `scripts/`. All scripts must:
- - Use `source "$REPO_ROOT/scripts/load-env.sh"` for credentials
- - Return JSON output
- - Handle errors gracefully
- - Support `--help`
- 5. Add reference docs in `references/` (`api-endpoints.md`, `quick-reference.md`, `troubleshooting.md`).
- 6. Create the symlink (bash path):
- ```bash
- ln -sf ~/claude-homelab/skills/service-name ~/.claude/skills/service-name
- ```
- Or re-run `./scripts/setup-symlinks.sh` to pick it up automatically.
- 7. Add the skill to the marketplace catalog if it should be discoverable:
- - Edit `.claude-plugin/marketplace.json`
- - Add a `bundled` entry pointing to `./skills/service-name`
- 8. Update this README's Skills table.
- ### Adding a New Command
- Single command (`/new-command`):
- ```bash
- touch commands/new-command.md
- ln -sf ~/claude-homelab/commands/new-command.md ~/.claude/commands/new-command.md
- ```
- Namespaced command (`/service:action`):
- ```bash
- mkdir -p commands/service-name
- touch commands/service-name/action.md
- ln -sf ~/claude-homelab/commands/service-name ~/.claude/commands/service-name
- ```
- ### Credential Pattern
- All scripts must source `scripts/load-env.sh` (see [Credential Model](#credential-model) above for the full pattern and variable naming conventions).
- ## Verification
- Run after any structural change:
- ```bash
- ./scripts/verify.sh
- ```
- The verify script checks:
- - All required symlinks exist and point to valid targets
- - `~/.claude-homelab/.env` exists
- Additional checks:
- ```bash
- # Run all Justfile validation targets
- just validate
- # Spot-check section headers across key docs
- rtk rg -n "^## " README.md AGENTS.md CLAUDE.md
- ```
- ## Repository Layout
- ```
- agents/ Top-level specialist agents
- commands/ Slash command definitions (.md files)
- commands/homelab/ /homelab:* command definitions
- commands/notebooklm/ /notebooklm:* command definitions
- docs/ Session logs and reference documentation
- docs/references/ Shared reference docs (security-patterns.md)
- hooks/ Reserved for future Claude Code hook definitions
- output-styles/ Reserved for custom response format definitions
- scripts/ Install, setup, credential loading, and verification helpers
- skills/ 18 service and core skill directories
- .claude-plugin/ Claude marketplace manifest (plugin.json, marketplace.json)
- .codex-plugin/ Codex plugin manifest
- gemini-extension.json Gemini extension manifest
- AGENTS.md Repo-wide development instructions
- CLAUDE.md Claude-facing project instructions
- CHANGELOG.md Release history
- .env.example Shared credential template (tracked, no secrets)
- Justfile Validation and maintenance recipes
- ```
- ## Related Files
- - `AGENTS.md` — canonical development and repo-structure guidance
- - `CLAUDE.md` — Claude-facing project instructions including symlink architecture, command format, and skill development workflow
- - `.env.example` — shared credential template for all 16 services and 10 MCP repos
- - `.claude-plugin/marketplace.json` — marketplace source of truth (27 plugin entries)
- - `.claude-plugin/plugin.json` — `homelab-core` plugin manifest
- - `CHANGELOG.md` — release history
- - `docs/references/security-patterns.md` — reusable patterns for input sanitization, injection prevention, and API key protection
- ## Related plugins
- | Plugin | Category | Description |
- |--------|----------|-------------|
- | [overseerr-mcp](https://github.com/jmagar/overseerr-mcp) | media | Search movies and TV shows, submit requests, and monitor failed requests via Overseerr. |
- | [unraid-mcp](https://github.com/jmagar/unraid-mcp) | infrastructure | Query, monitor, and manage Unraid servers: Docker, VMs, array, parity, and live telemetry. |
- | [unifi-mcp](https://github.com/jmagar/unifi-mcp) | infrastructure | Monitor and manage UniFi devices, clients, firewall rules, and network health. |
- | [gotify-mcp](https://github.com/jmagar/gotify-mcp) | utilities | Send and manage push notifications via a self-hosted Gotify server. |
- | [swag-mcp](https://github.com/jmagar/swag-mcp) | infrastructure | Create, edit, and manage SWAG nginx reverse proxy configurations. |
- | [synapse-mcp](https://github.com/jmagar/synapse-mcp) | infrastructure | Docker management (Flux) and SSH remote operations (Scout) across homelab hosts. |
- | [arcane-mcp](https://github.com/jmagar/arcane-mcp) | infrastructure | Manage Docker environments, containers, images, volumes, networks, and GitOps via Arcane. |
- | [syslog-mcp](https://github.com/jmagar/syslog-mcp) | infrastructure | Receive, index, and search syslog streams from all homelab hosts via SQLite FTS5. |
- | [plugin-lab](https://github.com/jmagar/plugin-lab) | dev-tools | Scaffold, review, align, and deploy homelab MCP plugins with agents and canonical templates. |
- ## License
- MIT
scripts/install.sh · Bundled script · 148 lines · 1 finding marked
- #!/bin/bash
- # =============================================================================
- # Claude Homelab Installer
- # =============================================================================
- # 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
- #
- # What this does:
- # 1. Checks prerequisites (git, jq, curl)
- # 2. Clones repo to ~/claude-homelab (or git pull if it exists)
- # 3. Runs setup-creds.sh (creates ~/.claude-homelab/.env with chmod 600)
- # 4. Runs setup-symlinks.sh (symlinks service-plugins/agents/commands into ~/.claude/)
- # 5. Runs verify.sh (confirms everything is in place)
- # 6. Prints next steps
- #
- # Non-interactive — safe for curl | bash (no read -p prompts)
- # =============================================================================
- set -euo pipefail
- # Colors
- RED='\033[0;31m'
- GREEN='\033[0;32m'
- YELLOW='\033[1;33m'
- BLUE='\033[0;34m'
- NC='\033[0m'
- REPO_URL="https://github.com/jmagar/claude-homelab.git"
- INSTALL_DIR="$HOME/claude-homelab"
- HOMELAB_DIR="$HOME/.claude-homelab"
- log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
- log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
- log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
- log_error() { echo -e "${RED}[ERR]${NC} $1"; }
- # -------------------------------------------------------------------
- # Step 1: Check prerequisites
- # -------------------------------------------------------------------
- check_prereqs() {
- local missing=()
- for cmd in git jq curl; do
- if ! command -v "$cmd" &>/dev/null; then
- missing+=("$cmd")
- fi
- done
- if [[ ${#missing[@]} -gt 0 ]]; then
- log_error "Missing required tools: ${missing[*]}"
- echo "Install them first, then re-run this script."
- exit 1
- fi
- log_success "Prerequisites met (git, jq, curl)"
- }
- # -------------------------------------------------------------------
- # Step 2: Clone or update repo
- # -------------------------------------------------------------------
- clone_or_pull() {
- if [[ -d "$INSTALL_DIR/.git" ]]; then
- log_info "Repository already exists at $INSTALL_DIR — pulling latest..."
- git -C "$INSTALL_DIR" pull --ff-only || {
- log_warn "git pull failed (you may have local changes). Continuing with existing checkout."
- }
- else
- if [[ -e "$INSTALL_DIR" ]]; then
- log_error "$INSTALL_DIR exists but is not a git repo. Move or remove it first."
- exit 1
- fi
- log_info "Cloning claude-homelab to $INSTALL_DIR..."
- git clone "$REPO_URL" "$INSTALL_DIR"
- fi
- log_success "Repository ready at $INSTALL_DIR"
- }
- # -------------------------------------------------------------------
- # Step 3: Set up credentials
- # -------------------------------------------------------------------
- run_setup_creds() {
- local script="$INSTALL_DIR/scripts/setup-creds.sh"
- if [[ ! -f "$script" ]]; then
- log_error "setup-creds.sh not found at $script"
- exit 1
- fi
- chmod +x "$script"
- log_info "Setting up credentials..."
- bash "$script"
- }
- # -------------------------------------------------------------------
- # Step 4: Run setup-symlinks.sh
- # -------------------------------------------------------------------
- run_symlinks() {
- local script="$INSTALL_DIR/scripts/setup-symlinks.sh"
- if [[ ! -f "$script" ]]; then
- log_error "setup-symlinks.sh not found at $script"
- exit 1
- fi
- chmod +x "$script"
- log_info "Running setup-symlinks.sh..."
- bash "$script"
- }
- # -------------------------------------------------------------------
- # Step 5: Verify
- # -------------------------------------------------------------------
- run_verify() {
- local script="$INSTALL_DIR/scripts/verify.sh"
- if [[ -f "$script" ]]; then
- chmod +x "$script"
- log_info "Verifying installation..."
- bash "$script" || log_warn "Verification had warnings — see above"
- fi
- }
- # -------------------------------------------------------------------
- # Step 6: Print next steps
- # -------------------------------------------------------------------
- print_next_steps() {
- echo ""
- echo -e "${GREEN}=== Installation Complete ===${NC}"
- echo ""
- echo "Next steps:"
- echo ""
- echo -e " 1. ${YELLOW}Configure credentials (interactive wizard):${NC}"
- echo " Open Claude Code and run: /homelab-core:setup"
- echo ""
- echo -e " Or edit manually: \$EDITOR ~/.claude-homelab/.env"
- echo ""
- echo -e " 2. ${YELLOW}Restart Claude Code${NC} to pick up the new skills"
- echo ""
- echo -e " 3. ${YELLOW}Check service health:${NC}"
- echo " /homelab-core:health"
- echo ""
- }
- # -------------------------------------------------------------------
- # Main
- # -------------------------------------------------------------------
- echo ""
- echo -e "${BLUE}=== Claude Homelab Installer ===${NC}"
- echo ""
- check_prereqs
- clone_or_pull
- run_setup_creds
- run_symlinks
- run_verify
- print_next_steps
scripts/verify.sh · Bundled script · 200 lines · 1 finding marked
- #!/bin/bash
- # =============================================================================
- # Verify Claude Homelab Installation
- # =============================================================================
- # Works for both bash path (symlinks) and plugin path (Claude Code cache).
- # Exits 0 if healthy, 1 if critical issues found.
- # =============================================================================
- set -uo pipefail
- RED='\033[0;31m'
- GREEN='\033[0;32m'
- YELLOW='\033[1;33m'
- BLUE='\033[0;34m'
- NC='\033[0m'
- ok=0
- warn=0
- err=0
- log_ok() { echo -e " ${GREEN}✓${NC} $1"; ((ok++)); }
- log_warn() { echo -e " ${YELLOW}⚠${NC} $1"; ((warn++)); }
- log_err() { echo -e " ${RED}✗${NC} $1"; ((err++)); }
- log_head() { echo ""; echo -e "${BLUE}$1${NC}"; }
- REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
- HOMELAB_DIR="$HOME/.claude-homelab"
- CLAUDE_DIR="$HOME/.claude"
- echo ""
- echo -e "${BLUE}=== Claude Homelab — Verification ===${NC}"
- # -------------------------------------------------------------------
- # 1. Credentials
- # -------------------------------------------------------------------
- log_head "Credentials"
- if [[ -f "$HOMELAB_DIR/.env" ]]; then
- perm=$(stat -c "%a" "$HOMELAB_DIR/.env" 2>/dev/null || stat -f "%Lp" "$HOMELAB_DIR/.env" 2>/dev/null)
- if [[ "$perm" == "600" ]]; then
- log_ok ".env exists with correct permissions (600)"
- else
- log_warn ".env exists but permissions are $perm (should be 600) — run: chmod 600 $HOMELAB_DIR/.env"
- fi
- if [[ -s "$HOMELAB_DIR/.env" ]]; then
- configured=$(grep -c "=.\+" "$HOMELAB_DIR/.env" 2>/dev/null || echo 0)
- log_ok "$configured credential lines configured"
- else
- log_warn ".env is empty — run /homelab-core:setup in Claude Code"
- fi
- else
- 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
- fi
- if [[ -f "$HOMELAB_DIR/load-env.sh" ]]; then
- log_ok "load-env.sh installed at $HOMELAB_DIR/load-env.sh"
- else
- log_warn "load-env.sh missing — run setup-symlinks.sh"
- fi
- # -------------------------------------------------------------------
- # 2. Bash path — symlinks
- # -------------------------------------------------------------------
- log_head "Bash Path (symlinks)"
- if [[ -d "$CLAUDE_DIR/skills" ]]; then
- skill_count=$(find "$CLAUDE_DIR/skills" -maxdepth 1 -type l 2>/dev/null | wc -l)
- broken=$(find "$CLAUDE_DIR/skills" -maxdepth 1 -type l ! -e 2>/dev/null | wc -l)
- if [[ "$broken" -gt 0 ]]; then
- log_warn "$skill_count skill symlinks ($broken broken) — re-run: $REPO_ROOT/scripts/setup-symlinks.sh"
- find "$CLAUDE_DIR/skills" -maxdepth 1 -type l ! -e 2>/dev/null | while read -r s; do
- echo " broken: $s"
- done
- else
- log_ok "$skill_count skill symlinks (all valid)"
- fi
- else
- log_warn "~/.claude/skills/ missing — run setup-symlinks.sh"
- fi
- if [[ -d "$CLAUDE_DIR/agents" ]]; then
- agent_count=$(find "$CLAUDE_DIR/agents" -maxdepth 1 -type l 2>/dev/null | wc -l)
- log_ok "$agent_count agent symlinks"
- else
- log_warn "~/.claude/agents/ missing"
- fi
- if [[ -d "$CLAUDE_DIR/commands" ]]; then
- cmd_count=$(find "$CLAUDE_DIR/commands" -maxdepth 1 \( -type l -o -type f \) -name "*.md" 2>/dev/null | wc -l)
- log_ok "$cmd_count command files"
- else
- log_warn "~/.claude/commands/ missing"
- fi
- # -------------------------------------------------------------------
- # 3. Plugin path — marketplace + plugin.json
- # -------------------------------------------------------------------
- log_head "Plugin Path"
- if [[ -f "$REPO_ROOT/.claude-plugin/marketplace.json" ]]; then
- plugin_count=$(jq '.plugins | length' "$REPO_ROOT/.claude-plugin/marketplace.json" 2>/dev/null || echo "?")
- log_ok "marketplace.json valid ($plugin_count plugins listed)"
- # Verify local source paths exist; GitHub-backed sources are not local directories.
- dead=0
- while IFS=$'\t' read -r name source_type source_value; do
- if [[ "$source_type" == "string" ]]; then
- src="${source_value#./}"
- full_path="$REPO_ROOT/$src"
- if [[ ! -d "$full_path" && "$source_value" != "./" ]]; then
- log_warn "Dead marketplace entry ($name): $source_value"
- ((dead++))
- fi
- fi
- done < <(
- jq -r '
- .plugins[]
- | [
- .name,
- (.source | type),
- (if (.source | type) == "string" then .source else .source.repo end)
- ]
- | @tsv
- ' "$REPO_ROOT/.claude-plugin/marketplace.json" 2>/dev/null
- )
- [[ "$dead" -eq 0 ]] && log_ok "All marketplace source paths exist"
- else
- log_err ".claude-plugin/marketplace.json missing"
- fi
- if [[ -f "$REPO_ROOT/.claude-plugin/plugin.json" ]]; then
- pname=$(jq -r '.name' "$REPO_ROOT/.claude-plugin/plugin.json" 2>/dev/null || echo "unknown")
- log_ok "homelab-core plugin.json valid (name: $pname)"
- else
- log_err ".claude-plugin/plugin.json missing — homelab-core plugin cannot be installed"
- fi
- # Check service plugin manifests
- missing_manifests=0
- total_services=0
- if [[ -d "$REPO_ROOT/service-plugins" ]]; then
- for d in "$REPO_ROOT/service-plugins"/*/; do
- [[ -d "$d" ]] || continue
- ((total_services++))
- if [[ ! -f "$d.claude-plugin/plugin.json" ]]; then
- log_warn "Missing plugin.json: $d"
- ((missing_manifests++))
- fi
- done
- if [[ "$total_services" -gt 0 ]]; then
- good=$(( total_services - missing_manifests ))
- if [[ "$missing_manifests" -eq 0 ]]; then
- log_ok "$total_services service plugins with valid manifests"
- else
- log_warn "$good/$total_services service plugins have plugin.json ($missing_manifests missing)"
- fi
- else
- log_warn "service-plugins/ exists but contains no plugin directories"
- fi
- else
- log_warn "service-plugins/ missing — skipping standalone manifest checks"
- fi
- # Check homelab-core skills
- log_head "Homelab-Core Skills"
- for skill in setup health; do
- if [[ -f "$REPO_ROOT/skills/$skill/SKILL.md" ]]; then
- log_ok "/homelab-core:$skill skill present"
- else
- log_err "skills/$skill/SKILL.md missing"
- fi
- done
- if [[ -x "$REPO_ROOT/skills/health/scripts/check-health.sh" ]]; then
- log_ok "check-health.sh is executable"
- else
- log_warn "check-health.sh missing or not executable"
- fi
- # -------------------------------------------------------------------
- # Summary
- # -------------------------------------------------------------------
- echo ""
- echo -e "${BLUE}============================${NC}"
- echo -e " ${GREEN}✓${NC} OK: $ok"
- [[ "$warn" -gt 0 ]] && echo -e " ${YELLOW}⚠${NC} Warnings: $warn"
- [[ "$err" -gt 0 ]] && echo -e " ${RED}✗${NC} Errors: $err"
- echo ""
- if [[ "$err" -gt 0 ]]; then
- echo -e "${RED}Critical issues found — fix errors above before using Claude Code skills.${NC}"
- echo ""
- exit 1
- elif [[ "$warn" -gt 0 ]]; then
- echo -e "${YELLOW}Setup complete with warnings. Run /homelab-core:setup in Claude Code to configure credentials.${NC}"
- echo ""
- else
- echo -e "${GREEN}All good! Run /homelab-core:health in Claude Code to verify service connectivity.${NC}"
- echo ""
- fi
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.