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

/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

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:

# 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:

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

Downloads

Infrastructure

Utilities and Document Management

Research and Dev Tools

MCP Server Variables

Each external MCP plugin has its own block of server-config vars. See .env.example for the full list. Key patterns:

Commands

Root Commands

/homelab:* Commands

/notebooklm:* Commands

/notebooklm:generate Type Reference

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)

Service Skills (16)

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

10 external MCP repos

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:

---
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:

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:

   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):

   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):

touch commands/new-command.md
ln -sf ~/claude-homelab/commands/new-command.md ~/.claude/commands/new-command.md

Namespaced command (/service:action):

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 above for the full pattern and variable naming conventions).

Verification

Run after any structural change:

./scripts/verify.sh

The verify script checks:

• All required symlinks exist and point to valid targets
• ~/.claude-homelab/.env exists

Additional checks:

# 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

License

MIT