homelab-agents/CLAUDE.md

AI Context File - Homelab Agents

Repository: homelab-agents (shared agent repository) Gitea Location: http://100.120.125.113:3000/pdm/homelab-agents.git Purpose: Centralized repository of Claude Code agents for VPS homelab automation User: pdm

Project Overview

This is a shared repository containing Claude Code agents that can be deployed across multiple VPS instances in the homelab environment. Agents help automate common system administration tasks, session management, and project workflow.

Current Development Phase

• Initial repository setup
• Finish Up Agent created and deployed
• Agent renamed from "Sysadmin Session Closer" to "Finish Up"
• VPS hostname tracking added to filenames
• Installation scripts created
• Agent testing across multiple VPS instances
• Additional specialized agents as needed

Current Phase: Maintenance and deployment Completion: ~70%

Key Decisions & Context

Project Goals & Requirements

Primary Objectives:

• Create reusable Claude Code agents for homelab automation
• Enable consistent session management across multiple VPS instances
• Automate git workflows with Gitea integration
• Preserve session context for seamless work resumption

Must-Have Features:

• Session summary generation with comprehensive context
• Automatic git commit and push to Gitea repositories
• VPS hostname tracking in documentation files
• Easy agent installation on new VPS instances

Architecture & Design

Repository Structure:

.homelab-agents/
├── agents/
│   ├── finish-up.md          # Main session closure agent
│   └── README.md             # Agent documentation
├── scripts/
│   ├── install-agent.sh      # Deploy agent to VPS
│   ├── bootstrap-agents.sh   # Initial setup script
│   └── init-project.sh       # New project initialization
├── session-logs/             # Historical session documentation
└── templates/                # Project templates

File Naming Convention:

• ALL new files: {hostname}-{description}.md (e.g., sys-apps-git-quick-reference.md)
• Agent files: agents/{agent-name}.md (no hostname prefix for shared agents)
• Session files: {hostname}-session-summary.md
• Documentation files: {hostname}-{topic}.md

Important: Always run hostname command to get the current VPS hostname. Never hardcode it.

Technical Decisions

Gitea Integration:

• Base URL: http://100.120.125.113:3000
• Organization: pdm
• Repository auto-detection based on current working directory
• Support for both shared repo (homelab-agents) and project-specific repos

Hostname Tracking:

• Uses hostname command to identify VPS
• Embedded in session summary filenames
• Helps track which VPS was used for each work session

Agent Installation:

• Centralized in this repository
• Scripts pull agents to VPS ~/.homelab-agents directory
• Consistent deployment across all VPS instances

Implementation Notes

Finish Up Agent Features:

• Comprehensive session summary generation
• Automatic README.md and CLAUDE.md updates
• Git workflow automation (commit + push)
• Repository type detection (shared vs project-specific)
• VPS hostname in all generated filenames
• Optional Gitea repository auto-creation with API token

Installation Process:

1. Clone homelab-agents to VPS: git clone http://100.120.125.113:3000/pdm/homelab-agents.git ~/.homelab-agents
2. Run bootstrap script: ~/.homelab-agents/scripts/bootstrap-agents.sh
3. Agents become available in Claude Code

Gitea Integration

Repository Pattern:

• Shared agents: http://100.120.125.113:3000/pdm/homelab-agents.git
• VPS projects: http://100.120.125.113:3000/pdm/{project-name}.git

Authentication:

• SSH keys configured for git operations
• Optional API token for automatic repository creation

Session History

Session 2025-11-28

• Phase: Verification and status check
• VPS: 108-system-apps
• Repository: homelab-agents
• Accomplishments:
  • Verified Finish Up Agent rename completed (previously in commit 1602733)
  • Confirmed VPS hostname tracking feature is implemented
  • Validated Gitea synchronization status
  • Created CLAUDE.md for future context preservation
• Key Decisions:
  • No changes needed - all requested features already implemented
  • Session summary filename format updated: [HOSTNAME]-session-summary.md (project name removed as redundant)
• Next Steps (Prioritized):
  • Test Finish Up Agent on this VPS to verify proper operation
  • Consider deploying agents to additional VPS instances
  • Document any VPS-specific configurations

Notes for Future Sessions

When Working in homelab-agents:

• This is a SHARED repository - changes affect all VPS instances
• Always test agents before pushing to Gitea
• Use descriptive commit messages indicating agent changes
• Mark commits with "[homelab-agents]" prefix

When Installing on New VPS:

1. Clone this repository to ~/.homelab-agents
2. Run scripts/bootstrap-agents.sh
3. Configure SSH keys for Gitea (see VPS-SSH-KEY-SETUP.md)
4. Optional: Set GITEA_API_TOKEN for auto-repo creation

VPS Instances Using This Repository:

• 108-system-apps (current)
• [Add other VPS hostnames as they're configured]

Quick Reference

Repository URL: http://100.120.125.113:3000/pdm/homelab-agents.git Clone Command: git clone http://100.120.125.113:3000/pdm/homelab-agents.git ~/.homelab-agents Gitea Web UI: http://100.120.125.113:3000/pdm/homelab-agents Branch: main Owner: pdm