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

- [x] Initial repository setup
- [x] Finish Up Agent created and deployed
- [x] Agent renamed from "Sysadmin Session Closer" to "Finish Up"
- [x] VPS hostname tracking added to filenames
- [x] 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
```

**Agent Naming Convention:**
- Agent files: `agents/{agent-name}.md`
- Invocation: Match the filename (e.g., "finish-up" agent)
- Session files: `[HOSTNAME]-session-summary.md`

### 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