Claude OS Playbook: Using Claude Code as an Ansible Replacement

The Project

https://github.com/danielrosehill/Claude-OS-Playbook

Anyone who has spent time maintaining Ansible playbooks knows the pain: package names shift between distro versions, PPAs go stale, shell scripts break silently, and keeping idempotent YAML working across Ubuntu releases becomes a perpetual maintenance tax. This project takes a fundamentally different approach to environment provisioning by replacing Ansible with Claude Code slash commands and a network of specialized subagents.

The core idea is simple: describe your desired environment in a human-readable YAML profile, then let Claude Code provision it conversationally, adapting in real time to whatever it finds on the target system. Instead of failing when a package name changes or a repository key rotates, the AI agent can reason about alternatives and ask the user when it hits ambiguity.

How It Works

The template ships with four slash commands that serve as the primary interface:

• /setup — The main entrypoint. It reads a YAML profile, shows a summary of what will be provisioned, asks for confirmation, then delegates to specialized subagents in the correct order.

• /setup-category — Runs a single provisioning category, like /setup-category languages to install only programming language runtimes.

• /verify — Audits the current system against the profile, reporting what matches, what is missing, and what has drifted.

• /export — Snapshots the current environment into a new YAML profile, making it easy to capture a working setup and reproduce it elsewhere.

The Subagent Architecture

When /setup runs, it delegates work to eight specialized subagents, each responsible for a different provisioning domain:

• system-packages — Handles apt, snap, and flatpak installations

• languages — Installs Python via uv, Node via nvm, Go, Rust via rustup, and Java via SDKMAN

• containers — Docker, Docker Compose, and container runtimes

• cli-tools — uv tools, npm globals, pip packages, cargo and go installs

• shell-config — Dotfiles, aliases, and environment variables

• desktop-apps — GUI applications via snap, flatpak, or apt

• services — systemd services, VPNs, and background daemons

• claude-setup — Claude Code commands, agent definitions, and MCP profiles via MCPM

Each agent checks what is already present before installing anything, reports what it changed, and skips items that are already satisfied. This gives you Ansible-like idempotency without the brittle YAML.

Profile-Driven Configuration

The environment specification lives in YAML profiles under the profiles/ directory. The included example profile is based on my own Ubuntu workstation and covers a comprehensive full-stack development setup: system packages via apt, snap, and flatpak (including tools like neovim, imagemagick, and virt-manager), language runtimes for Python 3.13 (via uv), Node 22 (via nvm), Go, and Rust, plus GUI apps like Discord, Postman, Kdenlive, and Draw.io.

The template also ships with a minimal profile for those who want a lighter starting point. You copy the example, rename it, and edit it to match your desired environment. The profiles are designed to be self-documenting, with notes fields explaining why each tool is installed with a particular method.

Why This Matters

This is a GitHub template repository, so anyone can click "Use this template" and start customizing. The slash commands and agents are all plain Markdown files, which means they are easy to read, edit, and extend without learning a DSL or fighting with YAML indentation. The CLAUDE.md at the project root establishes conventions like checking before installing, never running destructive commands without confirmation, and preferring the OS-native package manager.

The broader pattern here is interesting: rather than encoding system administration logic in a configuration management language, you describe the desired state in a simple data format and let an AI agent figure out the imperative steps. The agent can adapt to package name changes, offer alternatives when something is unavailable, and produce a clear report of everything it did. It is a fundamentally different model from traditional infrastructure-as-code, and one that I think works especially well for personal workstation provisioning where the stakes are lower and the environments are more varied.