sonarr

Claude Homelab

Claude Code skills, agents, and commands for self-hosted homelab service management. Talk to your Plex server, add movies to Radarr, monitor your Unraid array, check what's downloading — all through natural conversation in Claude Code.

---

Table of Contents

• How It Works
• Install
  • Plugin Path (Claude Code native)
  • Bash Path (fresh machine)
• After Install: First-Time Setup
• Credential Management
• Service Plugins
• Homelab-Core: What Gets Installed
  • Skills
  • Agents
  • Commands
• Repository Structure
• How Skills Work
• How the Plugin System Works
• Bash Path Deep Dive
• Verification
• Adding a New Service Plugin
• Security
• Troubleshooting

---

How It Works

This repo provides two things:

1. A Claude Code plugin marketplace — a private registry of installable plugins, each wrapping a homelab service with skills, scripts, and documentation that Claude understands.

2. A bash install path — a traditional curl | bash installer that clones the repo and symlinks everything into ~/.claude/ so Claude Code discovers it automatically.

Both paths end at the same state: Claude Code knows about your homelab services, has their API wrappers, and can act on natural language requests like "what's currently downloading?" or "add Dune Part Two to Radarr."

Credentials never touch the repo. They live in ~/.claude-homelab/.env (chmod 600), written there during setup, and read at runtime by service scripts.

---

Install

Two paths — pick one.

Plugin Path (Claude Code native)

The plugin path uses Claude Code's built-in plugin system. Plugins are copied to ~/.claude/plugins/cache/ when installed. No git clone, no symlinks.

# Step 1: Register this repo as a plugin marketplace
/plugin marketplace add jmagar/claude-homelab

# Step 2: Install the core plugin (agents, commands, setup wizard, health dashboard)
/plugin install homelab-core@jmagar-claude-homelab

# Step 3: Install only the services you actually run
/plugin install plex@jmagar-claude-homelab
/plugin install radarr@jmagar-claude-homelab
/plugin install sonarr@jmagar-claude-homelab
/plugin install overseerr@jmagar-claude-homelab
/plugin install prowlarr@jmagar-claude-homelab
/plugin install tautulli@jmagar-claude-homelab
/plugin install qbittorrent@jmagar-claude-homelab
/plugin install sabnzbd@jmagar-claude-homelab
/plugin install unraid@jmagar-claude-homelab
/plugin install unifi@jmagar-claude-homelab
/plugin install tailscale@jmagar-claude-homelab
/plugin install zfs@jmagar-claude-homelab
/plugin install gotify@jmagar-claude-homelab
/plugin install linkding@jmagar-claude-homelab
/plugin install memos@jmagar-claude-homelab
/plugin install bytestash@jmagar-claude-homelab
/plugin install paperless-ngx@jmagar-claude-homelab
/plugin install radicale@jmagar-claude-homelab
/plugin install nugs@jmagar-claude-homelab
/plugin install notebooklm@jmagar-claude-homelab
/plugin install gh-address-comments@jmagar-claude-homelab

# Step 4: Bootstrap the credentials file (one-time, plugin path only)
curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/setup-creds.sh | bash

# Step 5: Run the interactive credential wizard inside Claude Code
/homelab-core:setup

Why the separate setup-creds.sh for the plugin path? The plugin path copies files into Claude Code's plugin cache — it doesn't clone the repo to a known location on disk. The setup-creds.sh script creates ~/.claude-homelab/.env (from the template) and installs load-env.sh to ~/.claude-homelab/. This one-time step is needed before the service scripts can read credentials. After that, /homelab-core:setup walks you through filling in the actual values.

Bash Path (fresh machine)

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

This does everything in one shot:

1. Checks that git, jq, and curl are installed
2. Clones the repo to ~/claude-homelab/ (or git pull if it already exists)
3. Runs scripts/setup-creds.sh — creates ~/.claude-homelab/.env and installs load-env.sh
4. Runs scripts/setup-symlinks.sh — symlinks all service plugins, agents, and commands into ~/.claude/
5. Runs scripts/verify.sh — confirms everything is in place
6. Prints next steps

After the script completes, open Claude Code and run:

/homelab-core:setup

---

After Install: First-Time Setup

Regardless of which install path you used, the credential setup step is the same:

/homelab-core:setup