diff --git a/README.md b/README.md
new file mode 100644
index 0000000..229abc8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# Claude Code Agents
+
+Shared repository for Claude Code AI agents across machines.
+
+## 📦 Contents
+
+This repository contains 13 specialized Claude agents:
+
+### Core Agents
+- **documentation-keeper** - Automatically updates server documentation when services change
+- **homelab-optimizer** - Analyzes homelab infrastructure and provides optimization recommendations
+
+### GSD (Get Shit Done) Agent System
+Complete workflow system for structured project development:
+
+- **gsd-project-researcher** - Researches domain ecosystem before roadmap creation
+- **gsd-roadmapper** - Creates project roadmaps with phase breakdown
+- **gsd-phase-researcher** - Researches implementation approaches before planning
+- **gsd-planner** - Creates executable phase plans with task breakdown
+- **gsd-plan-checker** - Verifies plans will achieve phase goals
+- **gsd-executor** - Executes plans with atomic commits and state management
+- **gsd-verifier** - Verifies phase goal achievement through analysis
+- **gsd-integration-checker** - Verifies cross-phase integration and E2E flows
+- **gsd-debugger** - Investigates bugs using scientific method
+- **gsd-codebase-mapper** - Explores codebase and writes structured analysis
+
+## 🚀 Setup on New Machine
+
+### Initial Clone
+```bash
+# Clone to Claude's agents directory
+git clone https://gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents
+
+# Or if directory exists, pull into it
+cd ~/.claude/agents
+git init
+git remote add origin https://gitea.pressmess.duckdns.org/admin/claude-agents.git
+git pull origin main
+```
+
+### Configure Git
+```bash
+git config --global user.name "admin"
+git config --global user.email "admin@server-ai.local"
+```
+
+## 🔄 Syncing Changes
+
+### Push Changes
+```bash
+cd ~/.claude/agents
+git add .
+git commit -m "Description of changes"
+git push origin main
+```
+
+### Pull Changes
+```bash
+cd ~/.claude/agents
+git pull origin main
+```
+
+### Quick Sync Script
+```bash
+# Add to ~/.bashrc or create ~/sync-agents.sh
+sync-agents() {
+    cd ~/.claude/agents
+    git pull origin main
+    echo "✓ Agents synced from Gitea"
+}
+```
+
+## 📝 Adding New Agents
+
+1. Create new agent file: `nano ~/.claude/agents/my-new-agent.md`
+2. Commit and push:
+```bash
+cd ~/.claude/agents
+git add my-new-agent.md
+git commit -m "Add my-new-agent: description"
+git push origin main
+```
+
+## 🌐 Repository
+
+**Gitea URL**: https://gitea.pressmess.duckdns.org/admin/claude-agents
+
+**Clone URL**: `https://gitea.pressmess.duckdns.org/admin/claude-agents.git`
+
+## 🔐 Authentication
+
+Uses admin credentials for Gitea access. Credentials are stored in git remote URL (URL-encoded).
+
+To update credentials:
+```bash
+cd ~/.claude/agents
+git remote set-url origin https://admin:PASSWORD@gitea.pressmess.duckdns.org/admin/claude-agents.git
+```
+
+## 📚 Related
+
+- **Skills sync**: Managed by [Skillshare](https://github.com/runkids/skillshare) at `~/.claude/skills/`
+- **Server docs**: `/home/jon/SERVER-DOCUMENTATION.md`