homelab-agents/scripts/README.md

Scripts

Utility scripts for agent installation and project management.

bootstrap-agents.sh

Purpose: Ensures the latest homelab agents and tools are available on any VPS instance.

What it does:

• Clones the homelab-agents repository if not present
• Updates the repository to latest version if it exists
• Installs helper scripts (like init-project)
• Adds scripts to your PATH
• Verifies agents are available for use

Usage:

Run this once on your new VPS:

source <(curl -s http://100.120.125.113:3000/pdm/homelab-agents/raw/branch/main/scripts/bootstrap-agents.sh)

Why use source?

• Uses source instead of bash so PATH updates immediately in your current shell
• init-project and other commands are available right away
• No need to manually run source ~/.bashrc afterward

---

init-project

Purpose: Quickly initialize new VPS projects with automatic Gitea remote configuration and agent setup.

Important: The Gitea repository must be created FIRST on the web UI.

What it does:

1. Creates a new project directory
2. Initializes git repository
3. Sets up git user config
4. Automatically configures SSH remote to your Gitea repo
5. Creates initial main branch
6. Copies agents to .claude/agents/ for Claude Code
7. Provides clear next steps

Workflow:

Step 1: Create Repository on Gitea (First!)

Go to: http://100.120.125.113:3000/repo/create

• Repository name: my-new-app
• Visibility: Public or Private
• Initialize repository: Leave unchecked (init-project will set it up)
• Click "Create Repository"

Step 2: Initialize Local Project

cd ~/projects
init-project my-new-app

Example output:

📁 Creating project directory: my-new-app
🔧 Initializing git repository...
🔗 Configuring Gitea SSH remote...
📚 Setting up Claude Code agents...
✅ Copied 2 agent(s) to .claude/agents/

✅ Project initialized successfully!

📋 Project Details:
   Name: my-new-app
   Directory: /home/pdm/projects/my-new-app
   Remote: git@100.120.125.113:pdm/my-new-app.git
   Branch: main
   Agents: .claude/agents/

🚀 Next steps:
   1. Start working in this directory
   2. Create files and make changes
   3. When done, use the summary agent: .claude/agents/sysadmin-session-closer.md
   4. Agent will automatically commit and push to Gitea (via SSH)

What happens next:

• Work normally in your project directory
• Git remote is already configured to use SSH
• Agents are locally available in .claude/agents/
• When you use the summary agent, it pushes via SSH (no passwords!)
• No more "What's the Gitea remote URL?" prompts!

Project Repository:

Each project gets its own independent Gitea repository:

• Project: my-new-app → Repository: git@100.120.125.113:pdm/my-new-app.git
• Project: project-2 → Repository: git@100.120.125.113:pdm/project-2.git

Projects on the same VPS are separate and independent.

Agent Location:

Agents are available at:

.claude/agents/sysadmin-session-closer.md
.claude/agents/[other-agents].md

Claude Code will automatically find them.

Installation:

init-project is automatically installed by bootstrap-agents.sh to:

~/.homelab-scripts/init-project

It's added to your PATH, so you can run it from anywhere.

---

Workflow Summary

First Time on a VPS

source <(curl -s http://100.120.125.113:3000/pdm/homelab-agents/raw/branch/main/scripts/bootstrap-agents.sh)

For Each New Project

# 1. Go to Gitea and create the repo
# http://100.120.125.113:3000/repo/create

# 2. Initialize project locally
cd ~/projects
init-project my-app
cd my-app
# Start working...

Closing a Session

Use the summary agent at:

.claude/agents/sysadmin-session-closer.md

The agent will:

• Create session summary
• Commit changes
• Push to Gitea via SSH (automated!)