ux

claudefiles

Portable Claude Code configuration. Like dotfiles, but for Claude.

At the moment, this repo is opinionated toward Claude Code. It does not support other AI coding assistants.

About

Developers have been versioning their dotfiles for decades. A .bashrc, .vimrc, .gitconfig. These tiny files define how your tools behave. Clone them onto a new machine and it feels like your personal computer.

Claudefiles applies the same idea to Claude Code. Skills, commands, hooks, sounds, and settings, versioned in a repo, deployed to ~/.claude/ on any machine. Your AI assistant, configured exactly how you want it, everywhere.

Why this exists

I use Claude primarily for two things: managing my personal knowledge system (Obsidian) and writing software in Node.js, Rust and Golang. This repo is a minimal, portable setup that helps me bootstrap new systems. VMs, servers, side projects, multi-agent architectures where Claude runs not just on my personal machine but across environments. Clone, run Claude, done.

The design assumes Claude is smart enough to read a YAML manifest and configure itself. No complex bash installers. The /setup command reads claudefiles.yaml and does the right thing. Copies files, merges settings, resolves platform differences. This is a shift from imperative scripting into Agentic setup.

Installing

Requirements

• Claude Code (CLI)
• git
• jq — hooks parse tool input JSON
• macOS or Linux
• gh (optional) — only needed for preview-markdown.sh

Quick install

curl -fsSL https://raw.githubusercontent.com/koolamusic/claudefiles/main/bootstrap.sh | bash

This clones the repo to ~/.claudefiles. Then run Claude to deploy:

cd ~/.claudefiles && claude "/setup"

Manual install

git clone [email protected]:koolamusic/claudefiles.git ~/.claudefiles
cd ~/.claudefiles && claude "/setup"

What /setup does

/setup is a project-level command (.claude/commands/setup.md). It only works when Claude is running inside the claudefiles repo, which is why the install steps above cd into it first.

The command reads claudefiles.yaml (the manifest) and:

1. Detects your platform (macOS or Linux)
2. Copies skills, commands, hooks, and sounds to ~/.claude/
3. Smart-merges settings into ~/.claude/settings.json (backs up existing settings first)
4. Resolves platform-specific template variables (e.g., afplay vs aplay for sound)

What's included

Skills

Skill	Description	Source
agent-browser	Browser automation with Playwright	vercel-labs/agent-browser
brainstorming	Structured brainstorming sessions	obra/superpowers
breadboarding	UI breadboarding (Shape Up)	rjs/shaping-skills
docx	Word document creation and editing	anthropics/skills
golang-best-practices	Go concurrency, microservices, gRPC, generics	Jeffallan/claude-skills
nestjs-best-practices	NestJS architecture and patterns	Kadajett/agent-nestjs-skills
pdf	PDF processing and manipulation	anthropics/skills
pptx	PowerPoint creation	anthropics/skills
react-best-practices	React/Next.js performance patterns	vercel-labs/agent-skills
rust-best-practices	Idiomatic Rust, ownership, error handling, testing	apollographql/skills
shaping	Shape Up project shaping	rjs/shaping-skills
skill-creator	Create and test new skills (TDD methodology)	anthropics/skills + obra/superpowers
xlsx	Excel spreadsheet processing	anthropics/skills

Commands

Shorthand	What it does	Scope
/setup	Install claudefiles to ~/.claude/	Project-level (runs inside this repo only)
/gcw	Git commit with conventional commit format	Global (deployed to ~/.claude/commands/)
/gitconfig	Configure git — SSH keys, aliases, templates, hooks (local or global)	Global (deployed to ~/.claude/commands/)

Hooks

Hook	Trigger	What it does
shaping-ripple	PostToolUse (Write|Edit)	When editing a file with shaping: true frontmatter, prints a ripple-check reminder to keep tables, diagrams, and requirements in sync. Silent for all other files.

Sounds